@johpaz/hive-sdk 0.0.14 → 0.0.15

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 "@hive/core";
+
+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 "@hive/core";
+
+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 "@hive/core";
+
+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 "@hive/core";
+
+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 "@hive/core";
+
+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 "@hive/core";
+
+// 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 "@hive/core";
+
+// 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 "@hive/core";
+
+// 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 "@hive/core";
+
+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 });
+```

package/docs/API-CONTEXT-COMPILER.md

@@ -0,0 +1,252 @@
+# API Reference — Context Compiler y Componentes Avanzados
+
+## Índice
+
+1. [Context Compiler](#context-compiler)
+2. [Message History](#message-history)
+3. [Scratchpad](#scratchpad)
+4. [EthicsGuard](#ethicsguard)
+5. [ACE (Tracer, Reflector, Curator)](#ace)
+6. [MCP Internals](#mcp)
+
+---
+
+## Context Compiler
+
+Compila todo el contexto necesario para cada ejecución del agente.
+
+### compileContext
+
+```typescript
+import { compileContext } from "@hive/core";
+
+const ctx = await compileContext({
+  agentId: "analyst",
+  threadId: "thread-123",
+  userMessage: "Analiza esto",
+  channel: "slack",
+  mcpManager: mcpClient,
+  isolated: false,
+});
+
+// Resultado
+console.log(ctx.systemPrompt);
+console.log(ctx.messages);   // Historial compilado
+```
+
+### Estrategias
+
+El Context Compiler implementa 4 estrategias de Context Engineering:
+
+| Estrategia | Descripción |
+|------------|-------------|
+| **ESCRIBIR** | Guardar información fuera del contexto (Scratchpad, trazas) |
+| **SELECCIONAR** | Traer solo lo relevante (FTS5 tool/skill/playbook selection) |
+| **COMPRIMIR** | Reducir tokens (compaction, tool result clearing) |
+| **AISLAR** | Separar contextos por agente (workers reciben contexto mínimo) |
+
+---
+
+## Message History
+
+### addMessage
+
+```typescript
+import { addMessage } from "@hive/core";
+
+await addMessage(
+  threadId: string,
+  role: "user" | "assistant" | "system",
+  content: string | ContentPart[],
+  options?: {
+    channel?: string;
+    tool_calls?: ToolCall[];
+  }
+);
+```
+
+### getRecentMessages
+
+```typescript
+import { getRecentMessages } from "@hive/core";
+
+const messages = await getRecentMessages(threadId, {
+  maxTokens: 32000,
+  maxMessages: 50,
+});
+```
+
+### maybeCompact
+
+Reduce el historial cuando excede el límite de tokens.
+
+```typescript
+import { maybeCompact } from "@hive/core";
+
+await maybeCompact(threadId, { channel: "slack", userId: "U123" });
+```
+
+### clearOldToolResults
+
+```typescript
+import { clearOldToolResults } from "@hive/core";
+
+const clean = clearOldToolResults(messages);
+```
+
+### ConversationStore
+
+```typescript
+import { getSummary, saveSummary, getScratchpad, saveScratchpadNote } from "@hive/core";
+
+// Resumen de conversación
+const summary = getSummary(threadId);
+
+// Notas del scratchpad
+const notes = getScratchpad(threadId, "worker-1");
+```
+
+---
+
+## Scratchpad
+
+Memoria temporal por hilo de conversación.
+
+```typescript
+import { Scratchpad } from "@hive/core";
+import { getDb } from "@hive/core";
+
+const db = getDb();
+const pad = new Scratchpad(db);
+
+// Escribir nota
+pad.write("thread-1", "mi-nota", "contenido");
+
+// Leer nota
+const value = pad.read("thread-1", "mi-nota");
+
+// Listar notas de un hilo
+const all = pad.list("thread-1");
+
+// Eliminar nota
+pad.delete("thread-1", "mi-nota");
+
+// Limpiar todas las notas de un hilo
+pad.clear("thread-1");
+```
+
+---
+
+## EthicsGuard
+
+Guardián de reglas de calidad de respuesta desde la base de datos.
+
+```typescript
+import { EthicsGuard } from "@hive/core";
+import { getDb } from "@hive/core";
+
+const db = getDb();
+const guard = new EthicsGuard(db);
+
+// Obtener reglas
+const rules = guard.getRules();              // Todas
+const rulesForRole = guard.getRules("agent"); // Con FTS5
+
+// Inyectar en system prompt
+const prompt = guard.injectIntoPrompt(
+  "Eres un asistente.",
+  rules
+);
+
+// Verificar si hay reglas
+if (guard.hasEthicsLayer()) {
+  console.log("Reglas de calidad activas");
+}
+```
+
+---
+
+## ACE (Tracer, Reflector, Curator)
+
+Sistema de Auto-Corrección por Experiencia.
+
+### Tracer
+
+```typescript
+import { saveTrace, recordLLMUsage } from "@hive/core/ace";
+
+// Guardar traza de ejecución
+saveTrace({
+  agentId: "analyst",
+  model: "gpt-4o-mini",
+  messages: 5,
+  toolCalls: ["web_search", "read_file"],
+  durationMs: 1200,
+  tokensUsed: 450,
+  success: true,
+});
+
+// Registrar uso de LLM
+recordLLMUsage({
+  model: "gpt-4o-mini",
+  inputTokens: 200,
+  outputTokens: 250,
+  durationMs: 800,
+});
+```
+
+### Reflector + Curator
+
+```typescript
+import { runReflector, runCurator } from "@hive/core/ace";
+
+// Analizar trazas y generar insights
+await runReflector();
+
+// Curar insights en reglas del playbook
+await runCurator();
+```
+
+---
+
+## MCP Internals
+
+### Config
+
+```typescript
+import type { MCPConfig, MCPServerConfig } from "@hive/core";
+
+const config: MCPConfig = {
+  servers: {
+    "my-server": {
+      transport: "stdio",        // "stdio" | "sse" | "websocket"
+      command: "npx",
+      args: ["-y", "@server/pkg"],
+      env: { KEY: "value" },
+      enabled: true,
+    },
+  },
+};
+```
+
+### Singleton
+
+```typescript
+import { setMCPManager, getMCPManager, hasMCPManager } from "@hive/core";
+
+setMCPManager(mcpManager);
+const mcp = getMCPManager();     // MCPClientManager | undefined
+const exists = hasMCPManager();   // boolean
+```
+
+### Hot Reload
+
+```typescript
+import { startMCPHotReload, stopMCPHotReload } from "@hive/core";
+
+// Watch de configuración MCP
+startMCPHotReload();
+
+// Detener watch
+stopMCPHotReload();
+```