@johpaz/hive-sdk 0.0.12 → 0.0.15

package/docs/INDEX.md

@@ -0,0 +1,141 @@
+# Índice de Documentación — Hive SDK
+
+## Documentos de Usuario
+
+| 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 |
+| [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 |
+
+---
+
+## Guía de Inicio Rápido
+
+### 1. Crear Agente (nueva API)
+
+```typescript
+import { createAgent, defineTool } from "@hive/core";
+
+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");
+```
+
+### 2. Crear un Swarm
+
+```typescript
+import { DAGScheduler, TaskGraph } from "@hive/core";
+
+const graph = new TaskGraph([
+  { id: "task1", agentId: "worker", taskDescription: "Tarea 1", deps: [] },
+  { id: "task2", agentId: "worker", taskDescription: "Tarea 2", deps: ["task1"] },
+]);
+
+const result = await new DAGScheduler().execute(graph);
+```
+
+---
+
+## Estructura de Paquetes
+
+```
+packages/
+├── core/                   # @hive/core
+│   └── src/
+│       ├── agent/          # AgentLoop, ContextCompiler
+│       │   ├── providers/  # LLM providers (OpenAI, Anthropic, Gemini, Ollama)
+│       │   └── selectors/  # FTS5 ToolSelector, SkillSelector
+│       ├── tools/          # 66 built-in tools + ToolRegistry
+│       ├── skills/         # SkillLoader, defineSkill()
+│       ├── swarm/          # DAGScheduler, TaskGraph, WorkerPool
+│       │   ├── strategies/ # Parallel, Priority
+│       │   └── presets/    # HiveLearn, Research
+│       ├── mcp/            # MCPClientManager + transports
+│       ├── storage/        # SQLite (bun:sqlite) + FTS5
+│       ├── ace/            # Tracer, Reflector, Curator
+│       ├── canvas/         # CanvasManager + A2UI
+│       ├── memory/         # Scratchpad
+│       ├── ethics/         # EthicsGuard
+│       ├── config/         # loadConfig
+│       ├── utils/          # logger, toon
+│       ├── api/            # createAgent()
+│       └── index.ts        # Public API
+│
+└── cli/                    # @hive/cli
+    └── src/
+        └── commands/       # init, run, test, trace
+```
+
+---
+
+## 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)
+
+### Tool
+Función que el agente puede invocar:
+- Definida con `defineTool()`
+- Seleccionada dinámicamente via FTS5
+- Ejecutada por el worker
+
+### Skill
+Composición de tools con triggers semánticos:
+- Definida con `defineSkill()`
+- Categorización automática
+
+### Swarm (DAG)
+Ejecución paralela de múltiples agentes:
+- Nodos = tareas con dependencias
+- Topological sort automático
+- Workers paralelos con estrategias
+
+### MCP
+Model Context Protocol:
+- Servidores MCP como herramientas externas
+- Transports: STDIO, SSE, WebSocket
+
+---
+
+## Variables de Entorno
+
+```bash
+HIVE_DATA_DIR=./data          # Directorio de datos
+OPENAI_API_KEY=sk-...         # OpenAI
+ANTHROPIC_API_KEY=sk-ant-...  # Anthropic
+LOG_LEVEL=info                 # debug | info | warn | error
+```
+
+---
+
+## Tests
+
+```bash
+# Tests unitarios
+bun test packages/core/src/
+
+# Tests con timeout extendido
+bun test --timeout 60000 packages/core/src/
+```
+
+---
+
+*Documentación Hive SDK v2.0.0*

package/docs/README.md

@@ -0,0 +1,68 @@
+# Documentación — Hive SDK
+
+## 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 |
+
+## Inicio Rápido
+
+```bash
+# Instalar
+git clone https://github.com/anomalyco/hive-sdk.git
+cd hive-sdk
+bun install
+
+# Test
+bun test packages/core/src/
+```
+
+```typescript
+import { createAgent, defineTool } from "@hive/core";
+
+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);
+```
+
+## Variables de Entorno
+
+```bash
+HIVE_DATA_DIR=./data          # Directorio de datos SQLite
+OPENAI_API_KEY=sk-...         # OpenAI
+ANTHROPIC_API_KEY=sk-ant-...  # Anthropic
+LOG_LEVEL=info                 # debug | info | warn | error
+```
+
+## 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
+
+### v1.1.0
+- Streaming TTFT benchmarks
+- Worker performance metrics
+- DAGScheduler executor option fix
+
+### v1.0.0
+- Lanzamiento inicial

package/package.json

@@ -1,113 +1,62 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.0.12",
-  "description": "Hive SDK — Crear agentes IA con todo incluido: agentes, tools, skills, MCP, TTS, canales, gateway y más.",
+  "version": "0.0.15",
+  "description": "Hive SDK — Agentes AI con Context Engineering, FTS5, ACE, Swarm",
   "license": "MIT",
-  "type": "module",
-  "scripts": {
-    "build": "bun run --cwd ../.. build"
-  },
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    },
-    "./agents": {
-      "types": "./src/agents.ts",
-      "default": "./src/agents.ts"
-    },
-    "./tools": {
-      "types": "./src/tools.ts",
-      "default": "./src/tools.ts"
-    },
-    "./skills": {
-      "types": "./src/skills.ts",
-      "default": "./src/skills.ts"
-    },
-    "./mcp": {
-      "types": "./src/mcp.ts",
-      "default": "./src/mcp.ts"
-    },
-    "./tts": {
-      "types": "./src/tts.ts",
-      "default": "./src/tts.ts"
-    },
-    "./channels": {
-      "types": "./src/channels.ts",
-      "default": "./src/channels.ts"
-    },
-    "./storage": {
-      "types": "./src/storage.ts",
-      "default": "./src/storage.ts"
-    },
-    "./gateway": {
-      "types": "./src/gateway.ts",
-      "default": "./src/gateway.ts"
-    },
-    "./scheduler": {
-      "types": "./src/scheduler.ts",
-      "default": "./src/scheduler.ts"
-    },
-    "./events": {
-      "types": "./src/events.ts",
-      "default": "./src/events.ts"
-    },
-    "./state": {
-      "types": "./src/state.ts",
-      "default": "./src/state.ts"
-    },
-    "./security": {
-      "types": "./src/security.ts",
-      "default": "./src/security.ts"
-    },
-    "./config": {
-      "types": "./src/config.ts",
-      "default": "./src/config.ts"
-    },
-    "./canvas": {
-      "types": "./src/canvas.ts",
-      "default": "./src/canvas.ts"
-    },
-    "./voice": {
-      "types": "./src/voice.ts",
-      "default": "./src/voice.ts"
-    },
-    "./multimodal": {
-      "types": "./src/multimodal.ts",
-      "default": "./src/multimodal.ts"
-    },
-    "./utils": {
-      "types": "./src/utils.ts",
-      "default": "./src/utils.ts"
-    },
-    "./types": {
-      "types": "./src/types.ts",
-      "default": "./src/types.ts"
-    }
-  },
-  "peerDependencies": {
-    "typescript": "6.0.2"
+  "homepage": "https://github.com/anomalyco/hive-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anomalyco/hive-sdk.git"
   },
