@johpaz/hive-sdk 0.0.14 → 0.0.16

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.16] - 2026-05-28
+
+### Added
+- **Bun Workers individuales**: `createWorker()`, `WorkerPool`, `agent.worker.ts`
+  - Workers especializados con system prompt propio
+  - Ejecución en threads aislados via `Bun.Worker`
+  - Comunicación via `postMessage`/`onmessage`
+- **Gateway simplificado**: HTTP/WebSocket server con `Bun.serve()`
+  - Endpoints: `/status`, `/chat`, `/ws`
+  - Streaming de respuestas en tiempo real
+- **Channels**: Telegram, Discord, WhatsApp, Slack, Webchat
+- **Tool Runtime**: Ejecución paralela de tools via Bun Workers
+- **CLI mejorado**:
+  - `hive create-app <name>` — Generar app harness completa
+  - `hive add-tool <name>` — Generar boilerplate de tool
+  - `hive add-skill <name>` — Generar boilerplate de skill
+  - `hive add-worker <name>` — Generar Bun Worker
+- **Template hive-app**: Proyecto harness completo con Docker, config, gateway
+- **Tests del harness**: 39 tests pasando en 12 archivos
+  - Workers, Gateway, Channels, Canvas, Scheduler, Storage, Swarm, Tool Runtime
+
+### Changed
+- API pública expandida: exports de gateway, channels, canvas, scheduler, tool-runtime, workers
+- `package.json`: versión 0.0.16, descripción actualizada, bin `hive`
+- Documentación actualizada en `docs/`
+
+## [0.0.10] - 2026-05-02
+
+### Added
+- DAG Scheduler with parallel worker execution
+- Tool selector with FTS5 full-text search
+- Skill selector with semantic triggers
+- Context compiler for agent execution
+- Canvas (ACE) real-time visualization
+- Multi-channel support (Slack, Discord, Telegram, WhatsApp)
+- AgentBus for inter-agent communication
+- SQLite storage with FTS5 built-in
+- 130+ passing tests
+
+### Performance
+- 3x faster than LangChain (Bun runtime)
+- Parallel DAG execution (15x faster than sequential)
+- Streaming TTFT benchmarks
+- Worker metrics (12 tasks/sec throughput)
+
+### Documentation
+- Complete API documentation in docs/
+- README comparison with LangChain
+- Benchmark documentation
+
+## [0.0.9] - 2026-01-01
+
+### Added
+- Initial release
+- Agent execution with LLM providers
+- Basic tool and skill system
+- Gateway server

package/README.md

