@johpaz/hive-sdk 0.0.15 → 0.0.17

package/docs/README.md

@@ -1,29 +1,58 @@
 # 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, defineTool, defineSkill, AgentLoop, Tool/Skill Selector, LLM Providers |
-| [API-DAG-SCHEDULER.md](API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, TaskNode, Estrategias, Presets, EventBridge |
-| [API-WORKERS-EVENTS.md](API-WORKERS-EVENTS.md) | Workers, AgentBus, EventBus, Canvas Events |
-| [API-TOOLS-SKILLS-CHANNELS.md](API-TOOLS-SKILLS-CHANNELS.md) | ToolRegistry, ToolExecutor, SkillLoader, MCP, Canvas, Storage, Config |
-| [API-CONTEXT-COMPILER.md](API-CONTEXT-COMPILER.md) | compileContext, Message History, Scratchpad, EthicsGuard, ACE, MCP Internals |
+| [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
+hives init <name>         # Inicializar proyecto agente
+hives create-app <name>   # Crear aplicación harness completa
+hives add-tool <name>     # Añadir tool
+hives add-skill <name>    # Añadir skill
+hives add-worker <name>   # Añadir Bun Worker
+hives run                 # Ejecutar agente
+hives test                # Test tools/skills
+hives trace               # Ver logs de ejecución
+```
 
 ## Inicio Rápido
 
+### 1. Crear una app harness completa
+
 ```bash
-# Instalar
-git clone https://github.com/anomalyco/hive-sdk.git
-cd hive-sdk
+hives create-app my-hive
+cd my-hive
 bun install
-
-# Test
-bun test packages/core/src/
+cp .env.example .env
+bun run dev
 ```
 
+### 2. Crear un agente simple
+
 ```typescript
-import { createAgent, defineTool } from "@hive/core";
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
 
 const tool = defineTool({
   name: "saludar",
@@ -42,27 +71,91 @@ 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
-LOG_LEVEL=info                 # debug | info | warn | error
+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
 
-### v2.0.0
-- Restructura completa a @hive/core, @hive/cli
-- Nueva API: createAgent, defineTool, defineSkill
-- Eliminados: gateway, channels, tts, voice service (migrados a hive-app)
-- FTS5 preservado como ventaja competitiva
+### v0.0.17
+- **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**: `hives create-app`, `hives add-tool`, `hives add-skill`, `hives 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`
 
-### v1.1.0
-- Streaming TTFT benchmarks
-- Worker performance metrics
-- DAGScheduler executor option fix
+---
 
-### v1.0.0
-- Lanzamiento inicial
+*Documentación Hive SDK v0.0.17*

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
+hives 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
+hives add-worker researcher
+hives add-worker coder
+```
+
+Esto genera `src/workers/researcher.worker.ts` y `src/workers/coder.worker.ts`.
+
+### Añadir tools
+
+```bash
+cd my-hive
+hives add-tool search-docs
+```
+
+Genera `src/tools/search-docs.ts`.
+
+### Añadir skills
+
+```bash
+cd my-hive
+hives 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.17*

package/package.json

@@ -1,29 +1,36 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.0.15",
-  "description": "Hive SDK — Agentes AI con Context Engineering, FTS5, ACE, Swarm",
+  "version": "0.0.17",
+  "private": false,
+  "description": "Hive SDK — The Agent Harness SDK. Build, deploy, and scale AI agent applications with multi-channel support, context engineering, and swarm orchestration.",
   "license": "MIT",
-  "homepage": "https://github.com/anomalyco/hive-sdk#readme",
+  "homepage": "https://github.com/johpaz/hive-sdk#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/anomalyco/hive-sdk.git"
+    "url": "https://github.com/johpaz/hive-sdk.git"
   },
   "bugs": {
-    "url": "https://github.com/anomalyco/hive-sdk/issues"
+    "url": "https://github.com/johpaz/hive-sdk/issues"
   },
   "keywords": [
     "ai",
     "agent",
     "llm",
+    "harness",
     "context-engineering",
     "fts5",
     "swarm",
     "ace",
     "bun",
-    "langchain-alternative"
+    "langchain-alternative",
+    "multi-channel",
+    "gateway"
   ],
   "main": "./packages/core/src/index.ts",
   "types": "./packages/core/src/index.ts",
+  "bin": {
+    "hives": "./packages/cli/bin/hives"
+  },
   "workspaces": [
     "packages/core",
     "packages/cli"

package/packages/cli/bin/hives

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../src/index.ts");

package/packages/cli/src/commands/add-skill.ts

@@ -0,0 +1,42 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as process from "node:process";
+
+async function runAddSkill() {
+  const skillName = process.argv[3];
+
+  if (!skillName) {
+    console.error("Usage: hive add-skill <name>");
+    process.exit(1);
+  }
+
+  const skillsDir = join(process.cwd(), "src", "skills");
+  const filePath = join(skillsDir, `${skillName}.ts`);
+
+  if (existsSync(filePath)) {
+    console.error(`Skill '${skillName}' already exists.`);
+    process.exit(1);
+  }
+
+  mkdirSync(skillsDir, { recursive: true });
+
+  const content = `import { defineSkill } from "@johpaz/hive-sdk";
+
+export const ${skillName}Skill = defineSkill({
+  name: "${skillName}",
+  description: "Description of what ${skillName} skill does.",
+  steps: [
+    {
+      name: "step-1",
+      description: "First step of the skill",
+      tool: "notify",
+    },
+  ],
+});
+`;
+
+  writeFileSync(filePath, content);
+  console.log(`✅ Created skill: ${filePath}`);
+}
+
+runAddSkill();

package/packages/cli/src/commands/add-tool.ts

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as process from "node:process";
+
+function toPascalCase(str: string): string {
+  return str.replace(/[-_](.)/g, (_, char) => char.toUpperCase()).replace(/^(.)/, (_, char) => char.toUpperCase());
+}
+
+async function runAddTool() {
+  const toolName = process.argv[3];
+
+  if (!toolName) {
+    console.error("Usage: hive add-tool <name>");
+    process.exit(1);
+  }
+
+  const toolsDir = join(process.cwd(), "src", "tools");
+  const filePath = join(toolsDir, `${toolName}.ts`);
+
+  if (existsSync(filePath)) {
+    console.error(`Tool '${toolName}' already exists.`);
+    process.exit(1);
+  }
+
+  mkdirSync(toolsDir, { recursive: true });
+
+  const className = toPascalCase(toolName) + "Tool";
+
+  const content = `import { defineTool } from "@johpaz/hive-sdk";
+
+export const ${toolName} = defineTool({
+  name: "${toolName}",
+  description: "Description of what ${toolName} does.",
+  execute: async (args: { input: string }) => {
+    // TODO: implement tool logic
+    return { result: args.input };
+  },
+});
+`;
+
+  writeFileSync(filePath, content);
+  console.log(`✅ Created tool: ${filePath}`);
+}
+
+runAddTool();