@johpaz/hive-sdk 0.0.14 → 0.0.16

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

@@ -0,0 +1,350 @@
+# API Reference — Tools, Skills, MCP, Gateway, Channels y Storage
+
+## Índice
+
+1. [Tools](#tools)
+2. [Skills](#skills)
+3. [MCP](#mcp)
+4. [Gateway](#gateway)
+5. [Channels](#channels)
+6. [Tool Runtime](#tool-runtime)
+7. [Canvas](#canvas)
+8. [Storage](#storage)
+9. [Config](#config)
+
+---
+
+## Tools
+
+### defineTool
+
+Función para definir herramientas que el agente puede invocar.
+
+```typescript
+import { defineTool } from "@johpaz/hive-sdk";
+
+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 "@johpaz/hive-sdk";
+
+const reg = new ToolRegistry();
+
+reg.register(defineTool({ name: "t1", description: "...", execute: async () => ({}) }));
+
+reg.has("t1");              // true
+reg.get("t1");              // ToolDefinition
+reg.list();                 // ToolDefinition[]
+reg.getByCategory("web");   // Filtrar por categoría
+reg.getNames();             // ["t1"]
+reg.size();                 // 1
+reg.merge(otherRegistry);
+reg.clear();
+```
+
+### ToolExecutor
+
+Ejecutor de herramientas con validación Zod.
+
+```typescript
+import { ToolRegistry, ToolExecutor, defineTool } from "@johpaz/hive-sdk";
+
+const reg = new ToolRegistry();
+reg.register(defineTool({
+  name: "echo",
+  description: "Echo",
+  execute: async (args) => args,
+}));
+
+const exec = new ToolExecutor(reg);
+const result = await exec.execute("echo", { msg: "hola" });
+```
+
+### Tool Selection (FTS5)
+
+```typescript
+import { selectTools, CORE_TOOL_CATALOG } from "@johpaz/hive-sdk";
+
+const tools = selectTools("Buscar archivos en el proyecto");
+const webTools = tools.filter(t => t.category === "web");
+```
+
+---
+
+## Skills
+
+### defineSkill
+
+```typescript
+import { defineSkill } from "@johpaz/hive-sdk";
+
+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
+
+```typescript
+import { SkillLoader } from "@johpaz/hive-sdk";
+
+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/WebSocket.
+
+### MCPClientManager
+
+```typescript
+import { MCPClientManager } from "@johpaz/hive-sdk";
+
+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,
+    },
+  },
+});
+
+await mcp.initialize();
+const tools = mcp.getTools("filesystem");
+```
+
+### Transports
+
+```typescript
+import { createTransport, SSETransport, WebSocketTransport } from "@johpaz/hive-sdk";
+
+const transport = createTransport({
+  type: "stdio",
+  stdio: { command: "npx", args: ["-y", "server"], env: {} },
+});
+```
+
+---
+
+## Gateway
+
+Servidor HTTP/WebSocket simplificado para exponer el agente como API.
+
+### startGateway
+
+```typescript
+import { startGateway } from "@johpaz/hive-sdk";
+
+const server = await startGateway({
+  host: "127.0.0.1",
+  port: 18790,
+  agentId: "coordinator",
+  mcpManager: null,
+});
+
+console.log(`Gateway at http://127.0.0.1:18790`);
+```
+
+### Endpoints
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| GET | `/status` | Health check |
+| POST | `/chat` | Chat con el agente |
+| WS | `/ws` | WebSocket streaming |
+
+### Ejemplo: Chat HTTP
+
+```typescript
+const res = await fetch("http://127.0.0.1:18790/chat", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ message: "Hello!", threadId: "t1" }),
+});
+
+const data = await res.json();
+console.log(data.response);
+```
+
+---
+
+## Channels
+
+Integraciones con plataformas de mensajería.
+
+### ChannelManager
+
+```typescript
+import { ChannelManager } from "@johpaz/hive-sdk";
+
+const manager = new ChannelManager(config);
+await manager.initialize();
+```
+
+### Canales soportados
+
+```typescript
+import {
+  TelegramChannel,
+  DiscordChannel,
+  WhatsAppChannel,
+  SlackChannel,
+  WebChatChannel,
+} from "@johpaz/hive-sdk";
+
+// Telegram
+const telegram = new TelegramChannel({ botToken: process.env.TELEGRAM_BOT_TOKEN! });
+
+// Discord
+const discord = new DiscordChannel({ botToken: process.env.DISCORD_BOT_TOKEN! });
+
+// WhatsApp
+const whatsapp = new WhatsAppChannel();
+
+// Slack
+const slack = new SlackChannel({ botToken: process.env.SLACK_BOT_TOKEN! });
+
+// Webchat
+const webchat = new WebChatChannel();
+```
+
+---
+
+## Tool Runtime
+
+Ejecución paralela de herramientas vía Bun Workers.
+
+### executeToolBatch
+
+```typescript
+import { executeToolBatch, shutdownToolRuntime } from "@johpaz/hive-sdk";
+
+const results = await executeToolBatch({
+  toolCalls: [
+    { id: "1", function: { name: "search", arguments: JSON.stringify({ q: "AI" }) } },
+    { id: "2", function: { name: "fetch", arguments: JSON.stringify({ url: "..." }) } },
+  ],
+  allTools: [searchTool, fetchTool],
+  toolConfig: { user_id: "u1", thread_id: "t1" },
+  hiveConfig: loadConfig(),
+  workerPool: {
+    enabled: true,
+    maxWorkers: 4,
+    toolTimeoutMs: 30000,
+    parallelToolCalls: true,
+  },
+});
+
+// Limpieza
+shutdownToolRuntime();
+```
+
+### ToolBatchResult
+
+```typescript
+interface ToolBatchResult {
+  toolCall: ToolCallLike;
+  toolName: string;
+  result: unknown;
+  ok: boolean;
+  durationMs: number;
+  error?: SerializedError;
+  timedOut?: boolean;
+  aborted?: boolean;
+}
+```
+
+---
+
+## Canvas
+
+Visualización en tiempo real del estado de agentes.
+
+```typescript
+import { emitCanvas, subscribeCanvas, unsubscribeCanvas } from "@johpaz/hive-sdk";
+
+const handler = (data: any) => console.log("Canvas:", data);
+subscribeCanvas(handler);
+
+emitCanvas("canvas:node_update", {
+  nodeId: "agent-1",
+  changes: { status: "running", currentTool: "web_search" },
+});
+
+unsubscribeCanvas(handler);
+```
+
+---
+
+## Storage
+
+Base de datos SQLite con FTS5.
+
+```typescript
+import { initializeDatabase, dbService } from "@johpaz/hive-sdk";
+
+await initializeDatabase();
+const db = getTestDb();
+
+const results = db.query("SELECT * FROM agents WHERE id = ?").all(agentId);
+const single = db.query("SELECT * FROM agents WHERE id = ?").get(agentId);
+
+dbService.close();
+```
+
+### Schemas FTS5
+
+```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);
+```
+
+---
+
+## Config
+
+```typescript
+import { loadConfig, loadEnv, getHiveDir } from "@johpaz/hive-sdk";
+
+const config = await loadConfig();
+const hiveDir = getHiveDir();  // ~/.hive o HIVE_DATA_DIR
+```
+
+---
+
+*Documentación Hive SDK v0.0.16*

package/docs/API-WORKERS-EVENTS.md

@@ -0,0 +1,299 @@
+# API Reference — Workers y Eventos
+
+## Índice
+
+1. [Bun Workers](#bun-workers)
+2. [createWorker](#createworker)
+3. [WorkerPool](#workerpool)
+4. [AgentBus](#agentbus)
+5. [EventBus](#eventbus)
+6. [Canvas Events](#canvas-events)
+
+---
+
+## Bun Workers
+
+Hive SDK soporta **workers individuales con Bun Workers**. Cada worker corre en un thread aislado (`Bun.Worker` con `{ smol: true }`), con su propio system prompt y configuración.
+
+### Casos de uso
+
+- **Workers especializados**: Un worker para research, otro para coding, otro para review
+- **Paralelismo**: Ejecutar múltiples tareas simultáneamente sin bloquear el hilo principal
+- **Aislamiento**: Cada worker tiene su propio contexto y no interfere con otros
+
+---
+
+## createWorker
+
+Crea un worker individual con Bun Workers.
+
+### Firma
+
+```typescript
+import { createWorker } from "@johpaz/hive-sdk";
+
+const worker = createWorker(config: WorkerConfig): WorkerInstance
+```
+
+### WorkerConfig
+
+```typescript
+interface WorkerConfig {
+  name: string;                    // Identificador del worker
+  agentId?: string;                // ID del agente en DB (default: name)
+  systemPrompt?: string;           // System prompt personalizado
+  model?: string;                  // Modelo LLM
+  provider?: string;               // Provider LLM
+}
+```
+
+### WorkerInstance
+
+```typescript
+interface WorkerInstance {
+  readonly name: string;
+  readonly id: string;
+
+  // Ejecutar y esperar resultado
+  run(message: string, opts?: {
+    threadId?: string;
+    channel?: string;
+  }): Promise<string>;
+
+  // Streaming de resultados
+  runStream(message: string, opts?: {
+    threadId?: string;
+    channel?: string;
+  }): AsyncGenerator<WorkerChunk>;
+
+  // Terminar el worker
+  terminate(): void;
+}
+```
+
+### Ejemplo básico
+
+```typescript
+import { createWorker } from "@johpaz/hive-sdk";
+
+const researcher = createWorker({
+  name: "researcher",
+  systemPrompt: `
+    You are a research specialist.
+    Provide concise, factual summaries with citations.
+    Always verify facts before presenting them.
+  `,
+});
+
+const result = await researcher.run("Latest advances in quantum computing 2025");
+console.log(result);
+
+researcher.terminate();
+```
+
+### Streaming
+
+```typescript
+const stream = researcher.runStream("Explain quantum entanglement");
+
+for await (const chunk of stream) {
+  if (chunk.type === "chunk") {
+    console.log("Chunk:", chunk.chunk);
+  } else if (chunk.type === "result") {
+    console.log("Final:", chunk.content);
+  } else if (chunk.type === "error") {
+    console.error("Error:", chunk.error);
+  }
+}
+```
+
+---
+
+## WorkerPool
+
+Gestiona un pool de Bun Workers para ejecución paralela.
+
+### Firma
+
+```typescript
+import { WorkerPool } from "@johpaz/hive-sdk";
+
+const pool = new WorkerPool(config?: WorkerPoolConfig);
+```
+
+### WorkerPoolConfig
+
+```typescript
+interface WorkerPoolConfig {
+  maxWorkers?: number;        // Default: 4
+  taskTimeoutMs?: number;     // Default: 120000
+  workerConfig?: WorkerConfig;
+}
+```
+
+### Métodos
+
+```typescript
+// Ejecutar una tarea
+pool.execute(task: PoolTask): Promise<PoolTaskResult>
+
+// Ejecutar múltiples tareas en paralelo
+pool.executeBatch(tasks: PoolTask[]): Promise<PoolTaskResult[]>
+
+// Ejecutar con límite de concurrencia
+pool.executeWithConcurrency(tasks: PoolTask[], concurrency: number): Promise<PoolTaskResult[]>
+
+// Estadísticas
+pool.stats  // { total, busy, idle }
+
+// Cerrar todos los workers
+pool.shutdown(): void
+```
+
+### Ejemplo: Batch processing
+
+```typescript
+import { WorkerPool } from "@johpaz/hive-sdk";
+
+const pool = new WorkerPool({
+  maxWorkers: 4,
+  workerConfig: {
+    name: "analyzer",
+    systemPrompt: "You analyze text and extract key insights.",
+  },
+});
+
+const articles = [
+  { id: "a1", message: "Summarize article about AI..." },
+  { id: "a2", message: "Summarize article about climate..." },
+  { id: "a3", message: "Summarize article about space..." },
+];
+
+const results = await pool.executeBatch(articles);
+
+for (const result of results) {
+  console.log(`${result.taskId}: ${result.result} (${result.durationMs}ms)`);
+}
+
+pool.shutdown();
+```
+
+### Ejemplo: Concurrency limit
+
+```typescript
+// Procesar 100 tareas pero solo 5 a la vez
+const tasks = Array.from({ length: 100 }, (_, i) => ({
+  id: `task-${i}`,
+  message: `Process item ${i}`,
+}));
+
+const results = await pool.executeWithConcurrency(tasks, 5);
+```
+
+---
+
+## CLI: hive add-worker
+
+Genera un Bun Worker en tu proyecto:
+
+```bash
+cd my-project
+hive add-worker researcher
+```
+
+Crea `src/workers/researcher.worker.ts`:
+
+```typescript
+import { createWorker } from "@johpaz/hive-sdk";
+
+export const researcherWorker = createWorker({
+  name: "researcher",
+  systemPrompt: `You are the ResearcherWorker specialist...`,
+});
+```
+
+---
+
+## AgentBus
+
+Sistema de eventos singleton para comunicación entre agentes.
+
+```typescript
+import { agentBus, getUnreadMessagesForWorker } from "@johpaz/hive-sdk";
+
+// 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 "@johpaz/hive-sdk";
+
+const messages = getUnreadMessagesForWorker("worker-1");
+const history = getProjectMessageHistory("project-1");
+```
+
+---
+
+## EventBus
+
+EventBus global singleton (eventos del sistema).
+
+```typescript
+import { eventBus } from "@johpaz/hive-sdk";
+
+// 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, subscribeCanvas, unsubscribeCanvas } from "@johpaz/hive-sdk";
+
+// Suscribirse a eventos canvas
+const handler = (data: any) => console.log("Canvas:", data);
+subscribeCanvas(handler);
+
+// Emitir evento
+emitCanvas("canvas:node_update", {
+  nodeId: "agent-1",
+  changes: { status: "thinking" },
+});
+
+// Desuscribirse
+unsubscribeCanvas(handler);
+```
+
+### CanvasManager
+
+```typescript
+import { CanvasManager } from "@johpaz/hive-sdk";
+
+const canvas = new CanvasManager();
+```
+
+---
+
+*Documentación Hive SDK v0.0.16*