@johpaz/hive-sdk 0.1.6 → 0.2.0

package/docs/API-WORKERS-EVENTS.md

@@ -1,299 +0,0 @@
-# API Reference — Workers y Eventos
-
-## Índice
-
-1. [Bun Workers](#bun-workers)
-2. [createWorker](#createworker)
-3. [WorkerPool](#workerpool)
-4. [AgentBus](#agentbus)
-5. [EventBus](#eventbus)
-6. [Canvas Events](#canvas-events)
-
----
-
-## Bun Workers
-
-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.
-
-### 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 { 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);
-
-researcher.terminate();
-```
-
-### 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
-
-Gestiona un pool de Bun Workers para ejecución paralela.
-
-### Firma
-
-```typescript
-import { WorkerPool } from "@johpaz/hive-sdk";
-
-const pool = new WorkerPool(config?: WorkerPoolConfig);
-```
-
-### WorkerPoolConfig
-
-```typescript
-interface WorkerPoolConfig {
-  maxWorkers?: number;        // Default: 4
-  taskTimeoutMs?: number;     // Default: 120000
-  workerConfig?: WorkerConfig;
-}
-```
-
-### Métodos
-
-```typescript
-// Ejecutar una tarea
-pool.execute(task: PoolTask): Promise<PoolTaskResult>
-
-// 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...`,
-});
-```
-
----
-
-## AgentBus
-
-Sistema de eventos singleton para comunicación entre agentes.
-
-```typescript
-import { agentBus, getUnreadMessagesForWorker } from "@johpaz/hive-sdk";
-
-// Publicar evento
-agentBus.publish("worker:task_started", { taskId: "task-1" }, "worker-1");
-
-// Suscribirse
-const unsub = agentBus.subscribe("worker:task_completed", (data) => {
-  console.log("Task completed:", data);
-});
-
-// Unsubscribe
-unsub();
-```
-
-### Métodos Helper
-
-```typescript
-import {
-  getUnreadMessagesForWorker,
-  getProjectMessageHistory,
-} from "@johpaz/hive-sdk";
-
-const messages = getUnreadMessagesForWorker("worker-1");
-const history = getProjectMessageHistory("project-1");
-```
-
----
-
-## EventBus
-
-EventBus global singleton (eventos del sistema).
-
-```typescript
-import { eventBus } from "@johpaz/hive-sdk";
-
-// Escuchar eventos
-eventBus.on("agent:start", (data) => {
-  console.log("Agent started:", data);
-});
-
-// Emitir eventos
-eventBus.emit("agent:complete", { agentId: "a1", result: "ok" });
-```
-
----
-
-## Canvas Events
-
-Eventos de actualización visual del canvas.
-
-```typescript
-import { emitCanvas, subscribeCanvas, unsubscribeCanvas } from "@johpaz/hive-sdk";
-
-// 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" },
-});
-
-// Desuscribirse
-unsubscribeCanvas(handler);
-```
-
-### CanvasManager
-
-```typescript
-import { CanvasManager } from "@johpaz/hive-sdk";
-
-const canvas = new CanvasManager();
-```
-
----
-
-*Documentación Hive SDK v0.0.17*

package/docs/HIVE-HARNESS.md

@@ -1,113 +0,0 @@
-# Hive Harness — durable task execution
-
-The `harness` module (`@johpaz/hive-sdk/harness`) is the SDK's durable-execution
-layer: a HiveDB-backed job queue with crash recovery, checkpointable runs,
-retry with backoff, idempotent submission, goal verification, and proof
-packets. It's what lets a host app (a `hive-app`, or a production service like
-Hive Cloud) survive a process restart mid-task without losing work or
-double-executing a tool call.
-
-It is deliberately **not** wired into the agent loop automatically, and it has
-no built-in notion of "chat" vs "project task" vs any other app-specific job
-type — job `type` and run `kind` are plain strings. The host app defines its
-own vocabulary and registers executors for it. This is the same infrastructure
-that powers `hive`'s durable-queue harness, generalized so any SDK consumer
-can reuse it instead of re-implementing crash-safe job execution from scratch.
-
-## Architecture
-
-| Piece | File | Responsibility |
-|---|---|---|
-| `JobDoc` / `HarnessRunDoc` / `ProofPacketDoc` | `collections.ts` | HiveDB document shapes |
-| `db-helpers` | `db-helpers.ts` | `nextId`, `updateDoc`, `findByAny` — primitives HiveDB's `Collection` doesn't provide directly |
-| `job-store` | `job-store.ts` | Durable job persistence: claim/lease/complete/fail/retry, all via OCC |
-| `run-store` | `run-store.ts` | Checkpoint + lease for a single durable run (messages, iteration/token counters, pending tool calls) |
-| `durable-queue` | `durable-queue.ts` | `DurableLaneQueue` — FIFO+priority per lane, global concurrency cap, executor registry |
-| `goal-verifier` | `goal-verifier.ts` | `verifyGoal()` — deterministic check tool or LLM verifier, single goal or a list of acceptance criteria |
-| `run-epoch` | `run-epoch.ts` | Fixed-worker epoch fingerprint (provider/model/app-version/tool-catalog) |
-| `proof-packet` | `proof-packet.ts` | Compressed evidence artifact for a completed run |
-| `reconcile` | `reconcile.ts` | `reconcileOnBoot()` — crash repair + retention cap, call once at startup |
-
-## Durable queue semantics
-
-- **Lanes**: a lane (e.g. a session id, or `task:<id>`) runs at most one job
-  at a time, FIFO within the lane, ordered by `priority` then creation order.
-- **Global concurrency**: `maxGlobalConcurrency` caps how many jobs run at
-  once across all lanes (default 4). Types listed in `nonRetryableTypes`
-  (default `["chat_turn"]`) bypass this cap — a busy batch of background jobs
-  must not make an interactive/user-facing job type stop responding.
-- **Leases**: a claimed job gets a lease (default 30 min); the queue renews
-  it every 30s while executing. A lease that expires (crashed process) is
-  reclaimed to `pending` or marked `interrupted` once `attempts >=
-  max_attempts` — checked by `reconcileOnBoot()` at startup and by the
-  queue's periodic maintenance tick thereafter.
-- **Executors**: register one per job type with `registerExecutor(type, fn)`.
-  An executor receives the `JobDoc`, an `AbortSignal` (fired on cancel or
-  `taskTimeoutMs`), and any live callbacks passed to `enqueue()`.
-
-## Retry & backoff
-
-Two independent retry mechanisms:
-
-1. **Crash retries** (`attempts` / `max_attempts`) — bumped on every claim,
-   checked by `reclaimOrInterrupt` after a lease expires. This is about
-   *the process dying*, not the job failing logically.
-2. **Logical-failure retries** (`retry_count` / `JobRetryPolicy`) — when an
-   executor returns `{ok: false, retryable: true}` (the default unless set
-   `false`), `failJobOrRetry` reschedules the job with exponential backoff +
-   jitter instead of failing it immediately:
-
-   ```ts
-   delay = min(maxDelayMs, initialDelayMs * backoffMultiplier ** retryCount)
-         * (1 + jitter * random())
-   ```
-
-   Once `retryCount >= policy.maxRetries`, the job fails terminally. Types in
-   `nonRetryableTypes` never take this path — a failed interactive turn
-   should surface to the user immediately, not silently retry later.
-
-## Idempotency
-
-`createJob`/`enqueue` accept an optional `idempotency_key`. A repeated key
-returns the existing job (whatever its status — pending, running, completed,
-or terminally failed) instead of creating a duplicate, so a retried HTTP
-request from a caller doesn't double-enqueue work.
-
-## Goal verification & acceptance criteria
-
-`verifyGoal()` answers "was this met" for a single goal or — when
-`acceptance` criteria are supplied — for each criterion independently (its
-own optional `checkTool`, or an LLM judgment against its own description).
-The overall verdict is the conjunction of all criteria. The harness has no
-built-in tool registry: pass a `runCheckTool` callback that resolves a
-`checkTool` name to something the host app can actually execute.
-
-## Proof packets
-
-`buildProofPacket()` persists a compressed evidence artifact once a run
-finishes: intended outcome, per-criterion results, checks run, evidence
-snippets, known limits, and the run's fixed-worker epoch. Useful as an
-audit trail without having to replay the full run transcript.
-
-## Setup
-
-```ts
-import {
-  ensureHarnessIndexes,
-  reconcileOnBoot,
-  initDurableQueue,
-  registerExecutor,
-  getBootId,
-} from "@johpaz/hive-sdk/harness";
-
-await ensureHarnessIndexes();     // idempotent — safe every boot
-await reconcileOnBoot(getBootId());
-
-registerExecutor("my_job_type", async (job, signal) => {
-  // ... do the work, honoring `signal` for cancellation/timeout
-  return { ok: true, result: "done" };
-});
-
-const queue = initDurableQueue({ maxGlobalConcurrency: 4 });
-await queue.enqueue({ lane: "session-1", type: "my_job_type", run_id: "r1", payload: {} });
-```

package/docs/INDEX.md

@@ -1,190 +0,0 @@
-# Í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
-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 "@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-5.6-luna",
-  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)
-│       │   └── tool-selector.ts, skill-selector.ts, playbook-selector.ts (BM25 sobre HiveDB)
-│       ├── 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/        # HiveDB (colecciones + BM25)
-│       ├── 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 por búsqueda BM25.
-
-### 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.17*