@johpaz/hive-sdk 0.0.14 → 0.0.16

package/docs/API-CONTEXT-COMPILER.md

@@ -0,0 +1,252 @@
+# 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 (FTS5 tool/skill/playbook selection) |
+| **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";
+import { getDb } from "@johpaz/hive-sdk";
+
+const db = getDb();
+const pad = new Scratchpad(db);
+
+// 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");
+```
+
+---
+
+## EthicsGuard
+
+Guardián de reglas de calidad de respuesta desde la base de datos.
+
+```typescript
+import { EthicsGuard } from "@johpaz/hive-sdk";
+import { getDb } from "@johpaz/hive-sdk";
+
+const db = getDb();
+const guard = new EthicsGuard(db);
+
+// Obtener reglas
+const rules = guard.getRules();              // Todas
+const rulesForRole = guard.getRules("agent"); // Con FTS5
+
+// Inyectar en system prompt
+const prompt = guard.injectIntoPrompt(
+  "Eres un asistente.",
+  rules
+);
+
+// Verificar si hay reglas
+if (guard.hasEthicsLayer()) {
+  console.log("Reglas de calidad activas");
+}
+```
+
+---
+
+## 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-4o-mini",
+  messages: 5,
+  toolCalls: ["web_search", "read_file"],
+  durationMs: 1200,
+  tokensUsed: 450,
+  success: true,
+});
+
+// Registrar uso de LLM
+recordLLMUsage({
+  model: "gpt-4o-mini",
+  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();
+```
+
+---
+
+## 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-DAG-SCHEDULER.md

