@johpaz/hive-sdk 0.4.3 → 0.4.5

package/docs/API-DAG-SCHEDULER.md

@@ -0,0 +1,291 @@
+# API Reference — DAG Scheduler
+
+## Índice
+
+1. [Arquitectura](#arquitectura)
+2. [TaskNode](#tasknode)
+3. [TaskGraph](#taskgraph)
+4. [DAGScheduler](#dagscheduler)
+5. [Estrategias](#estrategias)
+6. [Presets](#presets)
+7. [EventBridge](#eventbridge)
+8. [Errores Comunes](#errores-comunes)
+
+---
+
+## Arquitectura
+
+El DAG Scheduler orquesta la ejecución de grafos acíclicos dirigidos (DAG) de tareas.
+
+```
+TaskNode → TaskGraph → DAGScheduler
+                           │
+            ┌──────────────┼──────────────┐
+            ▼              ▼              ▼
+        Worker 1        Worker 2       Worker 3
+       (agente)        (agente)       (agente)
+```
+
+---
+
+## TaskNode
+
+Representa una tarea individual en el grafo.
+
+### TaskNodeConfig
+
+```typescript
+import { TaskNode } from "@johpaz/hive-sdk";
+
+interface TaskNodeConfig {
+  id: string;
+  agentId: string;
+  name?: string;
+  taskDescription: string;
+  deps: string[];
+  priority?: number;
+  timeout?: number;
+  maxRetries?: number;
+}
+```
+
+### Estados
+
+```typescript
+type NodeStatus = "PENDING" | "READY" | "RUNNING" | "COMPLETED" | "FAILED";
+```
+
+### Ejemplo
+
+```typescript
+const node = new TaskNode({
+  id: "fetch-data",
+  agentId: "fetcher",
+  taskDescription: "Obtener datos de API",
+  deps: [],
+});
+node.markRunning();
+// ... ejecutar ...
+node.markCompleted("datos obtenidos");
+```
+
+---
+
+## TaskGraph
+
+Grafo acíclico dirigido de tareas.
+
+```typescript
+import { TaskGraph } from "@johpaz/hive-sdk";
+
+const graph = new TaskGraph([
+  { id: "a", agentId: "worker", taskDescription: "Tarea A", deps: [] },
+  { id: "b", agentId: "worker", taskDescription: "Tarea B", deps: ["a"] },
+  { id: "c", agentId: "worker", taskDescription: "Tarea C", deps: ["a"] },
+  { id: "d", agentId: "worker", taskDescription: "Tarea D", deps: ["b", "c"] },
+]);
+
+// Nodos listos para ejecutar (sin deps pendientes)
+const ready = graph.getReadyNodes();
+
+// IDs de nodos completados
+const completed = graph.getCompletedIds();
+
+// Nodos recién listos tras completar uno
+const newlyReady = graph.getNewlyReadyIds(new Set(["a"]));
+
+// Resultados de dependencias
+const depResults = graph.getDepResults("d");
+
+// Progreso
+const progress = graph.getProgress();
+// { total: 4, completed: 1, running: 0, failed: 0, pending: 3, percentComplete: 25 }
+```
+
+---
+
+## DAGScheduler
+
+Orquestador principal de la ejecución.
+
+```typescript
+import { DAGScheduler, TaskGraph } from "@johpaz/hive-sdk";
+
+const graph = new TaskGraph([
+  { id: "fetch", agentId: "fetcher", taskDescription: "Fetch data", deps: [] },
+  { id: "process", agentId: "processor", taskDescription: "Process", deps: ["fetch"] },
+  { id: "save", agentId: "saver", taskDescription: "Save", deps: ["process"] },
+]);
+
+const scheduler = new DAGScheduler({
+  maxConcurrentWorkers: 2,
+});
+
+const result = await scheduler.execute(graph);
+
+console.log(`Success: ${result.success}`);
+console.log(`Duration: ${result.totalDurationMs}ms`);
+```
+
+### DAGResult
+
+```typescript
+interface DAGResult {
+  swarmId: string;
+  totalDurationMs: number;
+  completed: NodeSummary[];
+  failed: NodeSummary[];
+  success: boolean;
+}
+
+interface NodeSummary {
+  id: string;
+  name: string;
+  status: "COMPLETED" | "FAILED";
+  durationMs: number;
+  result?: string;
+  error?: string;
+  retries: number;
+}
+```
+
+### Control
+
+```typescript
+scheduler.abort();    // Abortar ejecución en curso
+```
+
+---
+
+## Estrategias
+
+### ParallelStrategy (FIFO)
+
+```typescript
+import { ParallelStrategy } from "@johpaz/hive-sdk";
+
+const strategy = new ParallelStrategy();  // Orden de llegada
+```
+
+### PriorityStrategy
+
+```typescript
+import { PriorityStrategy } from "@johpaz/hive-sdk";
+
+const strategy = new PriorityStrategy();  // Por prioridad + path crítico
+```
+
+### Custom Strategy
+
+```typescript
+import type { ExecutionStrategy } from "@johpaz/hive-sdk";
+
+const myStrategy: ExecutionStrategy = {
+  initialize(nodes) { /* precomputar */ },
+  pick(nodes) { return nodes[0]; },  // FIFO
+};
+```
+
+---
+
+## Presets
+
+Grafos predefinidos.
+
+### ResearchPreset
+
+```typescript
+import { createResearchGraph } from "@hive/core/swarm/presets";
+
+const graph = createResearchGraph({
+  agents: { researcher: "researcher-id", writer: "writer-id" },
+  query: "Análisis de mercado",
+});
+```
+
+### HiveLearnPreset
+
+```typescript
+import { createHiveLearnGraph } from "@hive/core/swarm/presets";
+
+const graph = createHiveLearnGraph({
+  agents: { teacher: "teacher-id", student: "student-id" },
+  topic: "Machine Learning",
+});
+```
+
+---
+
+## EventBridge
+
+Puente de eventos entre el scheduler y el resto del sistema.
+
+```typescript
+import { EventBridge } from "@johpaz/hive-sdk";
+
+const bridge = new EventBridge("swarm-123", "project-1", "coordinator-1");
+
+bridge.onTaskCompleted = (node, progress) => {
+  console.log(`${node.name}: ${progress.percentComplete}%`);
+};
+
+bridge.onSwarmCompleted = (result) => {
+  console.log(`Swarm completed. Success: ${result.success}`);
+};
+```
+
+---
+
+## IAgentExecutor
+
+```typescript
+import type { IAgentExecutor } from "@johpaz/hive-sdk";
+
+const myExecutor: IAgentExecutor = {
+  async execute(node, depResults, threadId) {
+    const context = Object.values(depResults).join("\n");
+    return await myCustomFunction(node.taskDescription, context);
+  },
+};
+
+const result = await scheduler.execute(graph, { executor: myExecutor });
+```
+
+---
+
+## Errores Comunes
+
+### Cyclic dependency detected
+
+```typescript
+// ❌ Ciclo: a→b→a
+[{ id: "a", deps: ["b"] }, { id: "b", deps: ["a"] }];
+
+// ✅ Sin ciclo
+[{ id: "a", deps: [] }, { id: "b", deps: ["a"] }];
+```
+
+### Task timeout
+
+```typescript
+// Configurar timeout razonable
+const config = { id: "task", agentId: "w", taskDescription: "...", deps: [], timeout: 30000 };
+```
+
+## Errores y utilidades
+
+| | |
+|---|---|
+| `CyclicDependencyError` | El grafo tiene un ciclo: no hay orden posible. Se detecta al construirlo, no al ejecutarlo. |
+| `TaskTimeoutError` | Un nodo agotó su ventana. Lleva el id del nodo. |
+| `TaskFailureError` | Un nodo falló; sus dependientes se marcan sin llegar a correr. |
+
+`defaultInvoker` es cómo se invoca a un agente por defecto en `runRoleSwarm`
+(`runAgentIsolated`). Se puede reemplazar para instrumentar o para tests, sin
+tocar la topología.
+
+`createTaskHandler` · `notifyTaskCompletion` · `setSchedulerForCleanup` conectan
+el enjambre con el scheduler: son lo que hace que una tarea programada pueda
+disparar un grafo y que su finalización se notifique.
+
+*Documentación Hive SDK — ver `version` en package.json*

package/docs/API-HOOKS.md

@@ -0,0 +1,147 @@
+# API-HOOKS — engancharse al ciclo de vida
+
+## Por qué existe
+
+`HooksConfigSchema` declaraba 14 hooks en la configuración y **ninguno se
+invocaba**: era un esquema sin implementación. Quien lo encontrara asumiría que
+funciona, que es peor que no tenerlo.
+
+Ahora están conectados, con dos formas:
+
+- **Callbacks en proceso** (`registerHook`) — tipados, sin costo de arranque, y
+  pueden **devolver una decisión**. Es el primitivo: quien consume el SDK ya está
+  en el mismo proceso.
+- **Scripts externos** (`hooks.scripts` en la configuración) — para quien no
+  escribe TypeScript. Se montan encima del primitivo. Cuestan un `Bun.spawn` por
+  invocación, así que conviene reservarlos para lo que no ocurre en cada tool call.
+
+Sólo están los cinco con un uso claro. Los otros nueve del esquema original
+quedaron fuera a propósito: cada hook es una promesa que después hay que
+sostener, y uno que nadie usa es superficie que envejece mal.
+
+```typescript
+import { registerHook } from "@johpaz/hive-sdk/hooks";
+```
+
+## Los cinco
+
+| Hook | Cuándo | Puede bloquear |
+|---|---|---|
+| `beforeToolCall` | Antes de ejecutar una tool | **sí** |
+| `afterToolCall` | Con el resultado, haya salido bien o mal | no |
+| `beforeCompaction` | Antes de comprimir el historial | no |
+| `sessionStart` | Al abrir una conversación (crearla o reabrirla) | no |
+| `sessionEnd` | Al cerrarla (archivarla o borrarla) | no |
+
+## Bloquear una tool
+
+```typescript
+registerHook("beforeToolCall", (ctx) => {
+  if (ctx.toolName === "cli_exec" && String(ctx.args.command).includes("curl")) {
+    return { block: true, reason: "las llamadas de red salen por api_request" };
+  }
+});
+```
+
+La tool **no se ejecuta**, y el motivo le llega al modelo como resultado, para
+que sepa por qué no se hizo en vez de reintentar a ciegas.
+
+Detalles que importan:
+
+- **El primero que bloquea gana.** No tiene sentido seguir preguntando cuando ya
+  hay una negativa.
+- **Un hook que lanza no bloquea.** Un observador roto no debería frenar el
+  trabajo; se registra el error y se sigue.
+- **Se aplica a las tools que corren en un worker también.** El enganche está en
+  `executeToolBatch`, no en la ejecución del hilo principal: engancharlo abajo
+  dejaría la mitad de las llamadas sin revisar, que en un hook de política es
+  peor que no tenerlo.
+- **Bloquear una no impide las demás**, y el orden se conserva: el modelo espera
+  una respuesta por cada llamada que hizo, en el orden en que las hizo.
+
+## Auditar
+
+```typescript
+registerHook("afterToolCall", (ctx) => {
+  auditoria.registrar({
+    tool: ctx.toolName, ok: ctx.ok, ms: ctx.durationMs,
+    agente: ctx.agentId, usuario: ctx.userId,
+  });
+});
+```
+
+`afterToolCall` **también ve las bloqueadas**: auditar incluye lo que no pasó.
+
+## Sesiones
+
+```typescript
+registerHook("sessionStart", async ({ threadId, userId, channel }) => {
+  await miPanel.registrarConversacion(userId, threadId, channel);
+});
+
+registerHook("sessionEnd", async ({ threadId, userId }) => {
+  await miPanel.cerrarConversacion(userId, threadId);
+});
+```
+
+Se disparan en las cuatro transiciones del ciclo de vida de un hilo, todas en
+`agent/thread-store.ts`:
+
+| Transición | Hook | API pública |
+|---|---|---|
+| Se crea el hilo | `sessionStart` | `createSession` · `createWebSession` |
+| Se reabre | `sessionStart` | `reopenSession` |
+| Se archiva | `sessionEnd` | `closeSession` |
+| Se borra | `sessionEnd` | `deleteSession` |
+
+Detalles que importan:
+
+- **`sessionStart` no se dispara en cada turno.** `createSession` es idempotente
+  y se llama con cada mensaje entrante; el enganche está en el `put` que crea la
+  fila, no en la función. Quien use el hook para inicializar estado o para
+  cobrar por conversación cuenta conversaciones, no mensajes.
+- **Dos turnos concurrentes lo disparan una sola vez.** El `put` con
+  `expectedVersion: 0` es el punto de serialización: el que pierde la carrera no
+  dispara nada.
+- **Archivar o reabrir dos veces seguidas dispara una sola vez**: el estado se
+  compara antes de escribir, y un no-op no anuncia nada.
+- **`sessionEnd` por borrado lleva `userId` y `channel`.** La fila se lee antes
+  de borrarla; si no, el hook recibiría un `threadId` y nada más, y quien lo use
+  para limpiar no sabría de quién era lo que se fue.
+- **Cubre a los canales que llaman `ensureThread` directo**, sin pasar por el
+  módulo `sessions`.
+
+## Scripts
+
+```jsonc
+// hive.config.json
+{ "hooks": { "scripts": { "before_tool_call": "./hooks/politica.ts" } } }
+```
+
+```typescript
+loadConfiguredHookScripts();   // opt-in: ejecutar procesos externos no debería
+                               // pasar por el solo hecho de importar el SDK
+```
+
+El contexto llega por stdin como JSON. Para `before_tool_call`, **salir con
+código distinto de 0 bloquea** y lo que el script escriba en stdout es el motivo
+— el equivalente en procesos a devolver `{ block }`.
+
+## Utilidades
+
+`hasHooks(nombre)` para saltarse trabajo cuando no hay ninguno registrado;
+`clearHooks(nombre?)` para tests. `registerHook` devuelve la función que lo quita.
+
+## Los disparadores
+
+`runBeforeToolCall` · `runAfterToolCall` · `runBeforeCompaction` ·
+`runSessionStart` · `runSessionEnd`
+
+Los llama el SDK en cada punto del ciclo; están exportados para quien integre los
+hooks en su propio flujo —un gateway con su propia noción de sesión, por ejemplo—
+pero **no hay que llamarlos** para que los hooks funcionen en un turno normal.
+
+`runBeforeToolCall` devuelve el motivo del bloqueo o `null`; los demás no
+devuelven nada, porque son observadores.
+
+*Documentación Hive SDK — ver `version` en package.json*

package/docs/API-RESILIENCE.md

@@ -0,0 +1,45 @@
+# API-RESILIENCE — reintentos y circuit breakers
+
+```typescript
+import { withRetry, isRetryableError, CircuitBreaker } from "@johpaz/hive-sdk/resilience";
+```
+
+## Reintentos
+
+```typescript
+const res = await withRetry(
+  () => llamarAlProveedor(),
+  { maxAttempts: 3, initialDelayMs: 1000, backoffMultiplier: 2, maxDelayMs: 30000 },
+  (err) => isRetryableError(err),
+);
+```
+
+`isRetryableError` distingue lo que mejora reintentando —429, 5xx, timeouts,
+cortes de red— de lo que no. **Un 400 no mejora reintentando**: el cuerpo está
+mal y volver a mandarlo igual sólo gasta una llamada. Lo mismo con 401 y 403.
+
+El backoff es exponencial con jitter, y respeta el `Retry-After` cuando el
+proveedor lo manda: si te dicen cuánto esperar, discutirlo es contraproducente.
+
+`computeRetryDelay(intento, policy)` calcula la espera si necesitas programarla
+por tu cuenta.
+
+## Circuit breakers
+
+```typescript
+const breaker = new CircuitBreaker("proveedor-x", { failureThreshold: 5, resetTimeoutMs: 30000 });
+const r = await breaker.execute(() => llamar());
+```
+
+Cuando un servicio ya viene fallando, seguir intentando le agrega carga y te
+gasta el presupuesto de reintentos. El breaker corta: tras N fallos se abre y
+rechaza sin llamar, hasta que pasa el tiempo de reposo y deja pasar una de
+prueba.
+
+`CircuitBreakerOpenError` lleva `retryAfterMs`, que es lo que necesita quien
+quiera decirle al usuario cuándo volver a intentar.
+
+`circuitBreakerRegistry` mantiene uno por nombre, para no crear un breaker nuevo
+en cada llamada y perder el estado que le da sentido.
+
+*Documentación Hive SDK — ver `version` en package.json*