@johpaz/hive-sdk 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+## 0.1.5
+
+Sincronización del SDK con el runtime de agentes de `hive`. **Trae rupturas de
+API** (permitidas en 0.x, pero léelas antes de actualizar): el SDK y hive habían
+divergido hasta compartir sólo 87 de 224 nombres de archivo, y quien instalaba
+`@johpaz/hive-sdk` recibía un runtime más viejo y con bugs que en hive ya estaban
+arreglados.
+
+### Corregido
+
+- **Las caídas del provider ya no se guardan como respuestas del agente.**
+  `callLLM` devolvía `{ content: "[LLM Error] …", stop_reason: "error" }` y nadie
+  chequeaba `stop_reason`: el texto del error se persistía con `addMessage` y —
+  peor — la compactación lo guardaba como **el resumen permanente** que reemplaza
+  N mensajes de historial. `LLMResponse` ahora tiene un campo `error` tipado y hay
+  guardas en el loop, en la síntesis terminal y en la compactación.
+- **HTTP 404/410 se distinguen del resto.** Un modelo retirado por el proveedor
+  produce un mensaje accionable con `error.modelUnavailable`, en vez de un error
+  opaco y reintentos que no pueden funcionar.
+- **Las claves de modelo ya no colisionan.** Dos providers que sirven el mismo
+  modelo (`z-ai/glm-5.2` bajo NVIDIA y bajo OpenRouter) se pisaban la fila. Los
+  cuatro revendedores (`nvidia`, `openrouter`, `opencode-go`, `modelscope`,
+  `groq`) prefijan sus ids; el prefijo no llega al cable.
+- **Los precios salen de la base.** `MODEL_PRICING` era un mapa hardcodeado de
+  ~62 entradas en paralelo al catálogo, y mantener dos listas fallaba en silencio.
+  Ahora el precio vive en la fila del modelo (`input_per_1m` / `output_per_1m`) y
+  un modelo sin tarifa avisa una vez en vez de reportar $0 como si fuera gratis.
+- **`createAgent` honra su configuración.** `provider`, `model`, `maxIterations`,
+  `skills` y `workspace` se aceptaban y se descartaban: el agente corría con lo
+  que hubiera en la base. Ahora se persisten en la fila del agente.
+- **Las tools de la app son usables.** `defineTool` registraba la declaración pero
+  no el ejecutor, así que una llamada moría con "no matching executor found". Y
+  aunque lo tuviera, el índice de capacidad no se llenaba nunca por la vía del
+  SDK, así que el agente quedaba limitado al loadout mínimo para siempre.
+- **El selector ya no descarta tools que el índice sí encontró.** `selectTools`
+  resolvía los resultados contra `CORE_TOOL_CATALOG` mientras el índice se
+  construía con ése **más** la colección `tools`: una tool registrada en runtime
+  podía puntuar primera en BM25 y aun así nunca ofrecerse al modelo.
+- **`Scratchpad` escribe el documento completo.** Compartía colección e id con
+  `conversation-store` pero guardaba un doc sin `source`, `createdAt` ni `seq`,
+  así que sus notas se ordenaban mal dentro del prompt.
+- **La suite de tests dejó de escribir en la base real del usuario.** Un preload
+  fija `HIVE_DB_PATH=":memory:"` antes de que cargue cualquier módulo.
+- **`tool_choice` de Mistral.** Estaba en `"any"`, que según docs.mistral.ai
+  *fuerza* una llamada a tool en cada turno; ahora es `"auto"`.
+
+### Ruptura
+
+| Antes | Ahora |
+|---|---|
+| `initializeDatabase()`, `dbService`, `getDb()` | `ensureHiveDb()`, `col()` |
+| `seedHiveDB()` | `seedAllData()` (lo llama `ensureHiveDb`) |
+| `getAverageTokenCost()`, `getProviderPricing()`, `estimateCostForTokens()` | `calculateCost()` |
+| `new EthicsGuard(db)`, métodos sync | `new EthicsGuard()`, métodos async |
+| `new CronScheduler(db, handler)` | `new CronScheduler(handler)` |
+| `new Scratchpad(db)` | `new Scratchpad()` |
+| subpath `./ace` | `curator`, `reflector`, `tracer` desde `./agent` |
+| subpath `./agent/selectors` | selectores desde `./agent` |
+| `AgentConfig.provider: "openai" \| "anthropic" \| "gemini" \| "ollama"` | los 16 providers del catálogo |
+| `api_request` con `auth`, `body` objeto, `timeoutMs` | headers, `body` string, `timeout_ms` |
+| evento de canvas `canvas:render` | `canvas:node_add` / `node_update` / `edge_*` |
+
+Módulos eliminados: `auth/` (sin un solo import), `agent/ContextGuard.ts` y
+`agent/Hooks.ts` (muertos), `storage/SQLiteStorage.ts`, `storage/schema.ts`,
+`storage/hiveSeed.ts`, `scheduler/dag/` (copia byte-idéntica de `swarm/`),
+`swarm/WorkerPool.ts` (copia rezagada de `scheduler/integration.ts`),
+`swarm/AgentBus.ts` y `swarm/EventBus.ts` (duplicaban `events/`), y las tools
+`canvas/`, `codebridge/`, `meeting/`, `projects/`, `voice/`.
+
+`harness/` pasó de tener implementación propia a ser un barrel sobre la
+implementación única. El subpath `@johpaz/hive-sdk/harness` exporta lo mismo.
+
+### Agregado
+
+- 16 providers LLM con `OpenAICompatBase`, incluidos `nvidia`, `z-ai`,
+  `modelscope`, `opencode-go`, `minimax`, `hiveagents`.
+- Catálogo sembrado de 18 providers y 106 modelos con precio, actualizable
+  editando `SEED_DATA.models`: las filas de catálogo se borran y se recrean en
+  cada arranque, preservando qué modelo tenía activo el usuario.
+- `registerAppTool()` / `clearAppTools()` como punto de extensión del registry.
+- `catalogModelKey()`, `wireModelId()`, `isResellerProvider()`.
+- `callLLM` y los tipos de `llm-client` en la superficie pública: antes sólo se
+  exportaba el wrapper `AgentRunner`.
+- `bun run skills:bundle` regenera el catálogo de skills desde los `SKILL.md`
+  (el generador apuntaba a una ruta que no existe en este repo).
+- Subpaths `./scheduler`, `./workers` y `./events`.
+- De 18 a 44 archivos de test (77 → 314 casos), incluyendo agent loop, context
+  compiler, compactación, seed, precios y claves de modelo, que no tenían ninguno.
+
+### Corregido en el CLI
+
+`init`, `run`, `test` y `trace` importaban `@hive/core`, un nombre de workspace
+que no está publicado en npm: los cuatro comandos estaban rotos para cualquier
+usuario. `hives test` además hacía glob sobre `packages/core/src/**`, rutas del
+repo del SDK y no del proyecto donde se ejecuta.