-  "peerDependenciesMeta": {
-    "typescript": {
-      "optional": true
-    }
+  "bugs": {
+    "url": "https://github.com/anomalyco/hive-sdk/issues"
   },
   "keywords": [
-    "hive",
-    "sdk",
-    "agents",
     "ai",
+    "agent",
     "llm",
-    "mcp",
-    "tts",
-    "multi-channel",
-    "telegram",
-    "discord",
-    "whatsapp",
-    "slack"
-  ]
-}
+    "context-engineering",
+    "fts5",
+    "swarm",
+    "ace",
+    "bun",
+    "langchain-alternative"
+  ],
+  "main": "./packages/core/src/index.ts",
+  "types": "./packages/core/src/index.ts",
+  "workspaces": [
+    "packages/core",
+    "packages/cli"
+  ],
+  "scripts": {
+    "build": "bun run typecheck",
+    "typecheck": "tsc --build --force",
+    "test": "bun test",
+    "prepublish": "echo 'No build needed - Bun runs TypeScript directly'"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@google/genai": "^1.43.0",
+    "@modelcontextprotocol/sdk": "latest",
+    "@sapphire/snowflake": "latest",
+    "async-mutex": "^0.5.0",
+    "cron-parser": "^5.5.0",
+    "croner": "^10.0.1",
+    "docx": "^9.6.1",
+    "groq-sdk": "^0.37.0",
+    "jszip": "^3.10.1",
+    "pdf-lib": "^1.17.1",
+    "mammoth": "^1.12.0",
+    "ollama": "^0.6.3",
+    "openai": "^6.18.0",
+    "pdfjs-dist": "^5.6.205",
+    "pptxgenjs": "^4.0.1",
+    "toon-format-parser": "^1.1.0",
+    "xlsx": "^0.18.5",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13",
+    "typescript": "6.0.2"
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@hive/cli",
+  "version": "0.0.15",
+  "description": "Hive CLI — init, run, test, trace",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "hive": "./src/index.ts"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hive/core": "workspace:*"
+  }
+}

