@johpaz/hive-sdk 0.0.14 → 0.0.15

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 "@hive/core";
+
+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 "@hive/core";
+
+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 "@hive/core";
+
+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 "@hive/core";
+
+const strategy = new ParallelStrategy();  // Orden de llegada
+```
+
+### PriorityStrategy
+
+```typescript
+import { PriorityStrategy } from "@hive/core";
+
+const strategy = new PriorityStrategy();  // Por prioridad + path crítico
+```
+
+### Custom Strategy
+
+```typescript
+import type { ExecutionStrategy } from "@hive/core";
+
+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 "@hive/core";
+
+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 "@hive/core";
+
+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 };
+```

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

@@ -0,0 +1,293 @@
+# API Reference — Tools, Skills, MCP y Storage
+
+## Índice
+
+1. [Tools](#tools)
+2. [Skills](#skills)
+3. [MCP](#mcp)
+4. [Canvas](#canvas)
+5. [Storage](#storage)
+6. [Config](#config)
+7. [Gateway (stub)](#gateway)
+
+---
+
+## Tools
+
+### defineTool
+
+Función para definir herramientas que el agente puede invocar.
+
+```typescript
+import { defineTool } from "@hive/core";
+
+const tool = defineTool({
+  name: "saludar",
+  description: "Saluda a alguien por su nombre",
+  execute: async (args: { nombre: string }) => {
+    return { mensaje: `¡Hola ${args.nombre}!` };
+  },
+});
+```
+
+### ToolRegistry
+
+Registro central de herramientas.
+
+```typescript
+import { ToolRegistry, defineTool } from "@hive/core";
+
+const reg = new ToolRegistry();
+
+// Registrar
+reg.register(defineTool({ name: "t1", description: "...", execute: async () => ({}) }));
+
+// Consultar
+reg.has("t1");              // true
+reg.get("t1");              // ToolDefinition
+reg.list();                  // ToolDefinition[]
+reg.getByCategory("web");   // Filtrar por categoría
+reg.getNames();             // ["t1"]
+reg.size();                 // 1
+
+// Merge con otro registry
+reg.merge(otherRegistry);
+
+// Limpiar
+reg.clear();
+```
+
+### ToolExecutor
+
+Ejecutor de herramientas con validación Zod.
+
+```typescript
+import { ToolRegistry, ToolExecutor, defineTool } from "@hive/core";
+
+const reg = new ToolRegistry();
+reg.register(defineTool({
+  name: "echo",
+  description: "Echo",
+  execute: async (args) => args,
+}));
+
+const exec = new ToolExecutor(reg);
+
+// Ejecutar una tool
+const result = await exec.execute("echo", { msg: "hola" });
+// { toolName: "echo", args: { msg: "hola" }, result: { msg: "hola" }, durationMs: 1 }
+
+// Ejecución batch
+const results = await exec.executeBatch([
+  { name: "echo", args: { msg: "a" } },
+  { name: "echo", args: { msg: "b" } },
+]);
+```
+
+### Tool Selection (FTS5)
+
+```typescript
+import { selectTools, CORE_TOOL_CATALOG } from "@hive/core";
+
+// Selección automática por relevancia
+const tools = selectTools("Buscar archivos en el proyecto");
+
+// Filtrar por categoría
+const webTools = tools.filter(t => t.category === "web");
+```
+
+---
+
+## Skills
+
+### defineSkill
+
+```typescript
+import { defineSkill } from "@hive/core";
+
+const skill = defineSkill({
+  name: "file-manager",
+  description: "Gestiona archivos y directorios",
+  steps: [
+    { action: "fs_list", instruction: "Listar archivos" },
+    { action: "fs_read", instruction: "Leer archivo" },
+  ],
+  tools: ["fs_list", "fs_read"],
+  triggers: ["archivo", "directorio", "listar"],
+});
+```
+
+### SkillLoader
+
+Carga skills desde archivos YAML o datos bundled.
+
+```typescript
+import { SkillLoader } from "@hive/core";
+
+const loader = new SkillLoader({
+  allowBundled: ["file-manager", "web-researcher"],
+  managedDir: "./skills",
+});
+
+const skills = loader.list();
+const skill = loader.get("file-manager");
+```
+
+---
+
+## MCP
+
+Model Context Protocol — herramientas externas via STDIO/SSE.
+
+### MCPClientManager
+
+```typescript
+import { MCPClientManager } from "@hive/core";
+
+// Configurar con servidores
+const mcp = new MCPClientManager({
+  servers: {
+    "filesystem": {
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"],
+      enabled: true,
+    },
+    "weather-api": {
+      transport: "sse",
+      url: "https://api.weather.com/mcp",
+      enabled: true,
+    },
+  },
+});
+
+// Inicializar y conectar
+await mcp.initialize();
+
+// Obtener tools de servidores MCP
+const tools = mcp.getTools("filesystem");
+
+// Actualizar configuración
+await mcp.updateConfig({ servers: { ... } });
+```
+
+### MCPToolAdapter
+
+Sincroniza tools MCP con la base de datos FTS5.
+
+```typescript
+import { syncMCPToolsToDB, syncMCPToolsToFTS, clearMCPToolsFromDB } from "@hive/core/mcp";
+
+await syncMCPToolsToDB(mcpManager);
+await syncMCPToolsToFTS();
+```
+
+### Transports
+
+```typescript
+import { createTransport, SSETransport, WebSocketTransport } from "@hive/core/mcp/transports";
+
+// STDIO
+const transport = createTransport({
+  type: "stdio",
+  stdio: { command: "npx", args: ["-y", "server"], env: {} },
+});
+
+// SSE
+const sse = new SSETransport({ url: "https://api.example.com/mcp" });
+
+// WebSocket
+const ws = new WebSocketTransport({ url: "wss://api.example.com/mcp" });
+```
+
+---
+
+## Canvas
+
+Visualización en tiempo real del estado de agentes.
+
+```typescript
+import { CanvasManager, canvasManager, emitCanvas } from "@hive/core/canvas";
+
+// Singleton
+canvasManager.subscribe("agent-1", (update) => {
+  console.log("Estado:", update.changes.status);
+});
+
+// Emitir eventos
+emitCanvas("canvas:node_update", {
+  nodeId: "agent-1",
+  changes: { status: "running", currentTool: "web_search" },
+});
+```
+
+### A2UI Tools
+
+```typescript
+import { createA2UISurfaceTool, createA2UIUpdateComponentsTool } from "@hive/core/canvas";
+
+// Crear tools A2UI para UI generada por agentes
+const surfaceTool = createA2UISurfaceTool();
+const updateTool = createA2UIUpdateComponentsTool();
+```
+
+---
+
+## Storage
+
+Base de datos SQLite con FTS5.
+
+```typescript
+import { initializeDatabase, getDb, dbService } from "@hive/core";
+
+// Inicializar (crea tablas si no existen)
+await initializeDatabase();
+
+// Obtener instancia DB
+const db = getDb();
+
+// Queries
+const results = db.query("SELECT * FROM agents WHERE id = ?").all(agentId);
+const single = db.query("SELECT * FROM agents WHERE id = ?").get(agentId);
+
+// Insert/Update
+db.query("INSERT INTO agents (id, name) VALUES (?, ?)").run("a1", "Agent 1");
+
+// Cerrar
+dbService.close();
+```
+
+### Schemas FTS5
+
+```sql
+-- 4 tablas virtuales FTS5 para búsqueda full-text
+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);
+```
+
+---
+
+## Config
+
+```typescript
+import { loadConfig, loadEnv, getHiveDir } from "@hive/core";
+
+const config = await loadConfig();
+// { HIVE_DATA_DIR: "./data", LOG_LEVEL: "info", ... }
+
+const hiveDir = getHiveDir();  // ~/.hive o HIVE_DATA_DIR
+```
+
+---
+
+## Gateway (stub)
+
+```typescript
+import { sendToUserChannel } from "@hive/core/gateway";
+
+// Stub — logs al console, retorna { ok: true }
+// Reemplazar cuando se integre con un sistema de notificaciones real
+const result = await sendToUserChannel("cli:user-1", "user-1", "Hello!");
+```

package/docs/API-WORKERS-EVENTS.md

@@ -0,0 +1,152 @@
+# API Reference — Workers y Eventos
+
+## Índice
+
+1. [Workers](#workers)
+2. [AgentBus](#agentbus)
+3. [EventBus](#eventbus)
+4. [Canvas Events](#canvas-events)
+
+---
+
+## Workers
+
+Los workers ejecutan tareas dentro de un swarm.
+
+### AgentExecutor
+
+```typescript
+import { AgentExecutor } from "@hive/core";
+
+const executor = new AgentExecutor();
+const result = await executor.execute(node, depResults, threadId);
+```
+
+### WorkerPool
+
+Pool de workers para ejecución concurrente.
+
+```typescript
+import { setSchedulerForCleanup, executeScheduledTask } from "@hive/core/swarm/workers";
+
+// Programar task
+await executeScheduledTask(job);
+```
+
+### Worker Custom
+
+```typescript
+import type { IAgentExecutor } from "@hive/core";
+
+const myWorker: IAgentExecutor = {
+  async execute(node, depResults, threadId) {
+    const context = Object.entries(depResults)
+      .map(([id, r]) => `${id}: ${r}`).join("\n");
+    return await processTask(node.taskDescription, context);
+  },
+};
+```
+
+---
+
+## AgentBus
+
+Sistema de eventos singleton para comunicación entre agentes.
+
+```typescript
+import { agentBus, getUnreadMessagesForWorker } from "@hive/core";
+
+// Publicar evento
+agentBus.publish("worker:task_started", { taskId: "task-1" }, "worker-1");
+
+// Suscribirse
+const unsub = agentBus.subscribe("worker:task_completed", (data) => {
+  console.log("Task completed:", data);
+});
+
+// Unsubscribe
+unsub();
+```
+
+### Métodos Helper
+
+```typescript
+import { 
+  getUnreadMessagesForWorker, 
+  getProjectMessageHistory 
+} from "@hive/core";
+
+// Mensajes no leídos para un worker
+const messages = getUnreadMessagesForWorker("worker-1");
+
+// Historial de un proyecto
+const history = getProjectMessageHistory("project-1");
+```
+
+---
+
+## EventBus
+
+EventBus global singleton (eventos del sistema).
+
+```typescript
+import { eventBus } from "@hive/core";
+
+// Escuchar eventos
+eventBus.on("agent:start", (data) => {
+  console.log("Agent started:", data);
+});
+
+// Emitir eventos
+eventBus.emit("agent:complete", { agentId: "a1", result: "ok" });
+```
+
+---
+
+## Canvas Events
+
+Eventos de actualización visual del canvas.
+
+```typescript
+import { emitCanvas } from "@hive/core/canvas";
+
+// Actualizar estado de un nodo
+emitCanvas("canvas:node_update", {
+  nodeId: "agent-1",
+  changes: { status: "thinking" },
+});
+
+// Eventos disponibles
+emitCanvas("canvas:node_update", { nodeId, changes });
+emitCanvas("canvas:graph_update", { graphId, changes });
+emitCanvas("canvas:worker_update", { workerId, changes });
+```
+
+### CanvasManager
+
+```typescript
+import { CanvasManager, canvasManager } from "@hive/core/canvas";
+
+// Singleton
+const canvas = canvasManager;
+
+// Suscribirse a updates de un nodo
+canvas.subscribe("agent-1", (update) => {
+  console.log("Node update:", update);
+});
+```
+
+### WebSocket Canvas
+
+```typescript
+// Cliente se conecta
+const ws = new WebSocket("ws://localhost:3000/ws/canvas");
+
+ws.onmessage = (event) => {
+  const update = JSON.parse(event.data);
+  // { type: "node_update", nodeId: "...", changes: {...} }
+};
+
+// Enviar mensaje al agente
+ws.send(JSON.stringify({ type: "user_message", message: "ejecutar tarea" }));
+```