package/README.md

@@ -1,30 +1,26 @@
-# Documentación — Hive SDK
+# @johpaz/hive-sdk
 
-> **Hive Agent Harness SDK** — Build, deploy, and scale AI agent applications with multi-channel support, Bun Workers, and swarm orchestration.
+> **Hive Agent Harness SDK** — construí, desplegá y escalá aplicaciones de agentes de IA, con soporte multi-canal, Bun Workers y orquestación en swarm.
 
-## Documentos
+[![npm](https://img.shields.io/npm/v/@johpaz/hive-sdk)](https://www.npmjs.com/package/@johpaz/hive-sdk)
 
-| Documento | Descripción |
-|-----------|-------------|
-| [API-AGENTS.md](docs/API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, LLM Providers |
-| [API-DAG-SCHEDULER.md](docs/API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, TaskNode, Estrategias, Presets |
-| [API-WORKERS-EVENTS.md](docs/API-WORKERS-EVENTS.md) | **Bun Workers**, createWorker, WorkerPool, AgentBus, EventBus, Canvas |
-| [API-TOOLS-SKILLS-CHANNELS.md](docs/API-TOOLS-SKILLS-CHANNELS.md) | Tools, Skills, MCP, **Gateway**, **Channels**, **Tool Runtime**, Storage |
-| [API-CONTEXT-COMPILER.md](docs/API-CONTEXT-COMPILER.md) | Context Compiler, Message History, Scratchpad, EthicsGuard, ACE |
-| [TEMPLATE-HIVE-APP.md](docs/TEMPLATE-HIVE-APP.md) | **Template hive-app** — estructura, opciones, personalización |
+```bash
+bun add @johpaz/hive-sdk
+```
 
 ## ¿Qué es Hive SDK?
 
 **Hive SDK es un Agent Harness**: un marco de trabajo completo para construir, desplegar y escalar aplicaciones de agentes de IA. A diferencia de un simple wrapper de LLM, un *harness* provee todo lo necesario para que un agente opere en producción:
 
-- **Agentes**: ciclo ReAct, selección dinámica de tools/skills vía FTS5, múltiples providers (OpenAI, Anthropic, Gemini, Ollama).
-- **Tools**: 70+ tools incluidas — filesystem, web search, browser automation (`agent-browser`), APIs (`api_request`), canvas, voz, office, cron.
-- **Skills**: workflows reutilizables con `defineSkill` y `SkillLoader`.
+- **Agentes**: ciclo ReAct nativo con checkpoint durable, 16 providers LLM y descubrimiento de tools/skills por búsqueda BM25.
+- **Catálogo**: 18 providers y 106 modelos sembrados, cada uno con su precio por millón de tokens — una sola fuente de verdad para el costo.
+- **Tools**: 58 tools incluidas — filesystem, web search, browser automation (`agent-browser`), APIs (`api_request`), a2ui, office, cron, delegación.
+- **Skills**: 23 workflows bundled, más los tuyos con `defineSkill` y `SkillLoader`.
 - **Canales**: Telegram, Discord, WhatsApp, Slack y WebChat con `ChannelManager`.
 - **Swarm**: orquestación multi-agente con `DAGScheduler`, `TaskGraph` y `WorkerPool`.
 - **Runtime**: ejecución paralela de tools vía Bun Workers.
 - **Gateway**: servidor HTTP/WebSocket para exponer agentes como API.
-- **Memoria y estado**: SQLite + FTS5, scratchpad, context compiler.
+- **Memoria y estado**: HiveDB (colecciones + índice BM25), scratchpad, context compiler con compactación.
 
 Con Hive SDK no montas un agente desde cero: **enganchas tu lógica de negocio en un harness ya armado**.
 
@@ -67,17 +63,19 @@ bun run dev
 
 ```typescript
 import { createAgent, defineTool } from "@johpaz/hive-sdk";
+import { z } from "zod";
 
 const tool = defineTool({
   name: "saludar",
-  description: "Saluda a alguien",
+  description: "Saluda a alguien por su nombre",
+  schema: z.object({ nombre: z.string().describe("a quién saludar") }),
   execute: async (args: { nombre: string }) => `¡Hola ${args.nombre}!`,
 });
 
 const agent = await createAgent({
   name: "asistente",
-  provider: "openai",
-  model: "gpt-4o-mini",
+  provider: "openai",       // cualquiera de los 16 del catálogo
+  model: "gpt-5.6-luna",    // tiene que existir en el catálogo sembrado
   tools: [tool],
 });
 
@@ -85,6 +83,11 @@ const respuesta = await agent.run("Saluda a Juan");
 console.log(respuesta);
 ```
 
+`createAgent` abre HiveDB, siembra el catálogo de providers y modelos, persiste
+la configuración en la fila del agente y deja tus tools indexadas para que el
+modelo pueda descubrirlas. El `schema` de Zod es lo que se traduce a los
+parámetros que ve el LLM — sin él, la tool se ofrece sin argumentos.
+
 ### 3. Crear un worker especializado
 
 ```typescript
@@ -135,15 +138,26 @@ console.log(`Gateway at http://127.0.0.1:18790`);
 ## Variables de Entorno
 
 ```bash
-HIVE_DATA_DIR=./data          # Directorio de datos SQLite
+HIVE_HOME=~/.hive             # Directorio de datos (HiveDB vive en <HIVE_HOME>/data)
+HIVE_DB_PATH=                 # Ruta explícita de la base; ":memory:" para efímera
 HIVE_HOST=127.0.0.1           # Gateway host
 HIVE_PORT=18790               # Gateway port
-OPENAI_API_KEY=sk-...         # OpenAI
-ANTHROPIC_API_KEY=sk-ant-...  # Anthropic
-GOOGLE_API_KEY=...            # Gemini
 LOG_LEVEL=info                # debug | info | warn | error
 ```
 
+La API key de cada provider se guarda cifrada en la base. Como alternativa, el
+SDK cae a `<PROVIDER>_API_KEY` del entorno, en mayúsculas y con el id del
+provider tal cual:
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...            # provider "gemini"
+MODELSCOPE_API_KEY=ms-...
+NVIDIA_API_KEY=nvapi-...
+OPENROUTER_API_KEY=sk-or-...
+```
+
 ## Tests
 
 ```bash
@@ -154,7 +168,48 @@ bun test
 bun test --timeout 60000
 ```
 
+La suite usa una base efímera (`HIVE_DB_PATH=":memory:"`, fijado en
+`test/preload.ts`) para no escribir en la del usuario.
+
+## Publicar
+
+```bash
+# 1. Actualizar archivos, sin tocar git — revisá el diff
+bun run version:set 0.1.6
+
+# 2. Cuando estés conforme: typecheck + tests + commit + tag + push
+bun run version:set 0.1.6 --push
+
+# Preview que no se instala por defecto
+bun run version:set 0.2.0-rc.1 --push --npm-tag=next
+```
+
+`--push` corre `typecheck` y `bun test` antes de tocar git, y pide confirmación
+explícita. El tag `vX.Y.Z` es lo que dispara `.github/workflows/publish.yml`, que
+publica **sólo el paquete raíz** (`packages/*` son workspaces internos). El
+dist-tag viaja en el mensaje del tag, así que `--npm-tag=next` publica bajo `next`
+y no mueve `latest`.
 
+El script aborta si la versión ya existe en npm — republicar da 403 — y si el tag
+local ya existe.
 
+```bash
+npm view @johpaz/hive-sdk dist-tags   # verificar después del release
+```
+
+## Documentación
 
-*Documentación Hive SDK v0.0.18*
+| Documento | Descripción |
+|-----------|-------------|
+| [API-AGENTS.md](docs/API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, los 16 LLM Providers |
+| [API-CONTEXT-COMPILER.md](docs/API-CONTEXT-COMPILER.md) | Context Compiler, historial, Scratchpad, EthicsGuard, ACE |
+| [API-TOOLS-SKILLS-CHANNELS.md](docs/API-TOOLS-SKILLS-CHANNELS.md) | Tools, Skills, MCP, Gateway, Channels, Tool Runtime, Storage |
+| [API-DAG-SCHEDULER.md](docs/API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, TaskNode, estrategias, presets |
+| [API-WORKERS-EVENTS.md](docs/API-WORKERS-EVENTS.md) | Bun Workers, createWorker, WorkerPool, AgentBus, EventBus, Canvas |
+| [HIVE-HARNESS.md](docs/HIVE-HARNESS.md) | Ejecución durable: cola de jobs, checkpoints, leases, proof packets |
+| [TEMPLATE-HIVE-APP.md](docs/TEMPLATE-HIVE-APP.md) | Template `hive-app` — estructura, opciones, personalización |
+| [CHANGELOG.md](CHANGELOG.md) | Cambios por versión |
+
+---
+
+*Hive SDK v0.1.5 — MIT*

package/bunfig.toml

@@ -1,7 +1,9 @@
 [test]
-preload = ["./test/setup-db.ts"]
+# Fija HIVE_DB_PATH=":memory:" antes de que cargue cualquier módulo — ver test/preload.ts.
+# Sin esto la suite abre la base real del usuario (~/.hive/data/hive) y le escribe.
+preload = ["./test/preload.ts"]
 timeout = 30000
 randomize = false
 
 [install]
-registry = "https://registry.npmjs.org/"
+registry = "https://registry.npmjs.org/"

package/docs/API-AGENTS.md

@@ -27,8 +27,8 @@ const agent = await createAgent(config: AgentConfig): Promise<Agent>
 ```typescript
 interface AgentConfig {
   name: string;
-  model?: string;                           // default: gpt-4o-mini
-  provider?: "openai" | "anthropic" | "gemini" | "ollama";
+  model?: string;         // id tal como lo nombra su dueño, ej. "claude-opus-5"
+  provider?: Provider;    // cualquiera de los 16 del catálogo
   systemPrompt?: string;
   tools?: ToolDefinition[];                 // Tools custom
   skills?: SkillDefinition[];               // Skills custom
@@ -43,6 +43,21 @@ interface AgentConfig {
 }
 ```
 
+La config **se persiste en la fila del agente**, que es de donde el loop resuelve
+provider y modelo en cada turno. Consecuencias que conviene tener presentes:
+
+- `model` exige `provider`: el mismo modelo lo sirven varios providers y la clave
+  del catálogo depende de cuál. Sin provider, `createAgent` lanza.
+- El modelo tiene que existir en `SEED_DATA.models`, o lanza con el nombre del
+  provider al que no pertenece.
+- `name` deriva el id del agente (`"Mi Agente"` → `mi_agente`), así que dos
+  `createAgent` con el mismo nombre comparten fila e historial.
+- Las tools pasadas acá quedan registradas **y** indexadas, así que el modelo
+  puede descubrirlas con `search_knowledge` como a las nativas.
+
+> Hasta 0.1.5 `provider`, `model`, `maxIterations`, `skills` y `workspace` se
+> aceptaban y se descartaban: el agente corría con lo que hubiera en la base.
+
 ### Agent
 
 ```typescript
@@ -82,7 +97,7 @@ import { createAgent, defineTool } from "@johpaz/hive-sdk";
 const agent = await createAgent({
   name: "asistente",
   provider: "openai",
-  model: "gpt-4o-mini",
+  model: "gpt-5.6-luna",
   systemPrompt: "Eres un asistente útil.",
 });
 
@@ -208,7 +223,7 @@ const result = await runAgentIsolated({
 
 ## Tool Selector
 
-Selección automática de tools basada en FTS5.
+Selección automática de tools por búsqueda BM25 sobre el índice de capacidad.
 
 ```typescript
 import { selectTools, CORE_TOOL_CATALOG } from "@johpaz/hive-sdk";
@@ -229,22 +244,22 @@ const MIN_RELEVANCE_THRESHOLD = -30;
 
 ### CORE_TOOL_CATALOG
 
-~50 tools built-in organizadas por categoría:
-
-| Categoría | Descripción |
-|-----------|-------------|
-| filesystem | read, write, edit, delete, list, glob |
-| web | web_search, web_fetch, browser automation |
-| projects | project/task CRUD |
-| cron | Croner-based scheduling |
-| cli | Shell command execution |
-| agents | Agent management, task delegation |
-| canvas | UI rendering, A2UI |
-| codebridge | Code execution bridge |
-| voice | TTS/STT |
-| core | save_note, notify, report_progress |
-| office | PDF, DOCX, XLSX, PPTX |
-| meeting | Meeting management |
+58 tools built-in organizadas por categoría:
+
+| Categoría | # | Descripción |
+|-----------|---|-------------|
+| agents | 15 | delegación (`task_delegate`, `task_revise`), memoria, catálogo de modelos |
+| web | 10 | `web_search`, `web_fetch`, automatización de browser, `artifact_inspect` |
+| cron | 8 | scheduling con Croner |
+| office | 8 | PDF, DOCX, XLSX, PPTX |
+| filesystem | 7 | read, write, edit, delete, list, glob, exists |
+| a2ui | 4 | superficies de UI generadas por el agente |
+| core | 4 | `save_note`, `notify`, `report_progress`, `search_knowledge` |
+| cli | 1 | ejecución de comandos |
+| api | 1 | `api_request` |
+
+Las categorías `projects`, `canvas`, `codebridge`, `voice` y `meeting`
+desaparecieron en 0.1.5 junto con sus tools.
 
 ---
 
@@ -266,19 +281,55 @@ const minimal = getMinimalSkills();
 
 ### Providers Soportados
 
-| Provider | Modelos | Streaming |
-|----------|---------|-----------|
-| openai | gpt-4o, gpt-4o-mini | ✅ |
-| anthropic | claude-sonnet, claude-haiku | ✅ |
-| gemini | gemini-2.5-flash | ✅ |
-| ollama | modelos locales | ✅ |
+16 providers, todos sembrados con su catálogo de modelos y su precio por millón
+de tokens. `provider` en `createAgent` acepta cualquiera de estos ids.
+
+| Provider | Adapter | Notas |
+|----------|---------|-------|
+| `anthropic` | nativo | extended thinking, round-trip de thinking blocks |
+| `gemini` | nativo | REST v1beta |
+| `ollama` | nativo | modelos locales, flag `think` |
+| `openai` | OpenAI-compat | Sol / Terra / Luna |
+| `deepseek`, `kimi` | OpenAI-compat | round-trip de `reasoning_content` |
+| `mistral`, `groq`, `qwen`, `minimax` | OpenAI-compat | |
+| `z-ai` | OpenAI-compat | sirve en `/api/paas/v4`, no en `/v1` |
+| `hiveagents` | OpenAI-compat | |
+| `nvidia`, `openrouter`, `opencode-go`, `modelscope` | OpenAI-compat | **revendedores** |
+
+Los cuatro revendedores prefijan sus ids de modelo con su propio id de provider
+(`modelscope/Qwen/Qwen3.5-397B-A17B`), porque sirven modelos de terceros que se
+solapan entre sí y la colección `models` se indexa por una sola clave. El
+prefijo no llega al cable: el adapter lo quita antes del request.
+
+```typescript
+import { catalogModelKey, wireModelId } from "@johpaz/hive-sdk";
+
+catalogModelKey("modelscope", "Qwen/Qwen3.5-397B-A17B"); // modelscope/Qwen/Qwen3.5-397B-A17B
+wireModelId("modelscope", "modelscope/Qwen/Qwen3.5-397B-A17B"); // Qwen/Qwen3.5-397B-A17B
+```
+
+### Errores del provider
+
+`callLLM` nunca lanza: devuelve `stop_reason: "error"` con un campo `error`
+tipado. Chequealo antes de persistir `content` en cualquier lado — es texto para
+mostrar, no salida del modelo.
+
+```typescript
+const response = await callLLM({ ... });
+
+if (response.stop_reason === "error") {
+  console.error(response.error?.message);
+  // HTTP 404/410 → el proveedor retiró el modelo; reintentar no sirve.
+  if (response.error?.modelUnavailable) selectAnotherModel();
+}
+```
 
 ### callLLM
 
 ```typescript
 import { callLLM, resolveProviderConfig } from "@johpaz/hive-sdk";
 
-const config = await resolveProviderConfig("openai", "gpt-4o-mini");
+const config = await resolveProviderConfig("openai", "gpt-5.6-luna");
 
 const response = await callLLM({
   provider: config.provider,

package/docs/API-CONTEXT-COMPILER.md

@@ -41,7 +41,7 @@ El Context Compiler implementa 4 estrategias de Context Engineering:
 | Estrategia | Descripción |
 |------------|-------------|
 | **ESCRIBIR** | Guardar información fuera del contexto (Scratchpad, trazas) |
-| **SELECCIONAR** | Traer solo lo relevante (FTS5 tool/skill/playbook selection) |
+| **SELECCIONAR** | Traer solo lo relevante (selección BM25 de tool/skill/playbook) |
 | **COMPRIMIR** | Reducir tokens (compaction, tool result clearing) |
 | **AISLAR** | Separar contextos por agente (workers reciben contexto mínimo) |
 
@@ -114,56 +114,53 @@ Memoria temporal por hilo de conversación.
 
 ```typescript
 import { Scratchpad } from "@johpaz/hive-sdk";
-import { getDb } from "@johpaz/hive-sdk";
 
-const db = getDb();
-const pad = new Scratchpad(db);
+const pad = new Scratchpad();
 
-// Escribir nota
-pad.write("thread-1", "mi-nota", "contenido");
-
-// Leer nota
-const value = pad.read("thread-1", "mi-nota");
-
-// Listar notas de un hilo
-const all = pad.list("thread-1");
-
-// Eliminar nota
-pad.delete("thread-1", "mi-nota");
-
-// Limpiar todas las notas de un hilo
-pad.clear("thread-1");
+await pad.write("thread-1", "mi-nota", "contenido");
+const value = await pad.read("thread-1", "mi-nota");
+const all = await pad.list("thread-1");   // { "mi-nota": "contenido" }
+await pad.delete("thread-1", "mi-nota");
+await pad.clear("thread-1");
 ```
 
+El scratchpad se inyecta al system prompt en cada turno bajo
+`# SCRATCHPAD (Persistent Notes)`, comprimido con TOON. La clase es una fachada
+sobre las funciones de `conversation-store`: hasta 0.1.5 tenía implementación
+propia y, como usaba el mismo id, escribía las mismas filas con un documento
+incompleto que rompía el orden por recencia.
+
 ---
 
 ## EthicsGuard
 
-Guardián de reglas de calidad de respuesta desde la base de datos.
+Capa opcional de reglas de calidad de respuesta, leídas de la colección
+`playbook` (`category: "response_quality"`).
 
 ```typescript
 import { EthicsGuard } from "@johpaz/hive-sdk";
-import { getDb } from "@johpaz/hive-sdk";
 
-const db = getDb();
-const guard = new EthicsGuard(db);
+const guard = new EthicsGuard();
 
-// Obtener reglas
-const rules = guard.getRules();              // Todas
-const rulesForRole = guard.getRules("agent"); // Con FTS5
+const rules = await guard.getRules();                     // todas las activas
+const rulesForRole = await guard.getRules("coordinator"); // filtra por applicable_to
 
-// Inyectar en system prompt
-const prompt = guard.injectIntoPrompt(
-  "Eres un asistente.",
-  rules
-);
+const prompt = guard.injectIntoPrompt("Eres un asistente.", rules);
 
-// Verificar si hay reglas
-if (guard.hasEthicsLayer()) {
+if (await guard.hasEthicsLayer()) {
   console.log("Reglas de calidad activas");
 }
 ```
 
+> El constructor ya no recibe un handle de base y todos los métodos son async:
+> hasta 0.1.5 la clase armaba SQL a mano contra la tabla `playbook` y hacía un
+> JOIN con la tabla virtual `playbook_fts`. Ninguna de las dos existe.
+
+**Esto no es la ética constitucional del agente.** Esa vive en la colección
+`ethics` y la ensambla `buildSystemPrompt()` como primera sección, completa y sin
+comprimir. `EthicsGuard` es un complemento para hosts que quieran inyectar,
+además, reglas aprendidas por ACE.
+
 ---
 
 ## ACE (Tracer, Reflector, Curator)
@@ -178,7 +175,7 @@ import { saveTrace, recordLLMUsage } from "@hive/core/ace";
 // Guardar traza de ejecución
 saveTrace({
   agentId: "analyst",
-  model: "gpt-4o-mini",
+  model: "gpt-5.6-luna",
   messages: 5,
   toolCalls: ["web_search", "read_file"],
   durationMs: 1200,
@@ -188,7 +185,7 @@ saveTrace({
 
 // Registrar uso de LLM
 recordLLMUsage({
-  model: "gpt-4o-mini",
+  model: "gpt-5.6-luna",
   inputTokens: 200,
   outputTokens: 250,
   durationMs: 800,

package/docs/API-TOOLS-SKILLS-CHANNELS.md

@@ -71,7 +71,7 @@ const exec = new ToolExecutor(reg);
 const result = await exec.execute("echo", { msg: "hola" });
 ```
 
-### Tool Selection (FTS5)
+### Tool Selection (BM25)
 
 ```typescript
 import { selectTools, CORE_TOOL_CATALOG } from "@johpaz/hive-sdk";
@@ -120,17 +120,25 @@ Conecta APIs REST con autenticación y métodos HTTP:
 
 ```typescript
 const result = await apiRequestTool.execute({
-  url: "https://api.example.com/items",
   method: "POST",
-  headers: { "X-Custom": "value" },
-  body: { name: "example" },
-  auth: { type: "bearer", token: process.env.API_TOKEN! },
-  timeoutMs: 30000,
+  url: "https://api.example.com/items",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${process.env.API_TOKEN}`,
+  },
+  body: JSON.stringify({ name: "example" }),
+  query_params: { verbose: "1" },
+  timeout_ms: 30000,
 });
 
-// Auth soportada: bearer, basic, api_key (header o query)
+// → { ok, status, statusText, headers, body, contentType, url }
+// `body` viene parseado si la respuesta es JSON, y como string si no.
 ```
 
+Nunca lanza: un fallo de red o un método inválido vuelven como
+`{ ok: false, error }`. No tiene helpers de autenticación — la credencial va
+como un header más.
+
 ---
 
 ## Skills
@@ -168,12 +176,24 @@ const skill = loader.get("file-manager");
 
 ### Skills empaquetadas
 
-El SDK incluye skills empaquetadas para casos comunes. Algunas útiles para web y APIs:
+El SDK incluye 23 skills empaquetadas. Algunas útiles para web y APIs:
 
 - `web_research` — búsqueda y síntesis con `web_search` + `web_fetch`.
-- `web_browser_research` — investigación profunda combinando `web_search` con navegación real (`browser_navigate`, `browser_extract`) para sitios dinámicos.
 - `browser_scrape` — captura de contenido renderizado con screenshots.
 - `browser_automate` — automatización de flujos web (clicks, formularios).
+- `api_client` — consumo de APIs REST con `api_request`.
+- `capability_discovery` — la skill mínima: enseña al agente a encontrar el resto.
+
+Se generan desde los `SKILL.md` de `packages/core/src/skills/bundled/`:
+
+```bash
+bun run skills:bundle
+```
+
+En 0.1.5 se retiraron 21 skills que invocaban tools inexistentes (`voice_*`,
+`meeting_transcription`, `canvas_*`, `code_*`, `project_*`): el selector se las
+podía ofrecer al modelo y la ejecución moría sin ejecutor. Hay un test que falla
+si alguna vuelve a declarar una tool que no está en el registry.
 
 ---
 
@@ -371,29 +391,45 @@ unsubscribeCanvas(handler);
 
 ## Storage
 
-Base de datos SQLite con FTS5.
+HiveDB (`@johpaz/hive-db`), un motor embebido con colecciones de documentos e
+índice BM25. Reemplazó a SQLite + FTS5 en 0.1.5.
 
 ```typescript
-import { initializeDatabase, dbService } from "@johpaz/hive-sdk";
+import { ensureHiveDb, col } from "@johpaz/hive-sdk";
+import type { AgentDoc } from "@johpaz/hive-sdk";
+
+// Abre la base, crea los índices y siembra el catálogo. Idempotente.
+await ensureHiveDb();
 
-await initializeDatabase();
-const db = getTestDb();
+const agents = await col<AgentDoc>("agents");
 
-const results = db.query("SELECT * FROM agents WHERE id = ?").all(agentId);
-const single = db.query("SELECT * FROM agents WHERE id = ?").get(agentId);
+const one = await agents.get(agentId);          // { id, doc, version } | undefined
+const workers = await agents.findBy("role", "worker");
+const all = await agents.scan({});
+const scoped = await agents.scan({ prefix: `${threadId}:` });
 
-dbService.close();
+// Escritura con concurrencia optimista
+await agents.put(agentId, { ...one.doc, status: "idle" }, { expectedVersion: one.version });
 ```
 
-### Schemas FTS5
+`HIVE_DB_PATH=":memory:"` abre una base efímera — es lo que usa la suite de
+tests para no tocar la del usuario.
+
+### Búsqueda de capacidad
+
+El índice BM25 es lo que hace funcionar a `search_knowledge`: el agente arranca
+con un loadout mínimo y descubre el resto en runtime.
 
-```sql
-CREATE VIRTUAL TABLE playbook_fts USING fts5(rule, category, applicable_to);
-CREATE VIRTUAL TABLE tools_fts USING fts5(tool_name, name, description, category);
-CREATE VIRTUAL TABLE skills_fts USING fts5(id, name, description, category, tools, triggers, body);
-CREATE VIRTUAL TABLE mcp_tools_fts USING fts5(id, name, description, category);
+```typescript
+import { selectTools, selectSkills } from "@johpaz/hive-sdk";
+
+const tools = await selectTools("leer un archivo del workspace");
+const skills = await selectSkills("investigar en la web");
 ```
 
+Una tool declarada con `defineTool` y pasada a `createAgent` queda indexada
+automáticamente, así que el modelo puede descubrirla igual que a las nativas.
+
 ---
 
 ## Config