package/packages/cli/src/commands/init.ts

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as process from "node:process";
+
+const TEMPLATE_DIR = join(import.meta.dir, "..", "..", "templates");
+
+const HIVE_CONFIG = `{
+  "name": "my-hive-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "dependencies": {
+    "@hive/core": "latest"
+  }
+}
+`;
+
+const HIVE_AGENT_TS = `import { createAgent, defineTool } from "@hive/core";
+
+const myTool = defineTool({
+  name: "hello",
+  description: "Say hello",
+  execute: async (args: { name?: string }) => {
+    return { greeting: \`Hello, \${args.name ?? "world"}!\` };
+  },
+});
+
+const agent = await createAgent({
+  name: "my-agent",
+  model: "gpt-4o",
+  provider: "openai",
+  tools: [myTool],
+});
+
+console.log("Agent ready:", agent.name);
+`;
+
+async function runInit() {
+	const targetDir = process.argv[3] || process.cwd();
+
+	if (existsSync(join(targetDir, "hive.json"))) {
+		console.error("A hive project already exists in this directory.");
+		process.exit(1);
+	}
+
+	writeFileSync(join(targetDir, "hive.json"), HIVE_CONFIG.trim());
+	writeFileSync(join(targetDir, "hive.agent.ts"), HIVE_AGENT_TS.trim());
+
+	console.log(`\nInitialized Hive project in ${targetDir}`);
+	console.log("\nFiles created:");
+	console.log("  hive.json       - Project configuration");
+	console.log("  hive.agent.ts   - Agent definition");
+	console.log("\nNext steps:");
+	console.log("  Run: hive run");
+}
+
+runInit();

package/packages/cli/src/commands/run.ts

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+async function runCommand() {
+	const agentFile = findAgentFile();
+	if (!agentFile) {
+		console.error("No hive.agent.ts or hive.agent.js found in current directory.");
+		console.error("Run 'hive init' to create one.");
+		process.exit(1);
+	}
+
+	console.log(`Running agent from ${agentFile}...`);
+	const { createAgent } = await import("@hive/core");
+	const agentModule = await import(agentFile);
+
+	if (agentModule.agent) {
+		const input = process.argv[3] || process.env.HIVE_INPUT || "Hello!";
+		console.log(`\n--- Agent: ${agentModule.agent.name} ---`);
+		console.log(`Input: ${input}\n`);
+
+		for await (const event of agentModule.agent.chat(input)) {
+			if (event.type === "text") {
+				process.stdout.write(event.content);
+			} else if (event.type === "tool_call") {
+				console.log(`\n[Tool: ${event.name}]`);
+			}
+		}
+		console.log("\n--- Done ---");
+	} else {
+		console.error("Agent module does not export an 'agent' instance.");
+		process.exit(1);
+	}
+}
+
+function findAgentFile(): string | null {
+	const candidates = ["hive.agent.ts", "hive.agent.js", "agent.ts", "agent.js"];
+	const cwd = process.cwd();
+	for (const name of candidates) {
+		const full = join(cwd, name);
+		if (existsSync(full)) return full;
+	}
+	return null;
+}
+
+runCommand();

