@johpaz/hive-sdk 0.0.15 → 0.0.17

package/docs/API-WORKERS-EVENTS.md

@@ -2,49 +2,214 @@
 
 ## Índice
 
-1. [Workers](#workers)
-2. [AgentBus](#agentbus)
-3. [EventBus](#eventbus)
-4. [Canvas Events](#canvas-events)
+1. [Bun Workers](#bun-workers)
+2. [createWorker](#createworker)
+3. [WorkerPool](#workerpool)
+4. [AgentBus](#agentbus)
+5. [EventBus](#eventbus)
+6. [Canvas Events](#canvas-events)
 
 ---
 
-## Workers
+## Bun Workers
 
-Los workers ejecutan tareas dentro de un swarm.
+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.
 
-### AgentExecutor
+### 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 { AgentExecutor } from "@hive/core";
+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);
 
-const executor = new AgentExecutor();
-const result = await executor.execute(node, depResults, threadId);
+researcher.terminate();
 ```
 
-### WorkerPool
+### 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
 
-Pool de workers para ejecución concurrente.
+Gestiona un pool de Bun Workers para ejecución paralela.
+
+### Firma
 
 ```typescript
-import { setSchedulerForCleanup, executeScheduledTask } from "@hive/core/swarm/workers";
+import { WorkerPool } from "@johpaz/hive-sdk";
+
+const pool = new WorkerPool(config?: WorkerPoolConfig);
+```
 
-// Programar task
-await executeScheduledTask(job);
+### WorkerPoolConfig
+
+```typescript
+interface WorkerPoolConfig {
+  maxWorkers?: number;        // Default: 4
+  taskTimeoutMs?: number;     // Default: 120000
+  workerConfig?: WorkerConfig;
+}
 ```
 
-### Worker Custom
+### Métodos
 
 ```typescript
-import type { IAgentExecutor } from "@hive/core";
+// Ejecutar una tarea
+pool.execute(task: PoolTask): Promise<PoolTaskResult>
 
-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);
+// 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: hives add-worker
+
+Genera un Bun Worker en tu proyecto:
+
+```bash
+cd my-project
+hives 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...`,
+});
 ```
 
 ---
@@ -54,7 +219,7 @@ const myWorker: IAgentExecutor = {
 Sistema de eventos singleton para comunicación entre agentes.
 
 ```typescript
-import { agentBus, getUnreadMessagesForWorker } from "@hive/core";
+import { agentBus, getUnreadMessagesForWorker } from "@johpaz/hive-sdk";
 
 // Publicar evento
 agentBus.publish("worker:task_started", { taskId: "task-1" }, "worker-1");
@@ -71,15 +236,12 @@ unsub();
 ### Métodos Helper
 
 ```typescript
-import { 
-  getUnreadMessagesForWorker, 
-  getProjectMessageHistory 
-} from "@hive/core";
+import {
+  getUnreadMessagesForWorker,
+  getProjectMessageHistory,
+} from "@johpaz/hive-sdk";
 
-// Mensajes no leídos para un worker
 const messages = getUnreadMessagesForWorker("worker-1");
-
-// Historial de un proyecto
 const history = getProjectMessageHistory("project-1");
 ```
 
@@ -90,7 +252,7 @@ const history = getProjectMessageHistory("project-1");
 EventBus global singleton (eventos del sistema).
 
 ```typescript
-import { eventBus } from "@hive/core";
+import { eventBus } from "@johpaz/hive-sdk";
 
 // Escuchar eventos
 eventBus.on("agent:start", (data) => {
@@ -108,45 +270,30 @@ eventBus.emit("agent:complete", { agentId: "a1", result: "ok" });
 Eventos de actualización visual del canvas.
 
 ```typescript
-import { emitCanvas } from "@hive/core/canvas";
+import { emitCanvas, subscribeCanvas, unsubscribeCanvas } from "@johpaz/hive-sdk";
 
-// Actualizar estado de un nodo
+// 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" },
 });
 
-// Eventos disponibles
-emitCanvas("canvas:node_update", { nodeId, changes });
-emitCanvas("canvas:graph_update", { graphId, changes });
-emitCanvas("canvas:worker_update", { workerId, changes });
+// Desuscribirse
+unsubscribeCanvas(handler);
 ```
 
 ### CanvasManager
 
 ```typescript
-import { CanvasManager, canvasManager } from "@hive/core/canvas";
-
-// Singleton
-const canvas = canvasManager;
+import { CanvasManager } from "@johpaz/hive-sdk";
 
-// Suscribirse a updates de un nodo
-canvas.subscribe("agent-1", (update) => {
-  console.log("Node update:", update);
-});
+const canvas = new CanvasManager();
 ```
 
-### 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" }));
-```
+*Documentación Hive SDK v0.0.17*

package/docs/INDEX.md

@@ -4,21 +4,33 @@
 
 | Documento | Descripción |
 |-----------|-------------|
-| [README.md](../README.md) | Introducción y guía rápida |
-| [API-AGENTS.md](./API-AGENTS.md) | AgentLoop, Tool/Skill Selector, LLM Providers |
+| [README.md](../README.md) | Introducción, instalación, CLI, guía rápida |
+| [API-AGENTS.md](./API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, LLM Providers |
 | [API-DAG-SCHEDULER.md](./API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, Estrategias, Presets |
-| [API-WORKERS-EVENTS.md](./API-WORKERS-EVENTS.md) | Workers, AgentBus, Eventos del sistema |
-| [API-TOOLS-SKILLS-CHANNELS.md](./API-TOOLS-SKILLS-CHANNELS.md) | Tools, Skills, Canvas, Storage |
-| [API-CONTEXT-COMPILER.md](./API-CONTEXT-COMPILER.md) | Context Compiler, MCP, LLM Client |
+| [API-WORKERS-EVENTS.md](./API-WORKERS-EVENTS.md) | **Bun Workers**, createWorker, WorkerPool, AgentBus, EventBus, Canvas |
+| [API-TOOLS-SKILLS-CHANNELS.md](./API-TOOLS-SKILLS-CHANNELS.md) | Tools, Skills, MCP, Gateway, Channels, Tool Runtime, Storage |
+| [API-CONTEXT-COMPILER.md](./API-CONTEXT-COMPILER.md) | Context Compiler, Message History, Scratchpad, EthicsGuard, ACE |
+| [TEMPLATE-HIVE-APP.md](./TEMPLATE-HIVE-APP.md) | **Template hive-app** — estructura, opciones, personalización |
+| [HIVE-HARNESS.md](../docs/HIVE-HARNESS.md) | Posicionamiento: Hive como Agent Harness vertical |
 
 ---
 
 ## Guía de Inicio Rápido
 
-### 1. Crear Agente (nueva API)
+### 1. Crear una app harness completa
+
+```bash
+hives create-app my-hive
+cd my-hive
+bun install
+cp .env.example .env
+bun run dev
+```
+
+### 2. Crear Agente
 
 ```typescript
-import { createAgent, defineTool } from "@hive/core";
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
 
 const tool = defineTool({
   name: "saludar",
@@ -36,49 +48,85 @@ const agent = await createAgent({
 const respuesta = await agent.run("Saluda a Juan");
 ```
 
-### 2. Crear un Swarm
+### 3. Crear un Bun Worker
+
+```typescript
+import { createWorker } from "@johpaz/hive-sdk";
+
+const worker = createWorker({
+  name: "researcher",
+  systemPrompt: "You are a research specialist...",
+});
+
+const result = await worker.run("Research quantum computing");
+worker.terminate();
+```
+
+### 4. Ejecutar un Swarm (DAG)
 
 ```typescript
-import { DAGScheduler, TaskGraph } from "@hive/core";
+import { DAGScheduler, TaskGraph } from "@johpaz/hive-sdk";
 
 const graph = new TaskGraph([
-  { id: "task1", agentId: "worker", taskDescription: "Tarea 1", deps: [] },
-  { id: "task2", agentId: "worker", taskDescription: "Tarea 2", deps: ["task1"] },
+  { id: "task1", agentId: "worker", name: "T1", taskDescription: "Tarea 1", deps: [] },
+  { id: "task2", agentId: "worker", name: "T2", taskDescription: "Tarea 2", deps: ["task1"] },
 ]);
 
 const result = await new DAGScheduler().execute(graph);
 ```
 
+### 5. Gateway + Canales
+
+```typescript
+import { startGateway, ChannelManager, TelegramChannel } from "@johpaz/hive-sdk";
+
+const server = await startGateway({ host: "127.0.0.1", port: 18790 });
+
+const channels = new ChannelManager(config);
+// channels.register("telegram", new TelegramChannel({ botToken: "..." }));
+```
+
 ---
 
 ## Estructura de Paquetes
 
 ```
 packages/
-├── core/                   # @hive/core
+├── core/                   # @johpaz/hive-sdk
 │   └── src/
-│       ├── agent/          # AgentLoop, ContextCompiler
+│       ├── api/            # createAgent(), Agent interface
+│       ├── agent/          # AgentLoop, ContextCompiler, ConversationStore
 │       │   ├── providers/  # LLM providers (OpenAI, Anthropic, Gemini, Ollama)
-│       │   └── selectors/  # FTS5 ToolSelector, SkillSelector
-│       ├── tools/          # 66 built-in tools + ToolRegistry
+│       │   └── selectors/  # FTS5 ToolSelector, SkillSelector, PlaybookSelector
+│       ├── tools/          # 70+ built-in tools + ToolRegistry + ToolExecutor
 │       ├── skills/         # SkillLoader, defineSkill()
 │       ├── swarm/          # DAGScheduler, TaskGraph, WorkerPool
-│       │   ├── strategies/ # Parallel, Priority
-│       │   └── presets/    # HiveLearn, Research
-│       ├── mcp/            # MCPClientManager + transports
+│       ├── workers/        # Bun Workers: createWorker, WorkerPool, agent.worker.ts
+│       ├── gateway/        # HTTP/WebSocket server (Bun.serve)
+│       ├── channels/       # Telegram, Discord, WhatsApp, Slack, Webchat
+│       ├── mcp/            # MCPClientManager + transports (SSE, WS, STDIO)
 │       ├── storage/        # SQLite (bun:sqlite) + FTS5
-│       ├── ace/            # Tracer, Reflector, Curator
-│       ├── canvas/         # CanvasManager + A2UI
-│       ├── memory/         # Scratchpad
+│       ├── canvas/         # CanvasManager + A2UI emitter
+│       ├── scheduler/      # CronScheduler + DAG execution
+│       ├── tool-runtime/   # Bun Worker pool para ejecución paralela de tools
 │       ├── ethics/         # EthicsGuard
-│       ├── config/         # loadConfig
-│       ├── utils/          # logger, toon
-│       ├── api/            # createAgent()
-│       └── index.ts        # Public API
+│       ├── memory/         # Scratchpad
+│       ├── config/         # loadConfig, loadEnv, getHiveDir
+│       ├── utils/          # logger, toon, crypto, retry
+│       └── index.ts        # Public API barrel
 │
-└── cli/                    # @hive/cli
+└── cli/                    # Hive CLI
     └── src/
-        └── commands/       # init, run, test, trace
+        ├── index.ts        # Entry: hive <command>
+        └── commands/
+            ├── init.ts
+            ├── create-app.ts      # Generar app harness completa
+            ├── add-tool.ts        # Generar boilerplate de tool
+            ├── add-skill.ts       # Generar boilerplate de skill
+            ├── add-worker.ts      # Generar Bun Worker
+            ├── run.ts
+            ├── test.ts
+            └── trace.ts
 ```
 
 ---
@@ -86,32 +134,31 @@ packages/
 ## Conceptos Clave
 
 ### Agente
-Unidad de ejecución con:
-- Configuración (provider, model, system prompt)
-- Contexto (historial, tools, skills)
-- Ciclo de ejecución (prompt → LLM → tools → response)
+Unidad de ejecución con configuración, contexto y ciclo de ejecución.
 
 ### Tool
-Función que el agente puede invocar:
-- Definida con `defineTool()`
-- Seleccionada dinámicamente via FTS5
-- Ejecutada por el worker
+Función invocable por el agente. Definida con `defineTool()`, seleccionada vía FTS5.
 
 ### Skill
-Composición de tools con triggers semánticos:
-- Definida con `defineSkill()`
-- Categorización automática
+Composición de tools con triggers semánticos. Definida con `defineSkill()`.
+
+### Bun Worker
+Thread aislado que ejecuta un agente con system prompt propio. Creado con `createWorker()`.
+
+### WorkerPool
+Gestiona múltiples Bun Workers para ejecución paralela de tareas.
 
 ### Swarm (DAG)
-Ejecución paralela de múltiples agentes:
-- Nodos = tareas con dependencias
-- Topological sort automático
-- Workers paralelos con estrategias
+Ejecución paralela de múltiples agentes con dependencias. Topological sort automático.
+
+### Gateway
+Servidor HTTP/WebSocket que expone el agente como API.
+
+### Channel
+Integración con plataformas de mensajería (Telegram, Discord, WhatsApp, Slack, Webchat).
 
 ### MCP
-Model Context Protocol:
-- Servidores MCP como herramientas externas
-- Transports: STDIO, SSE, WebSocket
+Model Context Protocol — herramientas externas via STDIO/SSE/WebSocket.
 
 ---
 
@@ -119,9 +166,11 @@ Model Context Protocol:
 
 ```bash
 HIVE_DATA_DIR=./data          # Directorio de datos
+HIVE_HOST=127.0.0.1           # Gateway host
+HIVE_PORT=18790               # Gateway port
 OPENAI_API_KEY=sk-...         # OpenAI
 ANTHROPIC_API_KEY=sk-ant-...  # Anthropic
-LOG_LEVEL=info                 # debug | info | warn | error
+LOG_LEVEL=info                # debug | info | warn | error
 ```
 
 ---
@@ -129,13 +178,13 @@ LOG_LEVEL=info                 # debug | info | warn | error
 ## Tests
 
 ```bash
-# Tests unitarios
-bun test packages/core/src/
+# Tests unitarios (paralelo)
+bun test
 
 # Tests con timeout extendido
-bun test --timeout 60000 packages/core/src/
+bun test --timeout 60000
 ```
 
 ---
 
-*Documentación Hive SDK v2.0.0*
+*Documentación Hive SDK v0.0.17*