@johpaz/hive-sdk 0.4.4 → 0.4.5

package/docs/API-CONTEXT-COMPILER.md

@@ -0,0 +1,285 @@
+# API Reference — Context Compiler y Componentes Avanzados
+
+## Índice
+
+1. [Context Compiler](#context-compiler)
+2. [Message History](#message-history)
+3. [Scratchpad](#scratchpad)
+4. [EthicsGuard](#ethicsguard)
+5. [ACE (Tracer, Reflector, Curator)](#ace)
+6. [MCP Internals](#mcp)
+
+---
+
+## Context Compiler
+
+Compila todo el contexto necesario para cada ejecución del agente.
+
+### compileContext
+
+```typescript
+import { compileContext } from "@johpaz/hive-sdk";
+
+const ctx = await compileContext({
+  agentId: "analyst",
+  threadId: "thread-123",
+  userMessage: "Analiza esto",
+  channel: "slack",
+  mcpManager: mcpClient,
+  isolated: false,
+});
+
+// Resultado
+console.log(ctx.systemPrompt);
+console.log(ctx.messages);   // Historial compilado
+```
+
+### Estrategias
+
+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 (selección BM25 de tool/skill/playbook) |
+| **COMPRIMIR** | Reducir tokens (compaction, tool result clearing) |
+| **AISLAR** | Separar contextos por agente (workers reciben contexto mínimo) |
+
+---
+
+## Message History
+
+### addMessage
+
+```typescript
+import { addMessage } from "@johpaz/hive-sdk";
+
+await addMessage(
+  threadId: string,
+  role: "user" | "assistant" | "system",
+  content: string | ContentPart[],
+  options?: {
+    channel?: string;
+    tool_calls?: ToolCall[];
+  }
+);
+```
+
+### getRecentMessages
+
+```typescript
+import { getRecentMessages } from "@johpaz/hive-sdk";
+
+const messages = await getRecentMessages(threadId, {
+  maxTokens: 32000,
+  maxMessages: 50,
+});
+```
+
+### maybeCompact
+
+Reduce el historial cuando excede el límite de tokens.
+
+```typescript
+import { maybeCompact } from "@johpaz/hive-sdk";
+
+await maybeCompact(threadId, { channel: "slack", userId: "U123" });
+```
+
+### clearOldToolResults
+
+```typescript
+import { clearOldToolResults } from "@johpaz/hive-sdk";
+
+const clean = clearOldToolResults(messages);
+```
+
+### ConversationStore
+
+```typescript
+import { getSummary, saveSummary, getScratchpad, saveScratchpadNote } from "@johpaz/hive-sdk";
+
+// Resumen de conversación
+const summary = getSummary(threadId);
+
+// Notas del scratchpad
+const notes = getScratchpad(threadId, "worker-1");
+```
+
+---
+
+## Scratchpad
+
+Memoria temporal por hilo de conversación.
+
+```typescript
+import { Scratchpad } from "@johpaz/hive-sdk";
+
+const pad = new Scratchpad();
+
+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
+
+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";
+
+const guard = new EthicsGuard();
+
+const rules = await guard.getRules();                     // sólo las globales
+const rulesForRole = await guard.getRules("coordinator"); // filtra por applicable_to
+const rulesForUser = await guard.getRules(undefined, userId); // globales + las de ese usuario
+
+const prompt = guard.injectIntoPrompt("Eres un asistente.", rules);
+
+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)
+
+Sistema de Auto-Corrección por Experiencia.
+
+### Tracer
+
+```typescript
+import { saveTrace, recordLLMUsage } from "@hive/core/ace";
+
+// Guardar traza de ejecución
+saveTrace({
+  agentId: "analyst",
+  model: "gpt-5.6-luna",
+  messages: 5,
+  toolCalls: ["web_search", "read_file"],
+  durationMs: 1200,
+  tokensUsed: 450,
+  success: true,
+});
+
+// Registrar uso de LLM
+recordLLMUsage({
+  model: "gpt-5.6-luna",
+  inputTokens: 200,
+  outputTokens: 250,
+  durationMs: 800,
+});
+```
+
+### Reflector + Curator
+
+```typescript
+import { runReflector, runCurator } from "@hive/core/ace";
+
+// Analizar trazas y generar insights
+await runReflector();
+
+// Curar insights en reglas del playbook
+await runCurator();
+```
+
+### A quién se le aplica lo aprendido
+
+Una regla del playbook se inyecta en el system prompt de cada turno, así que
+quién la ve importa tanto como qué dice. `PlaybookDoc.user_id` y
+`ReflectionDoc.user_id` marcan de quién salió:
+
+| `user_id` | Origen | Quién la ve |
+|---|---|---|
+| `""` | Sembrada con el producto (`INITIAL_PLAYBOOK_RULES`) | Todos |
+| `"user-ana"` | Aprendida de las trazas de esa persona | Sólo ella |
+
+El reflector agrupa el lote de trazas por usuario antes de analizarlo —lo saca
+del `thread_id`, que es `${userId}/${channel}/${peerId}`— y emite una reflexión
+por grupo. El curador propaga ese dueño a la regla, y deduplica **dentro** del
+usuario: la misma observación en dos personas son dos reglas, no una reforzada
+al doble.
+
+Las tres puertas de lectura filtran igual (global + propio):
+
+```typescript
+await selectPlaybookRules(texto, userId)          // inyección en el prompt
+await guard.getRules(undefined, userId)           // EthicsGuard
+// search_knowledge toma el usuario de config.configurable.user_id
+```
+
+`selectPlaybookRules` pide un pozo de candidatos más ancho que el que devuelve,
+porque el índice BM25 es único para todo el proceso: filtrando después de un
+`k` justo, un usuario con pocas reglas se quedaría sin ninguna cuando las mejor
+puntuadas son de otro.
+
+> **Migración.** Las reglas anteriores a este campo se aprendieron cuando la
+> instalación era de un solo usuario: `ensureHiveDb()` se las asigna al primer
+> usuario de la base, no las deja globales. Las sembradas son la excepción —
+> `seedAllData()` les fija `user_id: ""` en cada arranque.
+
+---
+
+## MCP Internals
+
+### Config
+
+```typescript
+import type { MCPConfig, MCPServerConfig } from "@johpaz/hive-sdk";
+
+const config: MCPConfig = {
+  servers: {
+    "my-server": {
+      transport: "stdio",        // "stdio" | "sse" | "websocket"
+      command: "npx",
+      args: ["-y", "@server/pkg"],
+      env: { KEY: "value" },
+      enabled: true,
+    },
+  },
+};
+```
+
+### Singleton
+
+```typescript
+import { setMCPManager, getMCPManager, hasMCPManager } from "@johpaz/hive-sdk";
+
+setMCPManager(mcpManager);
+const mcp = getMCPManager();     // MCPClientManager | undefined
+const exists = hasMCPManager();   // boolean
+```
+
+### Hot Reload
+
+```typescript
+import { startMCPHotReload, stopMCPHotReload } from "@johpaz/hive-sdk";
+
+// Watch de configuración MCP
+startMCPHotReload();
+
+// Detener watch
+stopMCPHotReload();
+```

package/docs/API-CRON.md

@@ -0,0 +1,188 @@
+# Cron — tareas programadas
+
+Jobs recurrentes y de una sola vez, persistidos en HiveDB, que se ejecutan a
+través del pipeline de agentes.
+
+**Sin dependencias.** El motor de cron es propio (`scheduler/cron/`) y usa sólo
+`setTimeout` e `Intl` del runtime de Bun. Hasta 0.2.0 era `croner`.
+
+```typescript
+import { CronScheduler, Cron, parseCronExpression } from "@johpaz/hive-sdk/scheduler";
+```
+
+## Por qué un motor propio y no `Bun.cron()`
+
+Bun 1.4 trae `Bun.cron()` nativo y la pregunta se repite, así que acá está la
+respuesta reevaluada contra el runtime soportado (1.4.2). `Bun.cron` **no alcanza**
+para lo que este scheduler ya expone y persiste en `CronJobDoc`:
+
+| Lo que hace falta | `Bun.cron` 1.4.2 |
+|---|---|
+| 6 campos (con segundos) | Falla: *"seconds are not supported"* |
+| Fecha ISO como patrón — así se agendan los `one_shot` | La rechaza: espera 5 campos |
+| Zona horaria por job | Usa la zona local del proceso; no acepta una zona distinta por job |
+| `nextRun()` — de ahí sale `next_run_at` | El handle es `{ cron, ref, stop, unref }` |
+| `pause()` / `resume()` | No existen |
+| `protect`, `maxRuns`, `interval`, `startAt`/`stopAt`, `domAndDow` | Sin equivalente |
+| Controles persistidos | Sin equivalente para la política completa de Hive |
+
+Sin fecha ISO no hay jobs de una sola vez, y sin zona horaria "todos los días a
+las 9" significa las 9 UTC para todo el mundo. Por eso el motor es propio: la
+meta era **cero dependencias**, no *usar `Bun.cron` a cualquier precio*.
+
+Vale la pena volver a mirarlo cuando `Bun.cron` tenga zona horaria y next-run.
+
+---
+
+## Crear un job
+
+```typescript
+const scheduler = new CronScheduler(async (job) => {
+  // Acá corre lo tuyo. Devolver { success } decide si cuenta como corrida o error.
+  return { success: true, response: "listo" };
+});
+
+await scheduler.boot();   // carga los jobs activos de la BD y detecta los perdidos
+
+const { id, nextRun } = await scheduler.create({
+  name: "Reporte diario",
+  task: "Generá el reporte de ventas de ayer",
+  task_type: "recurring",
+  cron_expression: "0 9 * * 1-5",
+  timezone: "America/Bogota",
+});
+```
+
+Para una sola vez, `task_type: "one_shot"` con `fire_at` en ISO 8601. Debe estar
+en el futuro; si no, `create` lo rechaza.
+
+## Expresiones
+
+5 campos, o 6 poniendo los segundos adelante:
+
+```
+┌───────── segundos (0-59)  ← opcional
+│ ┌─────── minuto (0-59)
+│ │ ┌───── hora (0-23)
+│ │ │ ┌─── día del mes (1-31)
+│ │ │ │ ┌─ mes (1-12 o JAN-DEC)
+│ │ │ │ │ ┌ día de semana (0-7 o SUN-SAT, 0 y 7 = domingo)
+* * * * * *
+```
+
+Acepta `*`, `?` (igual que `*`), listas `1,15`, rangos `1-5`, pasos `*/2`,
+`1-9/3` y `5/15`, nombres de mes y de día, y rangos que dan la vuelta (`22-2` en
+horas = 22, 23, 0, 1, 2).
+
+| Expresión | Significado |
+|---|---|
+| `0 9 * * *` | Todos los días a las 9:00 |
+| `0 7 * * 1-5` | Lunes a viernes a las 7:00 |
+| `0 */2 * * *` | Cada 2 horas |
+| `0 0 1 * *` | El 1 de cada mes |
+| `*/30 * * * * *` | Cada 30 segundos |
+
+Un error de sintaxis dice **qué campo** falló, porque ese mensaje termina en la
+respuesta de `cron.create` y lo lee quien se equivocó al escribirla:
+
+```
+campo horas: 25 fuera de rango 0-23 (en "0 25 * * *")
+```
+
+## Opciones del job
+
+| Campo | Qué hace |
+|---|---|
+| `timezone` | Zona IANA en la que se lee la expresión. Obligatoria en la práctica |
+| `protect` | No arranca una corrida si la anterior sigue en curso |
+| `max_runs` | Deja de correr después de N corridas |
+| `interval_sec` | Piso de segundos entre arranques, además de la expresión |
+| `start_at` / `stop_at` | Ventana: no corre antes / después de esas fechas |
+| `dom_and_dow` | Exige día del mes **y** de semana, en vez de cualquiera de los dos |
+| `misfire_policy` | Qué hacer con lo que se perdió mientras el proceso estaba caído |
+
+### `dom_and_dow`
+
+El cron clásico usa **O** cuando los dos campos de día están restringidos:
+`0 9 15 * 1` es "los 15 **o** los lunes". Con `dom_and_dow: true` pasa a ser
+"los 15 **que sean** lunes". No es un detalle: la diferencia entre las dos
+lecturas es de ~4 corridas por mes a 1 cada varios meses.
+
+### `misfire_policy`
+
+Si el proceso estuvo caído cuando tocaba correr, al arrancar `boot()` lo detecta:
+
+- `skip` (por defecto) — se anota y se sigue con la próxima.
+- `fire_once` — se corre una vez ahora, si el atraso entra en `misfire_grace_min`.
+
+Un `one_shot` que se perdió y no se pone al día pasa a `failed`: su `fire_at` ya
+pasó y no puede volver a ocurrir, así que dejarlo activo sería un job zombi.
+
+## Zona horaria y horario de verano
+
+La expresión se lee contra **el reloj de pared de la zona del job**, no contra
+UTC ni contra la zona del servidor. "Todos los días a las 9" en Bogotá son las
+14:00Z, y en Madrid cambia dos veces al año.
+
+Los dos casos raros están resueltos, y no de forma arbitraria:
+
+- **La hora que no existe.** Cuando el reloj se adelanta, salta de 01:59 a
+  03:00: un job de las 2:30 no tiene cuándo correr ese día. **Se saltea ese día**
+  en vez de correr a una hora inventada.
+- **La hora que ocurre dos veces.** Cuando el reloj se atrasa, las 2:30 pasan
+  dos veces. **Corre en la primera**, una sola vez.
+
+## Usar el motor suelto
+
+Sirve sin montar un scheduler — por ejemplo para que una UI muestre las próximas
+corridas mientras la persona escribe la expresión:
+
+```typescript
+import { Cron, isValidCronExpression, parseCronExpression } from "@johpaz/hive-sdk/scheduler";
+
+isValidCronExpression("0 9 * * *");   // true
+
+const c = new Cron("0 9 * * 1-5", { timezone: "America/Bogota" });
+c.nextRun();       // Date de la próxima corrida
+c.nextRuns(5);     // las próximas cinco
+
+// Con función, se agenda de verdad
+const job = new Cron("*/30 * * * * *", { protect: true }, async () => {
+  await hacerAlgo();
+});
+job.pause(); job.resume(); job.trigger(); job.stop();
+```
+
+`new Cron(expr)` **sin función no agenda nada**: es la forma de validar una
+expresión sin dejar un timer suelto.
+
+## Contadores y auto-pausa
+
+Cada corrida deja una fila en `taskRuns` y actualiza `run_count` / `error_count`
+del job. A los **5 errores seguidos** el job se auto-pausa: un job roto no debe
+reintentar para siempre.
+
+Los incrementos se calculan dentro del reintento por conflicto de versión, no
+antes. Con dos corridas solapadas —normal en un job que tarda más que su
+intervalo y no declara `protect`— calcularlos afuera hace que una escritura se
+pierda, y entonces el umbral de auto-pausa no se alcanza nunca.
+
+## Limpieza
+
+`runCleanup()` corre sola como job interno: borra corridas de más de 30 días,
+cancela los `one_shot` completados hace más de 7, deja como mucho las últimas
+1000 corridas por job, y expira los artefactos vencidos.
+
+## API
+
+**`CronScheduler`** — `boot` · `create` · `update` · `delete` · `pause` ·
+`resume` · `trigger` · `activate` · `deactivate` · `getStatus` · `getTask` ·
+`listTasks` · `getHistory` · `runCleanup` · `shutdown`
+
+**Motor** — `Cron` · `parseCronExpression` · `isValidCronExpression` ·
+`nextOccurrence` · `toWallClock` · `toInstant` · `assertTimeZone`
+
+Para el CRUD desde una UI, sin manejar el scheduler a mano, ver
+[API-SERVICES.md](./API-SERVICES.md) (`createCronJob`, `listCronJobs`, …).
+
+*Documentación Hive SDK — ver `version` en package.json*