@johpaz/hive-sdk 0.0.14 → 0.0.16

package/docs/INDEX.md

@@ -0,0 +1,190 @@
+# Índice de Documentación — Hive SDK
+
+## Documentos de Usuario
+
+| Documento | Descripción |
+|-----------|-------------|
+| [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) | **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 una app harness completa
+
+```bash
+hive create-app my-hive
+cd my-hive
+bun install
+cp .env.example .env
+bun run dev
+```
+
+### 2. Crear Agente
+
+```typescript
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
+
+const tool = defineTool({
+  name: "saludar",
+  description: "Saluda a alguien",
+  execute: async (args: { nombre: string }) => `¡Hola ${args.nombre}!`,
+});
+
+const agent = await createAgent({
+  name: "asistente",
+  provider: "openai",
+  model: "gpt-4o-mini",
+  tools: [tool],
+});
+
+const respuesta = await agent.run("Saluda a Juan");
+```
+
+### 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 "@johpaz/hive-sdk";
+
+const graph = new TaskGraph([
+  { 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/                   # @johpaz/hive-sdk
+│   └── src/
+│       ├── api/            # createAgent(), Agent interface
+│       ├── agent/          # AgentLoop, ContextCompiler, ConversationStore
+│       │   ├── providers/  # LLM providers (OpenAI, Anthropic, Gemini, Ollama)
+│       │   └── selectors/  # FTS5 ToolSelector, SkillSelector, PlaybookSelector
+│       ├── tools/          # 70+ built-in tools + ToolRegistry + ToolExecutor
+│       ├── skills/         # SkillLoader, defineSkill()
+│       ├── swarm/          # DAGScheduler, TaskGraph, WorkerPool
+│       ├── 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
+│       ├── canvas/         # CanvasManager + A2UI emitter
+│       ├── scheduler/      # CronScheduler + DAG execution
+│       ├── tool-runtime/   # Bun Worker pool para ejecución paralela de tools
+│       ├── ethics/         # EthicsGuard
+│       ├── memory/         # Scratchpad
+│       ├── config/         # loadConfig, loadEnv, getHiveDir
+│       ├── utils/          # logger, toon, crypto, retry
+│       └── index.ts        # Public API barrel
+│
+└── cli/                    # Hive CLI
+    └── src/
+        ├── 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
+```
+
+---
+
+## Conceptos Clave
+
+### Agente
+Unidad de ejecución con configuración, contexto y ciclo de ejecución.
+
+### Tool
+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()`.
+
+### 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 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 — herramientas externas via STDIO/SSE/WebSocket.
+
+---
+
+## Variables de Entorno
+
+```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
+```
+
+---
+
+## Tests
+
+```bash
+# Tests unitarios (paralelo)
+bun test
+
+# Tests con timeout extendido
+bun test --timeout 60000
+```
+
+---
+
+*Documentación Hive SDK v0.0.16*

package/docs/README.md

@@ -0,0 +1,161 @@
+# Documentación — Hive SDK
+
+> **Agent Harness SDK** — Build, deploy, and scale AI agent applications with multi-channel support, Bun Workers, and swarm orchestration.
+
+## Documentos
+
+| Documento | Descripción |
+|-----------|-------------|
+| [API-AGENTS.md](API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, LLM Providers |
+| [API-DAG-SCHEDULER.md](API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, TaskNode, Estrategias, Presets |
+| [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 de producto: Hive como Agent Harness |
+
+## Instalación
+
+```bash
+# Instalar globalmente para el CLI
+bun install -g @johpaz/hive-sdk
+
+# O en un proyecto
+bun add @johpaz/hive-sdk
+```
+
+## CLI Commands
+
+```bash
+hive init <name>         # Inicializar proyecto agente
+hive create-app <name>   # Crear aplicación harness completa
+hive add-tool <name>     # Añadir tool
+hive add-skill <name>    # Añadir skill
+hive add-worker <name>   # Añadir Bun Worker
+hive run                 # Ejecutar agente
+hive test                # Test tools/skills
+hive trace               # Ver logs de ejecución
+```
+
+## Inicio Rápido
+
+### 1. Crear una app harness completa
+
+```bash
+hive create-app my-hive
+cd my-hive
+bun install
+cp .env.example .env
+bun run dev
+```
+
+### 2. Crear un agente simple
+
+```typescript
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
+
+const tool = defineTool({
+  name: "saludar",
+  description: "Saluda a alguien",
+  execute: async (args: { nombre: string }) => `¡Hola ${args.nombre}!`,
+});
+
+const agent = await createAgent({
+  name: "asistente",
+  provider: "openai",
+  model: "gpt-4o-mini",
+  tools: [tool],
+});
+
+const respuesta = await agent.run("Saluda a Juan");
+console.log(respuesta);
+```
+
+### 3. Crear un worker especializado
+
+```typescript
+import { createWorker } from "@johpaz/hive-sdk";
+
+const researcher = createWorker({
+  name: "researcher",
+  systemPrompt: "You are a research specialist. Provide concise, factual summaries.",
+});
+
+const result = await researcher.run("Research quantum computing advances");
+console.log(result);
+researcher.terminate();
+```
+
+### 4. Ejecutar workers en paralelo
+
+```typescript
+import { WorkerPool } from "@johpaz/hive-sdk";
+
+const pool = new WorkerPool({ maxWorkers: 4 });
+
+const tasks = [
+  { id: "t1", message: "Summarize article A" },
+  { id: "t2", message: "Summarize article B" },
+  { id: "t3", message: "Summarize article C" },
+];
+
+const results = await pool.executeBatch(tasks);
+console.log(results);
+pool.shutdown();
+```
+
+### 5. Gateway HTTP/WebSocket
+
+```typescript
+import { startGateway } from "@johpaz/hive-sdk";
+
+const server = await startGateway({
+  host: "127.0.0.1",
+  port: 18790,
+  agentId: "coordinator",
+});
+
+console.log(`Gateway at http://127.0.0.1:18790`);
+```
+
+## Variables de Entorno
+
+```bash
+HIVE_DATA_DIR=./data          # Directorio de datos SQLite
+HIVE_HOST=127.0.0.1           # Gateway host
+HIVE_PORT=18790               # Gateway port
+OPENAI_API_KEY=sk-...         # OpenAI
+ANTHROPIC_API_KEY=sk-ant-...  # Anthropic
+GOOGLE_API_KEY=...            # Gemini
+LOG_LEVEL=info                # debug | info | warn | error
+```
+
+## Tests
+
+```bash
+# Todos los tests (paralelo)
+bun test
+
+# Tests con timeout extendido
+bun test --timeout 60000
+```
+
+## Changelog
+
+### v0.0.16
+- **Bun Workers individuales**: `createWorker()`, `WorkerPool`, `agent.worker.ts`
+- **Gateway simplificado**: HTTP/WebSocket server con `Bun.serve()`
+- **Channels**: Telegram, Discord, WhatsApp, Slack, Webchat
+- **Tool Runtime**: Ejecución paralela de tools vía Bun Workers
+- **CLI mejorado**: `hive create-app`, `hive add-tool`, `hive add-skill`, `hive add-worker`
+- **Template hive-app**: Proyecto harness completo con Docker
+- **39 tests pasando** en 12 archivos
+
+### v0.0.15
+- Core de agentes con Context Engineering, FTS5, ACE
+- DAGScheduler con ejecución paralela
+- API pública: `createAgent`, `defineTool`, `defineSkill`
+
+---
+
+*Documentación Hive SDK v0.0.16*

package/docs/TEMPLATE-HIVE-APP.md

@@ -0,0 +1,360 @@
+# Template `hive-app` — Documentación Completa
+
+El template `hive-app` genera una **aplicación harness completa** lista para ejecutar. Incluye gateway HTTP/WebSocket, agente coordinador, configuración de canales, base de datos SQLite, y deployment con Docker.
+
+---
+
+## Generar una app
+
+```bash
+hive create-app my-hive
+```
+
+Esto crea el directorio `my-hive/` con la estructura completa.
+
+---
+
+## Estructura generada
+
+```
+my-hive/
+├── package.json              # Dependencias y scripts
+├── hive.config.ts            # Configuración del harness
+├── docker-compose.yml        # Deployment con Docker
+├── .env.example              # Variables de entorno de ejemplo
+├── .gitignore                # Archivos ignorados por git
+└── src/
+    ├── main.ts               # Entry point — arranca gateway + agente
+    └── agents/
+        └── coordinator.ts    # Definición del agente coordinador
+```
+
+---
+
+## Archivos y opciones
+
+### `package.json`
+
+```json
+{
+  "name": "my-hive",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "start": "bun run src/main.ts",
+    "build": "bun build src/main.ts --outdir dist --target bun"
+  },
+  "dependencies": {
+    "@johpaz/hive-sdk": "latest"
+  }
+}
+```
+
+| Script | Comando | Descripción |
+|--------|---------|-------------|
+| `dev` | `bun run src/main.ts` | Ejecutar en desarrollo |
+| `start` | `bun run src/main.ts` | Ejecutar en producción |
+| `build` | `bun build ...` | Compilar a `dist/` |
+
+---
+
+### `hive.config.ts`
+
+Configuración central del harness.
+
+```typescript
+import type { Config } from "@johpaz/hive-sdk";
+
+export default {
+  name: "my-hive",
+  gateway: {
+    host: process.env.HIVE_HOST ?? "127.0.0.1",
+    port: Number(process.env.HIVE_PORT ?? 18790),
+  },
+  channels: {
+    webchat: { enabled: true },    // Siempre habilitado
+    telegram: { enabled: false },  // Requiere TELEGRAM_BOT_TOKEN
+    discord: { enabled: false },   // Requiere DISCORD_BOT_TOKEN
+    whatsapp: { enabled: false },  // Requiere configuración adicional
+    slack: { enabled: false },     // Requiere SLACK_BOT_TOKEN
+  },
+  database: {
+    path: process.env.HIVE_DATA_DIR ?? "./data/hive.db",
+  },
+} satisfies Config;
+```
+
+#### Opciones de configuración
+
+| Opción | Tipo | Default | Descripción |
+|--------|------|---------|-------------|
+| `name` | `string` | `"my-hive"` | Nombre de la aplicación |
+| `gateway.host` | `string` | `"127.0.0.1"` | Host del gateway |
+| `gateway.port` | `number` | `18790` | Puerto del gateway |
+| `channels.webchat.enabled` | `boolean` | `true` | Canal webchat integrado |
+| `channels.telegram.enabled` | `boolean` | `false` | Bot de Telegram |
+| `channels.discord.enabled` | `boolean` | `false` | Bot de Discord |
+| `channels.whatsapp.enabled` | `boolean` | `false` | Bot de WhatsApp |
+| `channels.slack.enabled` | `boolean` | `false` | Bot de Slack |
+| `database.path` | `string` | `"./data/hive.db"` | Ruta de la base de datos SQLite |
+
+---
+
+### `src/main.ts`
+
+Entry point de la aplicación. Realiza:
+
+1. Inicializa la base de datos (`initializeDatabase`)
+2. Crea el agente coordinador (`createAgent`)
+3. Inicializa el ChannelManager
+4. Arranca el gateway (`startGateway`)
+5. Maneja shutdown graceful (`SIGINT`)
+
+```typescript
+import {
+  createAgent,
+  startGateway,
+  initializeDatabase,
+  ChannelManager,
+  logger,
+} from "@johpaz/hive-sdk";
+import config from "../hive.config.ts";
+
+const log = logger.child("app");
+
+async function main() {
+  log.info(`Starting my-hive...`);
+
+  await initializeDatabase();
+
+  const agent = await createAgent({
+    name: "coordinator",
+    provider: "openai",
+    model: "gpt-4o-mini",
+    systemPrompt: "You are a helpful AI assistant...",
+  });
+
+  const channelManager = new ChannelManager();
+  // TODO: configure channels from hive.config.ts
+
+  const gateway = await startGateway({
+    host: config.gateway?.host,
+    port: config.gateway?.port,
+    agentId: "coordinator",
+  });
+
+  log.info(`my-hive is running at http://${gateway.hostname}:${gateway.port}`);
+}
+
+main().catch((err) => {
+  log.error("Fatal error:", err);
+  process.exit(1);
+});
+```
+
+#### Personalizar el agente
+
+Puedes cambiar el `provider`, `model`, y `systemPrompt`:
+
+```typescript
+const agent = await createAgent({
+  name: "coordinator",
+  provider: "anthropic",        // "openai" | "anthropic" | "gemini" | "ollama"
+  model: "claude-3-5-sonnet-20241022",
+  systemPrompt: "Tu system prompt personalizado...",
+});
+```
+
+#### Añadir tools al agente
+
+```typescript
+import { defineTool } from "@johpaz/hive-sdk";
+
+const searchTool = defineTool({
+  name: "search",
+  description: "Search the web",
+  execute: async (args: { query: string }) => {
+    // Implementation
+    return { results: [] };
+  },
+});
+
+const agent = await createAgent({
+  name: "coordinator",
+  provider: "openai",
+  model: "gpt-4o-mini",
+  tools: [searchTool],
+});
+```
+
+---
+
+### `src/agents/coordinator.ts`
+
+Definición standalone del agente coordinador. Puedes importarlo desde `main.ts` o usarlo directamente.
+
+```typescript
+import { createAgent } from "@johpaz/hive-sdk";
+
+export const coordinatorAgent = await createAgent({
+  name: "coordinator",
+  provider: "openai",
+  model: "gpt-4o-mini",
+  systemPrompt: "You are the coordinator agent...",
+});
+```
+
+---
+
+### `docker-compose.yml`
+
+Deployment containerizado.
+
+```yaml
+services:
+  app:
+    image: oven/bun:latest
+    working_dir: /app
+    volumes:
+      - .:/app
+      - hive-data:/app/data
+    ports:
+      - "${HIVE_PORT:-18790}:18790"
+    environment:
+      - HIVE_HOST=0.0.0.0
+      - HIVE_PORT=18790
+      - HIVE_DATA_DIR=/app/data
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+    command: ["bun", "run", "src/main.ts"]
+    restart: unless-stopped
+
+volumes:
+  hive-data:
+```
+
+#### Deployment
+
+```bash
+# Copiar variables de entorno
+cp .env.example .env
+# Editar .env con tus API keys
+
+# Levantar con Docker
+docker compose up -d
+
+# Ver logs
+docker compose logs -f
+```
+
+---
+
+### `.env.example`
+
+Variables de entorno disponibles:
+
+```bash
+# Hive Harness Configuration
+HIVE_HOST=127.0.0.1
+HIVE_PORT=18790
+HIVE_DATA_DIR=./data
+
+# LLM Providers
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+
+# Channels (enable as needed)
+TELEGRAM_BOT_TOKEN=
+DISCORD_BOT_TOKEN=
+SLACK_BOT_TOKEN=
+
+# Logging
+LOG_LEVEL=info
+```
+
+| Variable | Requerida | Descripción |
+|----------|-----------|-------------|
+| `HIVE_HOST` | No | Host del gateway |
+| `HIVE_PORT` | No | Puerto del gateway |
+| `HIVE_DATA_DIR` | No | Directorio de datos SQLite |
+| `OPENAI_API_KEY` | Sí* | API key de OpenAI |
+| `ANTHROPIC_API_KEY` | Sí* | API key de Anthropic |
+| `GOOGLE_API_KEY` | Sí* | API key de Gemini |
+| `TELEGRAM_BOT_TOKEN` | No | Token del bot de Telegram |
+| `DISCORD_BOT_TOKEN` | No | Token del bot de Discord |
+| `SLACK_BOT_TOKEN` | No | Token del bot de Slack |
+| `LOG_LEVEL` | No | `debug` \| `info` \| `warn` \| `error` |
+
+\* Al menos una API key de LLM es requerida.
+
+---
+
+## Personalización avanzada
+
+### Añadir canales
+
+```typescript
+// src/main.ts
+import { TelegramChannel, DiscordChannel } from "@johpaz/hive-sdk";
+
+const channelManager = new ChannelManager(config);
+
+if (config.channels.telegram.enabled) {
+  channelManager.register("telegram", new TelegramChannel({
+    botToken: process.env.TELEGRAM_BOT_TOKEN!,
+  }));
+}
+
+if (config.channels.discord.enabled) {
+  channelManager.register("discord", new DiscordChannel({
+    botToken: process.env.DISCORD_BOT_TOKEN!,
+  }));
+}
+
+await channelManager.initialize();
+```
+
+### Añadir workers especializados
+
+```bash
+cd my-hive
+hive add-worker researcher
+hive add-worker coder
+```
+
+Esto genera `src/workers/researcher.worker.ts` y `src/workers/coder.worker.ts`.
+
+### Añadir tools
+
+```bash
+cd my-hive
+hive add-tool search-docs
+```
+
+Genera `src/tools/search-docs.ts`.
+
+### Añadir skills
+
+```bash
+cd my-hive
+hive add-skill onboarding
+```
+
+Genera `src/skills/onboarding.ts`.
+
+---
+
+## Tests del template
+
+El template incluye tests para verificar que la estructura se genera correctamente.
+
+```bash
+cd my-hive
+bun test
+```
+
+---
+
+*Documentación Hive SDK v0.0.16*