@johpaz/hive-sdk 0.1.6 → 0.2.0

package/bunfig.toml

@@ -1,9 +0,0 @@
-[test]
-# Fija HIVE_DB_PATH=":memory:" antes de que cargue cualquier módulo — ver test/preload.ts.
-# Sin esto la suite abre la base real del usuario (~/.hive/data/hive) y le escribe.
-preload = ["./test/preload.ts"]
-timeout = 30000
-randomize = false
-
-[install]
-registry = "https://registry.npmjs.org/"

package/docs/API-AGENTS.md

@@ -1,367 +0,0 @@
-# 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;         // id tal como lo nombra su dueño, ej. "claude-opus-5"
-  provider?: Provider;    // cualquiera de los 16 del catálogo
-  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;
-}
-```
-
-La config **se persiste en la fila del agente**, que es de donde el loop resuelve
-provider y modelo en cada turno. Consecuencias que conviene tener presentes:
-
-- `model` exige `provider`: el mismo modelo lo sirven varios providers y la clave
-  del catálogo depende de cuál. Sin provider, `createAgent` lanza.
-- El modelo tiene que existir en `SEED_DATA.models`, o lanza con el nombre del
-  provider al que no pertenece.
-- `name` deriva el id del agente (`"Mi Agente"` → `mi_agente`), así que dos
-  `createAgent` con el mismo nombre comparten fila e historial.
-- Las tools pasadas acá quedan registradas **y** indexadas, así que el modelo
-  puede descubrirlas con `search_knowledge` como a las nativas.
-
-> Hasta 0.1.5 `provider`, `model`, `maxIterations`, `skills` y `workspace` se
-> aceptaban y se descartaban: el agente corría con lo que hubiera en la base.
-
-### 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-5.6-luna",
-  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 por búsqueda BM25 sobre el índice de capacidad.
-
-```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
-
-58 tools built-in organizadas por categoría:
-
-| Categoría | # | Descripción |
-|-----------|---|-------------|
-| agents | 15 | delegación (`task_delegate`, `task_revise`), memoria, catálogo de modelos |
-| web | 10 | `web_search`, `web_fetch`, automatización de browser, `artifact_inspect` |
-| cron | 8 | scheduling con Croner |
-| office | 8 | PDF, DOCX, XLSX, PPTX |
-| filesystem | 7 | read, write, edit, delete, list, glob, exists |
-| a2ui | 4 | superficies de UI generadas por el agente |
-| core | 4 | `save_note`, `notify`, `report_progress`, `search_knowledge` |
-| cli | 1 | ejecución de comandos |
-| api | 1 | `api_request` |
-
-Las categorías `projects`, `canvas`, `codebridge`, `voice` y `meeting`
-desaparecieron en 0.1.5 junto con sus tools.
-
----
-
-## 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
-
-16 providers, todos sembrados con su catálogo de modelos y su precio por millón
-de tokens. `provider` en `createAgent` acepta cualquiera de estos ids.
-
-| Provider | Adapter | Notas |
-|----------|---------|-------|
-| `anthropic` | nativo | extended thinking, round-trip de thinking blocks |
-| `gemini` | nativo | REST v1beta |
-| `ollama` | nativo | modelos locales, flag `think` |
-| `openai` | OpenAI-compat | Sol / Terra / Luna |
-| `deepseek`, `kimi` | OpenAI-compat | round-trip de `reasoning_content` |
-| `mistral`, `groq`, `qwen`, `minimax` | OpenAI-compat | |
-| `z-ai` | OpenAI-compat | sirve en `/api/paas/v4`, no en `/v1` |
-| `hiveagents` | OpenAI-compat | |
-| `nvidia`, `openrouter`, `opencode-go`, `modelscope` | OpenAI-compat | **revendedores** |
-
-Los cuatro revendedores prefijan sus ids de modelo con su propio id de provider
-(`modelscope/Qwen/Qwen3.5-397B-A17B`), porque sirven modelos de terceros que se
-solapan entre sí y la colección `models` se indexa por una sola clave. El
-prefijo no llega al cable: el adapter lo quita antes del request.
-
-```typescript
-import { catalogModelKey, wireModelId } from "@johpaz/hive-sdk";
-
-catalogModelKey("modelscope", "Qwen/Qwen3.5-397B-A17B"); // modelscope/Qwen/Qwen3.5-397B-A17B
-wireModelId("modelscope", "modelscope/Qwen/Qwen3.5-397B-A17B"); // Qwen/Qwen3.5-397B-A17B
-```
-
-### Errores del provider
-
-`callLLM` nunca lanza: devuelve `stop_reason: "error"` con un campo `error`
-tipado. Chequealo antes de persistir `content` en cualquier lado — es texto para
-mostrar, no salida del modelo.
-
-```typescript
-const response = await callLLM({ ... });
-
-if (response.stop_reason === "error") {
-  console.error(response.error?.message);
-  // HTTP 404/410 → el proveedor retiró el modelo; reintentar no sirve.
-  if (response.error?.modelUnavailable) selectAnotherModel();
-}
-```
-
-### callLLM
-
-```typescript
-import { callLLM, resolveProviderConfig } from "@johpaz/hive-sdk";
-
-const config = await resolveProviderConfig("openai", "gpt-5.6-luna");
-
-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

@@ -1,249 +0,0 @@
-# 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 "@johpaz/hive-sdk";
-
-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 (selección BM25 de tool/skill/playbook) |
-| **COMPRIMIR** | Reducir tokens (compaction, tool result clearing) |
-| **AISLAR** | Separar contextos por agente (workers reciben contexto mínimo) |
-
----
-
-## Message History
-
-### addMessage
-
-```typescript
-import { addMessage } from "@johpaz/hive-sdk";
-
-await addMessage(
-  threadId: string,
-  role: "user" | "assistant" | "system",
-  content: string | ContentPart[],
-  options?: {
-    channel?: string;
-    tool_calls?: ToolCall[];
-  }
-);
-```
-
-### getRecentMessages
-
-```typescript
-import { getRecentMessages } from "@johpaz/hive-sdk";
-
-const messages = await getRecentMessages(threadId, {
-  maxTokens: 32000,
-  maxMessages: 50,
-});
-```
-
-### maybeCompact
-
-Reduce el historial cuando excede el límite de tokens.
-
-```typescript
-import { maybeCompact } from "@johpaz/hive-sdk";
-
-await maybeCompact(threadId, { channel: "slack", userId: "U123" });
-```
-
-### clearOldToolResults
-
-```typescript
-import { clearOldToolResults } from "@johpaz/hive-sdk";
-
-const clean = clearOldToolResults(messages);
-```
-
-### ConversationStore
-
-```typescript
-import { getSummary, saveSummary, getScratchpad, saveScratchpadNote } from "@johpaz/hive-sdk";
-
-// 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 "@johpaz/hive-sdk";
-
-const pad = new Scratchpad();
-
-await pad.write("thread-1", "mi-nota", "contenido");
-const value = await pad.read("thread-1", "mi-nota");
-const all = await pad.list("thread-1");   // { "mi-nota": "contenido" }
-await pad.delete("thread-1", "mi-nota");
-await pad.clear("thread-1");
-```
-
-El scratchpad se inyecta al system prompt en cada turno bajo
-`# SCRATCHPAD (Persistent Notes)`, comprimido con TOON. La clase es una fachada
-sobre las funciones de `conversation-store`: hasta 0.1.5 tenía implementación
-propia y, como usaba el mismo id, escribía las mismas filas con un documento
-incompleto que rompía el orden por recencia.
-
----
-
-## EthicsGuard
-
-Capa opcional de reglas de calidad de respuesta, leídas de la colección
-`playbook` (`category: "response_quality"`).
-
-```typescript
-import { EthicsGuard } from "@johpaz/hive-sdk";
-
-const guard = new EthicsGuard();
-
-const rules = await guard.getRules();                     // todas las activas
-const rulesForRole = await guard.getRules("coordinator"); // filtra por applicable_to
-
-const prompt = guard.injectIntoPrompt("Eres un asistente.", rules);
-
-if (await guard.hasEthicsLayer()) {
-  console.log("Reglas de calidad activas");
-}
-```
-
-> El constructor ya no recibe un handle de base y todos los métodos son async:
-> hasta 0.1.5 la clase armaba SQL a mano contra la tabla `playbook` y hacía un
-> JOIN con la tabla virtual `playbook_fts`. Ninguna de las dos existe.
-
-**Esto no es la ética constitucional del agente.** Esa vive en la colección
-`ethics` y la ensambla `buildSystemPrompt()` como primera sección, completa y sin
-comprimir. `EthicsGuard` es un complemento para hosts que quieran inyectar,
-además, reglas aprendidas por ACE.
-
----
-
-## 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-5.6-luna",
-  messages: 5,
-  toolCalls: ["web_search", "read_file"],
-  durationMs: 1200,
-  tokensUsed: 450,
-  success: true,
-});
-
-// Registrar uso de LLM
-recordLLMUsage({
-  model: "gpt-5.6-luna",
-  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 "@johpaz/hive-sdk";
-
-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 "@johpaz/hive-sdk";
-
-setMCPManager(mcpManager);
-const mcp = getMCPManager();     // MCPClientManager | undefined
-const exists = hasMCPManager();   // boolean
-```
-
-### Hot Reload
-
-```typescript
-import { startMCPHotReload, stopMCPHotReload } from "@johpaz/hive-sdk";
-
-// Watch de configuración MCP
-startMCPHotReload();
-
-// Detener watch
-stopMCPHotReload();
-```