package/packages/cli/src/commands/test.ts

@@ -0,0 +1,42 @@
+export {};
+async function testCommand() {
+	const filter = process.argv[3];
+
+	console.log("Hive Test Runner\n");
+
+	const { initializeDatabase, dbService } = await import("@hive/core");
+	await initializeDatabase();
+
+	const { Glob } = await import("bun");
+	const glob = new Glob("packages/core/src/**/*.{test,spec}.ts");
+	const testFiles = Array.from(glob.scanSync({ cwd: process.cwd(), absolute: true }));
+
+	const tests = filter
+		? testFiles.filter((f: string) => f.includes(filter))
+		: testFiles;
+
+	if (tests.length === 0) {
+		console.log("No tests found.");
+	} else {
+		console.log(`Found ${tests.length} test(s)\n`);
+		let passed = 0;
+		let failed = 0;
+
+		for (const test of tests as string[]) {
+			try {
+				await import(test);
+				console.log(`  ✓ ${test.split("/").pop()}`);
+				passed++;
+			} catch (err) {
+				console.error(`  ✗ ${test.split("/").pop()}: ${(err as Error).message}`);
+				failed++;
+			}
+		}
+
+		console.log(`\n${passed} passed, ${failed} failed`);
+	}
+
+	dbService.close();
+}
+
+testCommand();

package/packages/cli/src/commands/trace.ts

@@ -0,0 +1,55 @@
+export {};
+async function traceCommand() {
+	const { initializeDatabase } = await import("@hive/core");
+	const { getDb } = await import("@hive/core/storage");
+
+	await initializeDatabase();
+	const db = getDb();
+
+	const limit = parseInt(process.argv[3] || "20", 10);
+
+	console.log(`\nRecent Trace Logs (last ${limit})\n`);
+	console.log("─".repeat(80));
+
+	try {
+		const rows = db
+			.query(
+				`SELECT id, agent_id, model, tool_calls, duration_ms, tokens_used, created_at
+         FROM traces
+         ORDER BY created_at DESC
+         LIMIT ?`
+			)
+			.all(limit) as Array<{
+			id: string;
+			agent_id: string;
+			model: string;
+			tool_calls: string;
+			duration_ms: number;
+			tokens_used: number;
+			created_at: string;
+		}>;
+
+		if (rows.length === 0) {
+			console.log("No traces found.");
+			return;
+		}
+
+		for (const row of rows) {
+			console.log(`ID:        ${row.id}`);
+			console.log(`Agent:     ${row.agent_id}`);
+			console.log(`Model:     ${row.model}`);
+			console.log(`Duration:  ${row.duration_ms}ms`);
+			console.log(`Tokens:    ${row.tokens_used}`);
+			console.log(`Time:      ${row.created_at}`);
+			if (row.tool_calls) {
+				const tools = JSON.parse(row.tool_calls);
+				console.log(`Tools:     ${Array.isArray(tools) ? tools.join(", ") : row.tool_calls}`);
+			}
+			console.log("─".repeat(80));
+		}
+	} catch (err) {
+		console.log("No traces table found (run the agent first).");
+	}
+}
+
+traceCommand();

package/packages/cli/src/index.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+
+export {};
+const command = process.argv[2];
+
+switch (command) {
+	case "init":
+		await import("./commands/init.ts");
+		break;
+	case "run":
+		await import("./commands/run.ts");
+		break;
+	case "test":
+		await import("./commands/test.ts");
+		break;
+	case "trace":
+		await import("./commands/trace.ts");
+		break;
+	case "--help":
+	case "-h":
+	case undefined:
+		printHelp();
+		break;
+	default:
+		console.error(`Unknown command: ${command}`);
+		printHelp();
+		process.exit(1);
+}
+
+function printHelp() {
+	console.log(`
+Usage: hive <command> [options]
+
+Commands:
+  init         Initialize a new Hive project
+  run          Run the agent
+  test         Test tools or skills
+  trace        View trace execution logs
+
+Options:
+  --help, -h   Show this help message
+`);
+}