@@ -0,0 +1,280 @@
+# Hive SDK
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Bun-v1.3.13-000000?style=flat&logo=bun" alt="Bun">
+  <img src="https://img.shields.io/badge/TypeScript-6.0-blue?style=flat&logo=typescript">
+  <img src="https://img.shields.io/badge/License-MIT-green?style=flat">
+</p>
+
+**The Hive Agent Harness SDK** — Build, deploy, and scale AI agent applications with multi-channel support, context engineering, and swarm orchestration.
+
+> This Hive SDK powers the [Hive Harness](https://github.com/johpaz/hive). Use it to create your own harness instances without building everything from scratch.
+
+---
+
+## Paquetes
+
+| Paquete | Descripción |
+|---------|-------------|
+| `@johpaz/hive-sdk` | Core SDK + CLI — agents, tools, skills, MCP, storage, swarm, gateway, channels |
+
+## Instalación
+
+```bash
+# Install globally for the CLI
+bun install -g @johpaz/hive-sdk
+
+# Or in a project
+bun add @johpaz/hive-sdk
+```
+
+## CLI Commands
+
+### Create a full harness application
+
+```bash
+hive create-app my-hive
+```
+
+Generates a complete Hive harness with gateway, channels, and agent configuration.
+
+### Create a lightweight agent project
+
+```bash
+hive init my-agent
+```
+
+### Add a tool to your project
+
+```bash
+cd my-hive
+hive add-tool search-docs
+```
+
+### Add a skill to your project
+
+```bash
+cd my-hive
+hive add-skill onboarding
+```
+
+### Run your agent
+
+```bash
+cd my-agent
+hive run
+```
+
+---
+
+## Inicio Rápido — Programmatic API
+
+### Create an Agent
+
+```typescript
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
+
+const myTool = 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: [myTool],
+});
+
+const respuesta = await agent.run("Saluda a Juan");
+console.log(respuesta);
+```
+
+### Start a Gateway
+
+```typescript
+import { startGateway, createAgent, initializeDatabase } from "@johpaz/hive-sdk";
+
+await initializeDatabase();
+
+const agent = await createAgent({
+  name: "coordinator",
+  provider: "openai",
+  model: "gpt-4o-mini",
+});
+
+const server = await startGateway({
+  host: "127.0.0.1",
+  port: 18790,
+  agentId: "coordinator",
+});
+
+console.log(`Gateway running at http://127.0.0.1:18790`);
+```
+
+### Create a Swarm (DAG)
+
+```typescript
+import { DAGScheduler, TaskGraph } from "@johpaz/hive-sdk";
+
+const graph = new TaskGraph([
+  { id: "fetch", agentId: "fetcher", taskDescription: "Obtener datos", deps: [] },
+  { id: "process", agentId: "processor", taskDescription: "Procesar", deps: ["fetch"] },
+  { id: "report", agentId: "reporter", taskDescription: "Reportar", deps: ["process"] },
+]);
+
+const result = await new DAGScheduler().execute(graph);
+```
+
+### Multi-Channel Bot
+
+```typescript
+import { ChannelManager, TelegramChannel, DiscordChannel } from "@johpaz/hive-sdk";
+
+const manager = new ChannelManager();
+
+manager.register("telegram", new TelegramChannel({ botToken: process.env.TELEGRAM_BOT_TOKEN! }));
+manager.register("discord", new DiscordChannel({ botToken: process.env.DISCORD_BOT_TOKEN! }));
+
+await manager.startAll();
+```
+
+---
+
+## Estructura del Proyecto (SDK)
+
+```
+hive-sdk/
+├── packages/
+│   ├── core/                   # @johpaz/hive-sdk core
+│   │   └── src/
+│   │       ├── api/            # createAgent(), Agent interface
+│   │       ├── agent/          # AgentLoop, ContextCompiler, ConversationStore
+│   │       │   ├── providers/  # LLM: OpenAI, Anthropic, Gemini, Ollama
+│   │       │   └── selectors/  # FTS5: ToolSelector, SkillSelector, PlaybookSelector
+│   │       ├── tools/          # ToolRegistry + 70+ built-in tools
+│   │       ├── skills/         # SkillLoader, defineSkill()
+│   │       ├── swarm/          # DAGScheduler, TaskGraph, WorkerPool
+│   │       ├── gateway/        # HTTP/WebSocket server (Bun.serve)
+│   │       ├── channels/       # Telegram, Discord, WhatsApp, Slack, Webchat
+│   │       ├── mcp/            # MCPClientManager, transports (SSE, WS)
+│   │       ├── storage/        # SQLite (bun:sqlite) + FTS5
+│   │       ├── canvas/         # CanvasManager + A2UI emitter
+│   │       ├── scheduler/      # CronScheduler + DAG execution
+│   │       ├── ethics/         # EthicsGuard
+│   │       ├── memory/         # Scratchpad
+│   │       ├── config/         # loadConfig, loadEnv
+│   │       ├── utils/          # logger, toon, crypto, retry
+│   │       └── index.ts        # Public API barrel
+│   │
+│   └── cli/                    # Hive CLI
+│       └── src/
+│           ├── index.ts        # Entry: hive {init,create-app,add-tool,add-skill,run,test,trace}
+│           ├── commands/
+│           │   ├── init.ts
+│           │   ├── create-app.ts
+│           │   ├── add-tool.ts
+│           │   ├── add-skill.ts
+│           │   ├── run.ts
+│           │   ├── test.ts
+│           │   └── trace.ts
+│           └── templates/
+│               └── hive-app/   # Full harness template
+│                   ├── package.json
+│                   ├── hive.config.ts
+│                   ├── docker-compose.yml
+│                   ├── .env.example
+│                   └── src/
+│                       ├── main.ts
+│                       └── agents/
+│                           └── coordinator.ts
+│
+├── test/                       # Test helpers
+├── docs/                       # Documentation
+├── tsconfig.json
+└── package.json
+```
+
+---
+
+## API Pública
+
+```typescript
+import {
+  // Agent
+  createAgent,
+  defineTool,
+  defineSkill,
+  runAgent,
+  runAgentIsolated,
+
+  // Gateway
+  startGateway,
+
+  // Channels
+  ChannelManager,
+  TelegramChannel,
+  DiscordChannel,
+  WhatsAppChannel,
+  SlackChannel,
+  WebChatChannel,
+
+  // Swarm
+  DAGScheduler,
+  TaskGraph,
+  TaskNode,
+
+  // MCP
+  MCPClientManager,
+
+  // Tools
+  ToolRegistry,
+  ToolExecutor,
+  executeToolBatch,
+
+  // Storage
+  initializeDatabase,
+
+  // Config
+  loadConfig,
+
+  // Utils
+  logger,
+  retry,
+} from "@johpaz/hive-sdk";
+```
+
+---
+
+## Testing
+
+```bash
+# All tests
+bun test packages/core/src/
+
+# Tests with timeout
+bun test --timeout 30000
+
+# Specific tests
+bun test packages/core/src/tools/ToolRegistry.test.ts
+```
+
+---
+
+## 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
+```
+
+---
+
+## Licencia
+
+MIT © 2024-2025 Anomaly Co. / @Johpaz

package/docs/API-AGENTS.md

@@ -0,0 +1,316 @@
+# API Reference — Agentes
+
+## Índice
+
+1. [createAgent](#createagent)
+2. [AgentLoop](#agentloop)
+3. [Tool Selector](#tool-selector)
+4. [Skill Selector](#skill-selector)
+5. [LLM Providers](#llm-providers)
+
+---
+
+## createAgent
+
+Función de alto nivel para crear y ejecutar agentes.
+
+### Firma
+
+```typescript
+import { createAgent } from "@johpaz/hive-sdk";
+
+const agent = await createAgent(config: AgentConfig): Promise<Agent>
+```
+
+### AgentConfig
+
+```typescript
+interface AgentConfig {
+  name: string;
+  model?: string;                           // default: gpt-4o-mini
+  provider?: "openai" | "anthropic" | "gemini" | "ollama";
+  systemPrompt?: string;
+  tools?: ToolDefinition[];                 // Tools custom
+  skills?: SkillDefinition[];               // Skills custom
+  mcpServers?: Record<string, {             // Servidores MCP
+    command?: string;                       // STDIO transport
+    url?: string;                           // SSE transport
+    args?: string[];
+    env?: Record<string, string>;
+  }>;
+  maxIterations?: number;
+  workspace?: string;
+}
+```
+
+### Agent
+
+```typescript
+interface Agent {
+  readonly name: string;
+  readonly config: AgentConfig;
+
+  // Streaming chat
+  chat(message: string, opts?: {
+    threadId?: string;
+    channel?: string;
+  }): AsyncGenerator<AgentEvent>;
+
+  // Run to completion (devuelve string final)
+  run(task: string, opts?: {
+    threadId?: string;
+    channel?: string;
+  }): Promise<string>;
+}
+```
+
+### AgentEvent
+
+```typescript
+type AgentEvent =
+  | { type: "text"; content: string }
+  | { type: "tool_call"; name: string; args: Record<string, unknown> }
+  | { type: "tool_result"; name: string; result: unknown }
+  | { type: "done"; response: string };
+```
+
+### Ejemplo
+
+```typescript
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
+
+const agent = await createAgent({
+  name: "asistente",
+  provider: "openai",
+  model: "gpt-4o-mini",
+  systemPrompt: "Eres un asistente útil.",
+});
+
+// Streaming
+for await (const event of agent.chat("Hola!")) {
+  if (event.type === "text") process.stdout.write(event.content);
+}
+
+// Run to completion
+const respuesta = await agent.run("Analiza las ventas del mes");
+```
+
+---
+
+## defineTool
+
+Define una herramienta 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}!` };
+  },
+});
+```
+
+### ToolDefinition
+
+```typescript
+interface ToolDefinition {
+  name: string;
+  description: string;
+  schema?: z.ZodType;             // Validación Zod opcional
+  execute: (args: any, config?: any) => Promise<any>;
+  category?: string;
+}
+```
+
+---
+
+## defineSkill
+
+Define una composición de herramientas con triggers semánticos.
+
+```typescript
+import { defineSkill } from "@johpaz/hive-sdk";
+
+const skill = defineSkill({
+  name: "analisis-datos",
+  description: "Analiza datos y genera reportes",
+  steps: [
+    { action: "web_search", instruction: "Buscar datos relevantes" },
+    { action: "create_report", instruction: "Generar reporte" },
+  ],
+  tools: ["web_search", "create_report"],
+  triggers: ["analizar", "reporte", "datos"],
+});
+```
+
+---
+
+## AgentLoop
+
+Clase de bajo nivel para control directo del bucle del agente.
+
+```typescript
+import { AgentLoop, buildAgentLoop } from "@johpaz/hive-sdk";
+
+const loop = buildAgentLoop({ mcpManager });
+
+const stream = loop.stream(
+  { messages: [{ role: "user", content: "Hola" }] },
+  { configurable: { thread_id: "thread-1" } }
+);
+
+for await (const chunk of stream) {
+  if (chunk.agent?.messages) {
+    console.log(chunk.agent.messages[0].content);
+  }
+  if (chunk.tools?.messages) {
+    console.log("Tool result:", chunk.tools.messages);
+  }
+}
+```
+
+### StreamChunk
+
+```typescript
+interface StreamChunk {
+  agent?: { messages: any[] };
+  tools?: { messages: any[] };
+  usage?: { input_tokens: number; output_tokens: number };
+}
+```
+
+### runAgent (bajo nivel)
+
+```typescript
+import { runAgent, runAgentIsolated } from "@johpaz/hive-sdk";
+
+// Streaming
+for await (const chunk of runAgent({
+  agentId: "assistant",
+  userMessage: "Analiza las ventas",
+  threadId: "thread-123",
+})) {
+  // procesar chunk
+}
+
+// Modo aislado (para workers DAG)
+const result = await runAgentIsolated({
+  agentId: "processor",
+  taskDescription: "Procesa estos datos",
+  threadId: "dag-thread",
+});
+```
+
+---
+
+## Tool Selector
+
+Selección automática de tools basada en FTS5.
+
+```typescript
+import { selectTools, CORE_TOOL_CATALOG } from "@johpaz/hive-sdk";
+
+// Seleccionar tools relevantes
+const tools = selectTools("Buscar archivos en el proyecto");
+console.log(tools.map(t => t.name));
+
+// Con límite personalizado
+const limited = selectTools("search query", CORE_TOOL_CATALOG, 3);
+```
+
+### Constantes
+
+```typescript
+const MIN_RELEVANCE_THRESHOLD = -30;
+```
+
+### CORE_TOOL_CATALOG
+
+~50 tools built-in organizadas por categoría:
+
+| Categoría | Descripción |
+|-----------|-------------|
+| filesystem | read, write, edit, delete, list, glob |
+| web | web_search, web_fetch, browser automation |
+| projects | project/task CRUD |
+| cron | Croner-based scheduling |
+| cli | Shell command execution |
+| agents | Agent management, task delegation |
+| canvas | UI rendering, A2UI |
+| codebridge | Code execution bridge |
+| voice | TTS/STT |
+| core | save_note, notify, report_progress |
+| office | PDF, DOCX, XLSX, PPTX |
+| meeting | Meeting management |
+
+---
+
+## Skill Selector
+
+```typescript
+import { selectSkills, getMinimalSkills } from "@johpaz/hive-sdk";
+
+// Skills según mensaje
+const skills = selectSkills("Analyze the sales data");
+
+// Skills mínimos siempre disponibles
+const minimal = getMinimalSkills();
+```
+
+---
+
+## LLM Providers
+
+### Providers Soportados
+
+| Provider | Modelos | Streaming |
+|----------|---------|-----------|
+| openai | gpt-4o, gpt-4o-mini | ✅ |
+| anthropic | claude-sonnet, claude-haiku | ✅ |
+| gemini | gemini-2.5-flash | ✅ |
+| ollama | modelos locales | ✅ |
+
+### callLLM
+
+```typescript
+import { callLLM, resolveProviderConfig } from "@johpaz/hive-sdk";
+
+const config = await resolveProviderConfig("openai", "gpt-4o-mini");
+
+const response = await callLLM({
+  provider: config.provider,
+  model: config.model,
+  messages: [{ role: "user", content: "Hola" }],
+});
+```
+
+---
+
+## Errores Comunes
+
+### createAgent: no se encuentra el agente
+
+```typescript
+// El agente no necesita existir en DB — createAgent lo gestiona internamente
+// Si falla, verificar API keys en variables de entorno
+```
+
+### Tool no encontrada
+
+```typescript
+// Verificar que la tool está registrada
+const reg = new ToolRegistry();
+reg.register(myTool);
+reg.has("my_tool"); // true
+```
+
+### Context too large
+
+```typescript
+// Usar maybeCompact para reducir historial
+const { maybeCompact } = await import("../agent/Compaction.ts");
+await maybeCompact(threadId, { channel, userId });
+```