@@ -0,0 +1,273 @@
+# API Reference — DAG Scheduler
+
+## Índice
+
+1. [Arquitectura](#arquitectura)
+2. [TaskNode](#tasknode)
+3. [TaskGraph](#taskgraph)
+4. [DAGScheduler](#dagscheduler)
+5. [Estrategias](#estrategias)
+6. [Presets](#presets)
+7. [EventBridge](#eventbridge)
+8. [Errores Comunes](#errores-comunes)
+
+---
+
+## Arquitectura
+
+El DAG Scheduler orquesta la ejecución de grafos acíclicos dirigidos (DAG) de tareas.
+
+```
+TaskNode → TaskGraph → DAGScheduler
+                           │
+            ┌──────────────┼──────────────┐
+            ▼              ▼              ▼
+        Worker 1        Worker 2       Worker 3
+       (agente)        (agente)       (agente)
+```
+
+---
+
+## TaskNode
+
+Representa una tarea individual en el grafo.
+
+### TaskNodeConfig
+
+```typescript
+import { TaskNode } from "@johpaz/hive-sdk";
+
+interface TaskNodeConfig {
+  id: string;
+  agentId: string;
+  name?: string;
+  taskDescription: string;
+  deps: string[];
+  priority?: number;
+  timeout?: number;
+  maxRetries?: number;
+}
+```
+
+### Estados
+
+```typescript
+type NodeStatus = "PENDING" | "READY" | "RUNNING" | "COMPLETED" | "FAILED";
+```
+
+### Ejemplo
+
+```typescript
+const node = new TaskNode({
+  id: "fetch-data",
+  agentId: "fetcher",
+  taskDescription: "Obtener datos de API",
+  deps: [],
+});
+node.markRunning();
+// ... ejecutar ...
+node.markCompleted("datos obtenidos");
+```
+
+---
+
+## TaskGraph
+
+Grafo acíclico dirigido de tareas.
+
+```typescript
+import { TaskGraph } from "@johpaz/hive-sdk";
+
+const graph = new TaskGraph([
+  { id: "a", agentId: "worker", taskDescription: "Tarea A", deps: [] },
+  { id: "b", agentId: "worker", taskDescription: "Tarea B", deps: ["a"] },
+  { id: "c", agentId: "worker", taskDescription: "Tarea C", deps: ["a"] },
+  { id: "d", agentId: "worker", taskDescription: "Tarea D", deps: ["b", "c"] },
+]);
+
+// Nodos listos para ejecutar (sin deps pendientes)
+const ready = graph.getReadyNodes();
+
+// IDs de nodos completados
+const completed = graph.getCompletedIds();
+
+// Nodos recién listos tras completar uno
+const newlyReady = graph.getNewlyReadyIds(new Set(["a"]));
+
+// Resultados de dependencias
+const depResults = graph.getDepResults("d");
+
+// Progreso
+const progress = graph.getProgress();
+// { total: 4, completed: 1, running: 0, failed: 0, pending: 3, percentComplete: 25 }
+```
+
+---
+
+## DAGScheduler
+
+Orquestador principal de la ejecución.
+
+```typescript
+import { DAGScheduler, TaskGraph } from "@johpaz/hive-sdk";
+
+const graph = new TaskGraph([
+  { id: "fetch", agentId: "fetcher", taskDescription: "Fetch data", deps: [] },
+  { id: "process", agentId: "processor", taskDescription: "Process", deps: ["fetch"] },
+  { id: "save", agentId: "saver", taskDescription: "Save", deps: ["process"] },
+]);
+
+const scheduler = new DAGScheduler({
+  maxConcurrentWorkers: 2,
+});
+
+const result = await scheduler.execute(graph);
+
+console.log(`Success: ${result.success}`);
+console.log(`Duration: ${result.totalDurationMs}ms`);
+```
+
+### DAGResult
+
+```typescript
+interface DAGResult {
+  swarmId: string;
+  totalDurationMs: number;
+  completed: NodeSummary[];
+  failed: NodeSummary[];
+  success: boolean;
+}
+
+interface NodeSummary {
+  id: string;
+  name: string;
+  status: "COMPLETED" | "FAILED";
+  durationMs: number;
+  result?: string;
+  error?: string;
+  retries: number;
+}
+```
+
+### Control
+
+```typescript
+scheduler.abort();    // Abortar ejecución en curso
+```
+
+---
+
+## Estrategias
+
+### ParallelStrategy (FIFO)
+
+```typescript
+import { ParallelStrategy } from "@johpaz/hive-sdk";
+
+const strategy = new ParallelStrategy();  // Orden de llegada
+```
+
+### PriorityStrategy
+
+```typescript
+import { PriorityStrategy } from "@johpaz/hive-sdk";
+
+const strategy = new PriorityStrategy();  // Por prioridad + path crítico
+```
+
+### Custom Strategy
+
+```typescript
+import type { ExecutionStrategy } from "@johpaz/hive-sdk";
+
+const myStrategy: ExecutionStrategy = {
+  initialize(nodes) { /* precomputar */ },
+  pick(nodes) { return nodes[0]; },  // FIFO
+};
+```
+
+---
+
+## Presets
+
+Grafos predefinidos.
+
+### ResearchPreset
+
+```typescript
+import { createResearchGraph } from "@hive/core/swarm/presets";
+
+const graph = createResearchGraph({
+  agents: { researcher: "researcher-id", writer: "writer-id" },
+  query: "Análisis de mercado",
+});
+```
+
+### HiveLearnPreset
+
+```typescript
+import { createHiveLearnGraph } from "@hive/core/swarm/presets";
+
+const graph = createHiveLearnGraph({
+  agents: { teacher: "teacher-id", student: "student-id" },
+  topic: "Machine Learning",
+});
+```
+
+---
+
+## EventBridge
+
+Puente de eventos entre el scheduler y el resto del sistema.
+
+```typescript
+import { EventBridge } from "@johpaz/hive-sdk";
+
+const bridge = new EventBridge("swarm-123", "project-1", "coordinator-1");
+
+bridge.onTaskCompleted = (node, progress) => {
+  console.log(`${node.name}: ${progress.percentComplete}%`);
+};
+
+bridge.onSwarmCompleted = (result) => {
+  console.log(`Swarm completed. Success: ${result.success}`);
+};
+```
+
+---
+
+## IAgentExecutor
+
+```typescript
+import type { IAgentExecutor } from "@johpaz/hive-sdk";
+
+const myExecutor: IAgentExecutor = {
+  async execute(node, depResults, threadId) {
+    const context = Object.values(depResults).join("\n");
+    return await myCustomFunction(node.taskDescription, context);
+  },
+};
+
+const result = await scheduler.execute(graph, { executor: myExecutor });
+```
+
+---
+
+## Errores Comunes
+
+### Cyclic dependency detected
+
+```typescript
+// ❌ Ciclo: a→b→a
+[{ id: "a", deps: ["b"] }, { id: "b", deps: ["a"] }];
+
+// ✅ Sin ciclo
+[{ id: "a", deps: [] }, { id: "b", deps: ["a"] }];
+```
+
+### Task timeout
+
+```typescript
+// Configurar timeout razonable
+const config = { id: "task", agentId: "w", taskDescription: "...", deps: [], timeout: 30000 };
+```