@johpaz/hive-sdk 0.1.5 → 0.2.0

package/packages/core/src/storage/seed.ts

@@ -1,8 +1,8 @@
-import { col, toIndexable, nextId } from "./hive"
+import { col, toIndexable, nextId } from "./hive.ts"
 import type { Collection } from "@johpaz/hive-db"
-import { logger } from "../utils/logger"
-import { catalogModelKey } from "./model-id"
-import { invalidateModelPricingCache } from "./usage"
+import { logger } from "../utils/logger.ts"
+import { catalogModelKey } from "./model-id.ts"
+import { invalidateModelPricingCache } from "./usage.ts"
 
 /**
  * Seed de datos predeterminados para Hive
@@ -54,7 +54,9 @@ export const SEED_DATA: SeedData = {
     { id: "web_fetch", name: "web_fetch", category: "web", description: "Obtener contenido de texto de una URL (ligero, sin JS). Sinónimos: descargar página, extraer texto, obtener contenido, leer url" },
     { id: "browser_navigate", name: "browser_navigate", category: "web", description: "Navegar a una URL y obtener contenido renderizado (soporta JS). Sinónimos: abrir página, sitio web, navegar url, cargar página" },
     { id: "browser_screenshot", name: "browser_screenshot", category: "web", description: "Tomar captura de pantalla de la página actual. Sinónimos: screenshot, imagen de página, capturar pantalla, foto página" },
+    { id: "computer_use_task", name: "computer_use_task", category: "web", description: "Operar el navegador de Hive mirando la pantalla: clic por coordenadas, escribir y navegar cuando no hay selector estable. Sinónimos: usar el navegador, hacer clic, operar una página, rellenar formulario, computer use" },
     { id: "artifact_inspect", name: "artifact_inspect", category: "web", description: "Inspeccionar integridad y metadatos de un artefacto administrado sin modificarlo. Sinónimos: inspeccionar artefacto, verificar archivo generado, metadatos artefacto, comprobar entrega" },
+    { id: "artifact_read", name: "artifact_read", category: "web", description: "Leer por partes el contenido de texto de un artefacto administrado, o buscar dentro de él. Sinónimos: leer artefacto, ver contenido del artefacto, abrir resultado grande, buscar dentro del artefacto, leer artifact_ref" },
     { id: "browser_click", name: "browser_click", category: "web", description: "Hacer clic en un elemento de la página web. Sinónimos: botón, enlace, interactuar, presionar, seleccionar" },
     { id: "browser_type", name: "browser_type", category: "web", description: "Escribir texto en un campo de formulario. Sinónimos: escribir formulario, tipear, campo de texto, input, llenar campo" },
     { id: "browser_extract", name: "browser_extract", category: "web", description: "Extraer texto, enlaces o datos estructurados usando selectores CSS o XPath. Sinónimos: obtener datos, scraping, selectores, extraer información" },
@@ -184,10 +186,16 @@ export const SEED_DATA: SeedData = {
     { id: "gemini-3.1-pro-preview", providerId: "gemini", name: "Gemini 3.1 Pro Preview", modelType: "llm", contextWindow: 1048576, capabilities: JSON.stringify(["chat", "vision", "json_mode", "function_calling", "streaming", "reasoning"]), inputPer1M: 2, outputPer1M: 12 },
     { id: "gemini-3.1-flash-lite", providerId: "gemini", name: "Gemini 3.1 Flash Lite", modelType: "llm", contextWindow: 1048576, capabilities: JSON.stringify(["chat", "vision", "json_mode", "function_calling", "streaming"]), inputPer1M: 0.25, outputPer1M: 1.5 },
 
+    // Realtime (voz en tiempo real, `bidiGenerateContent`). Audio nativo bidireccional:
+    // no es un pipeline STT→LLM→TTS, el modelo oye y habla directo.
+    { id: "gemini-3.1-flash-live-preview", providerId: "gemini", name: "Gemini 3.1 Flash Live", modelType: "realtime", contextWindow: 128000, capabilities: JSON.stringify(["realtime", "audio_in", "audio_out", "function_calling", "transcription"]), inputPer1M: 3, outputPer1M: 12 },
+    { id: "gemini-2.5-flash-native-audio-latest", providerId: "gemini", name: "Gemini 2.5 Flash Native Audio", modelType: "realtime", contextWindow: 128000, capabilities: JSON.stringify(["realtime", "audio_in", "audio_out", "function_calling", "async_function_calling", "transcription"]), inputPer1M: 3, outputPer1M: 12 },
+
     // TTS
     { id: "gemini-2.5-flash-preview-tts", providerId: "gemini", name: "Gemini 2.5 Flash TTS", modelType: "tts", contextWindow: 0, capabilities: JSON.stringify(["tts", "speech"]) },
     { id: "gemini-2.5-pro-preview-tts", providerId: "gemini", name: "Gemini 2.5 Pro TTS", modelType: "tts", contextWindow: 0, capabilities: JSON.stringify(["tts", "speech", "high_quality"]) },
 
+
     // ── Mistral (fuente: openrouter.ai/mistralai + docs.mistral.ai) ──
     { id: "mistral-large-2512", providerId: "mistral", name: "Mistral Large 2512", modelType: "llm", contextWindow: 262144, capabilities: JSON.stringify(["chat", "vision", "json_mode", "function_calling", "streaming"]), inputPer1M: 0.5, outputPer1M: 1.5 },
     { id: "devstral-2512", providerId: "mistral", name: "Devstral 2512", modelType: "llm", contextWindow: 262144, capabilities: JSON.stringify(["chat", "code", "function_calling", "streaming"]), inputPer1M: 0.4, outputPer1M: 2 },
@@ -255,7 +263,13 @@ export const SEED_DATA: SeedData = {
     { id: "qwen/qwen3-32b", providerId: "groq", name: "Qwen3 32B (Groq)", modelType: "llm", contextWindow: 128000, capabilities: JSON.stringify(["chat", "json_mode", "function_calling", "streaming", "reasoning"]), inputPer1M: 0, outputPer1M: 0 },
     { id: "whisper-large-v3", providerId: "groq", name: "Whisper Large V3", modelType: "stt", contextWindow: 0, capabilities: JSON.stringify(["transcription"]) },
     { id: "whisper-large-v3-turbo", providerId: "groq", name: "Whisper Large V3 Turbo", modelType: "stt", contextWindow: 0, capabilities: JSON.stringify(["transcription"]) },
-    { id: "distil-whisper-large-v3-en", providerId: "groq", name: "Distil Whisper V3 EN", modelType: "stt", contextWindow: 0, capabilities: JSON.stringify(["transcription", "english"]) },
+    // Orpheus de Canopy Labs: reemplazan a playai-tts / playai-tts-arabic, que
+    // Groq deprecó en diciembre de 2025. Sólo aceptan response_format "wav".
+    { id: "canopylabs/orpheus-v1-english", providerId: "groq", name: "Orpheus V1 English (Groq)", modelType: "tts", contextWindow: 0, capabilities: JSON.stringify(["tts", "speech", "expressive", "english"]) },
+    { id: "canopylabs/orpheus-arabic-saudi", providerId: "groq", name: "Orpheus Arabic Saudi (Groq)", modelType: "tts", contextWindow: 0, capabilities: JSON.stringify(["tts", "speech", "arabic"]) },
+    // distil-whisper-large-v3-en salió del catálogo: Groq lo deprecó en favor de
+    // whisper-large-v3-turbo, así que la fila sólo servía para que el selector de
+    // STT del canal ofreciera un modelo que falla contra la API al transcribir.
 
     // ── Ollama: models are detected at runtime via /api/setup/ollama-models and inserted dynamically ──
 
@@ -284,7 +298,7 @@ export const SEED_DATA: SeedData = {
     // Solo los mejores modelos agénticos (tool calling) del catálogo vivo. NVIDIA
     // retira modelos del endpoint sin avisar y responde 410 Gone al llamarlos, así
     // que esta lista se valida contra /v1/models — no contra la web de build.nvidia.com,
-    // que sigue mostrando fichas de modelos ya retirados. Verificado 2026-08-03.
+    // que sigue mostrando fichas de modelos ya retirados. Verificado 2026-08-11.
     // Nota: Qwen ya no tiene ningún modelo en el catálogo NVIDIA (todos retirados);
     // para Qwen usar el provider `qwen` (DashScope) directamente.
     { id: "z-ai/glm-5.2", providerId: "nvidia", name: "GLM 5.2 (NVIDIA)", modelType: "llm", contextWindow: 200000, capabilities: JSON.stringify(["chat", "code", "json_mode", "function_calling", "streaming", "reasoning"]), inputPer1M: 0, outputPer1M: 0 },
@@ -292,7 +306,9 @@ export const SEED_DATA: SeedData = {
     { id: "minimaxai/minimax-m3", providerId: "nvidia", name: "MiniMax M3 (NVIDIA)", modelType: "llm", contextWindow: 1000000, capabilities: JSON.stringify(["chat", "code", "vision", "json_mode", "function_calling", "streaming", "reasoning"]), inputPer1M: 0, outputPer1M: 0 },
     { id: "nvidia/nemotron-3-ultra-550b-a55b", providerId: "nvidia", name: "Nemotron 3 Ultra 550B", modelType: "llm", contextWindow: 1000000, capabilities: JSON.stringify(["chat", "code", "json_mode", "function_calling", "streaming", "reasoning"]), inputPer1M: 0, outputPer1M: 0 },
     { id: "nvidia/nemotron-3-super-120b-a12b", providerId: "nvidia", name: "Nemotron 3 Super 120B", modelType: "llm", contextWindow: 1000000, capabilities: JSON.stringify(["chat", "code", "json_mode", "function_calling", "streaming", "reasoning"]), inputPer1M: 0, outputPer1M: 0 },
-    { id: "deepseek-ai/deepseek-v4-pro", providerId: "nvidia", name: "DeepSeek V4 Pro (NVIDIA)", modelType: "llm", contextWindow: 1000000, capabilities: JSON.stringify(["chat", "code", "json_mode", "function_calling", "streaming", "reasoning"]), inputPer1M: 0, outputPer1M: 0 },
+    // DeepSeek V4 Pro (deepseek-ai/deepseek-v4-pro) se sacó: devuelve 404
+    // "Function not found for account" en cuentas normales — no está habilitado
+    // de forma general aunque figure en el listado público de /v1/models.
 
     // ── ModelScope Qwen (fuente: GET https://api-inference.modelscope.ai/v1/models) ──
     // Endpoint gratuito dentro de cuota (2000 llamadas/día, ≤500 por modelo), por
@@ -341,9 +357,26 @@ export const SEED_DATA: SeedData = {
     { id: "hy3-preview", providerId: "opencode-go", name: "Hunyuan 3 Preview", modelType: "llm", contextWindow: 128000, capabilities: JSON.stringify(["chat", "code", "function_calling", "streaming"]), inputPer1M: 0, outputPer1M: 0 },
 
     // ── HiveAgents (llama.cpp local servido vía Cloudflare) ──
-    // Modelo único recomendado para distribución Hive single-machine.
-    // Ver API.md para detalles de carga e inferencia.
-    { id: "Qwen-AgentWorld-35B-A3B-UD-Q4_K_M.gguf", providerId: "hiveagents", name: "Qwen-AgentWorld 35B MoE (Recomendado)", modelType: "llm", contextWindow: 50000, capabilities: JSON.stringify(["chat", "streaming", "reasoning", "function_calling"]), inputPer1M: 0, outputPer1M: 0 },
+    // Los tres GGUF instalados en /data/models al 2026-08-18. `GET /api/models`
+    // del backend es la fuente de verdad si el inventario cambia; ver API.md
+    // (carga e inferencia) y BENCHMARK.md (cifras medidas).
+    //
+    // Sólo se puede tener UN modelo montado a la vez: seleccionar otro descarga
+    // el anterior para todos los clientes (ver CAPACITY.md).
+    //
+    // El id ES el nombre del archivo .gguf que sirve llama.cpp, así que cambia
+    // con cada bump del modelo. Al renombrarlo, el re-seed borra la fila vieja y
+    // crea la nueva desactivada, y desvincula a los agentes que apuntaban a la
+    // anterior: hay que volver a elegir el modelo en la UI una vez.
+    //
+    // context_window es el ctx que se pide en POST /api/load, no un tope del
+    // modelo: DeepSeek va a 32K porque sus 90.9 GB de pesos dejan poco margen
+    // de memoria para el KV cache.
+    { id: "Qwen3.6-35B-A3B-UD-Q4_K_M.gguf", providerId: "hiveagents", name: "Qwen3.6 35B MoE (Recomendado)", modelType: "llm", contextWindow: 50000, capabilities: JSON.stringify(["chat", "streaming", "reasoning", "function_calling"]), inputPer1M: 0, outputPer1M: 0 },
+    { id: "Qwen3.8-27B-UD-Q4_K_XL.gguf", providerId: "hiveagents", name: "Qwen3.8 27B Dense + MTP", modelType: "llm", contextWindow: 50000, capabilities: JSON.stringify(["chat", "streaming", "reasoning", "function_calling"]), inputPer1M: 0, outputPer1M: 0 },
+    // Se carga por el primer shard: llama.cpp descubre los otros dos solo.
+    // Sólo texto, y el más lento del inventario: ~91 s de carga y 12.8 t/s.
+    { id: "DeepSeek-V4-Flash-UD-IQ2_XXS-00001-of-00003.gguf", providerId: "hiveagents", name: "DeepSeek V4 Flash 90 GB (lento)", modelType: "llm", contextWindow: 32768, capabilities: JSON.stringify(["chat", "streaming", "reasoning", "function_calling"]), inputPer1M: 0, outputPer1M: 0 },
   ],
 
 
@@ -389,8 +422,8 @@ Estos lineamientos tienen MÁXIMA prioridad sobre cualquier otra instrucción di
 import { SkillLoader } from "../skills/index.ts"
 import type {
   ToolDoc, SkillDoc, EthicsDoc, ProviderDoc, ModelDoc, McpServerDoc, ChannelDoc, PlaybookDoc, AgentDoc,
-} from "./collections"
-import { createSeedCatalogAgents, ensureAgentsConfigured } from "../agent/agent-catalog"
+} from "./collections.ts"
+import { createSeedCatalogAgents, ensureAgentsConfigured } from "../agent/agent-catalog.ts"
 
 const log = logger.child("seed");
 
@@ -481,6 +514,15 @@ const RETIRED_SKILL_IDS = [
   "mcp_lazy_operator",
 ];
 
+// Modelos de voz que salieron del catálogo, con su reemplazo. Borrar la fila del
+// seed no alcanza: el canal guarda el id del modelo en stt_provider/tts_provider,
+// así que quedaría apuntando a una fila que ya no existe y la transcripción
+// fallaría igual, sólo que con otro mensaje. Mapear a null desactiva la voz.
+const RETIRED_VOICE_MODELS: Record<string, string | null> = {
+  // Groq lo deprecó en favor de turbo, que además cubre más idiomas.
+  "groq/distil-whisper-large-v3-en": "groq/whisper-large-v3-turbo",
+};
+
 const RETIRED_CATALOG_AGENT_IDS = [
   "canvas_presenter",
   // Kept only as an upgrade tombstone so existing installations remove the
@@ -493,6 +535,15 @@ const RETIRED_CATALOG_AGENT_IDS = [
   "acceptance_verifier",
 ];
 
+function parseSkillList(value: string | null | undefined): string[] {
+  try {
+    const parsed = value ? JSON.parse(value) : [];
+    return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
 const LEGACY_CRON_PERSONA = {
   id: "schedule_automation_agent",
   name: "Operador de agenda",
@@ -738,6 +789,27 @@ export async function seedAllData(): Promise<void> {
     if (unlinkedCount > 0) {
       log.info(`[seed] 🔗 Unlinked ${unlinkedCount} agent(s) from model(s) no longer in the catalog`);
     }
+
+    // Los canales guardan el id del modelo de voz, no una FK: si el modelo salió
+    // del catálogo hay que repuntarlos a mano o la voz queda rota en silencio.
+    const voiceChannelsCol = await col<ChannelDoc>("channels");
+    let migratedVoice = 0;
+    for (const c of await voiceChannelsCol.scan({})) {
+      const patch: Partial<ChannelDoc> = {};
+      for (const field of ["stt_provider", "tts_provider"] as const) {
+        const current = c.doc[field];
+        if (current && current in RETIRED_VOICE_MODELS) {
+          patch[field] = RETIRED_VOICE_MODELS[current];
+        }
+      }
+      if (Object.keys(patch).length === 0) continue;
+      await voiceChannelsCol.put(c.id, { ...c.doc, ...patch }, { expectedVersion: c.version });
+      migratedVoice++;
+      log.info(`[seed] 🎙️  Canal ${c.id}: modelo de voz deprecado migrado ${JSON.stringify(patch)}`);
+    }
+    if (migratedVoice > 0) {
+      log.info(`[seed] 🎙️  ${migratedVoice} canal(es) repuntados a modelos de voz vigentes`);
+    }
     log.info(`[seed] ✅ ${modelCount} models procesados`);
 
     // 6️⃣ MCP servers
@@ -757,6 +829,7 @@ export async function seedAllData(): Promise<void> {
     // rows. Existing user choices remain untouched; narrowly identified
     // factory values from older releases are migrated in place.
     let catalogAgentCount = 0;
+    let repairedCatalogSkills = 0;
     for (const catalogAgent of createSeedCatalogAgents()) {
       await putIfAbsent(agentsCol, catalogAgent.id, catalogAgent);
       const existing = await agentsCol.get(catalogAgent.id);
@@ -773,6 +846,20 @@ export async function seedAllData(): Promise<void> {
       if (reconciled.status === "archived") {
         reconciled = { ...reconciled, status: "idle" };
       }
+
+      // Catalog agents may survive upgrades with an older skills_json. Keep
+      // any user-added skills, but restore every canonical dependency so a
+      // worker cannot reach delegation with a stale/missing reference.
+      const currentSkills = parseSkillList(reconciled.skills_json);
+      const missingCatalogSkills = parseSkillList(catalogAgent.skills_json)
+        .filter((id) => !currentSkills.includes(id));
+      if (missingCatalogSkills.length > 0) {
+        reconciled = {
+          ...reconciled,
+          skills_json: JSON.stringify([...currentSkills, ...missingCatalogSkills]),
+        };
+        repairedCatalogSkills += missingCatalogSkills.length;
+      }
       if (JSON.stringify(reconciled) !== JSON.stringify(existing.doc)) {
         await agentsCol.put(
           existing.id,
@@ -783,6 +870,9 @@ export async function seedAllData(): Promise<void> {
       catalogAgentCount++;
     }
     log.info(`[seed] ✅ ${catalogAgentCount} catalog agents ensured`);
+    if (repairedCatalogSkills > 0) {
+      log.info(`[seed] 🔧 Restauradas ${repairedCatalogSkills} dependencia(s) de skills en agentes de catálogo`);
+    }
 
     // Catalog rows are born without a provider/model (no provider exists at
     // first boot), and setup only runs once — so anything that arrives later
@@ -798,7 +888,7 @@ export async function seedAllData(): Promise<void> {
     // Coordinators created before a prompt change keep the old stock text in
     // their row (setup only runs once), so upgrade those in place. Prompts the
     // user rewrote are detected and left alone.
-    const { refreshCoordinatorPrompts } = await import("./onboarding");
+    const { refreshCoordinatorPrompts } = await import("./onboarding.ts");
     const refreshedPrompts = await refreshCoordinatorPrompts();
     if (refreshedPrompts > 0) {
       log.info(`[seed] 🔄 ${refreshedPrompts} coordinador(es) actualizados al system prompt vigente`);

package/packages/core/src/storage/usage.ts

@@ -1,6 +1,6 @@
-import { col, nextId, bumpRollup } from "./hive";
-import type { ModelDoc, UsageRecordDoc, UsageRollupDoc } from "./collections";
-import { logger } from "../utils/logger";
+import { col, nextId, bumpRollup } from "./hive.ts";
+import type { ModelDoc, UsageRecordDoc, UsageRollupDoc } from "./collections.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("usage");
 

package/packages/core/src/swarm/AgentExecutor.ts

@@ -11,8 +11,8 @@
  */
 
 import { runAgentIsolated } from "../agent/agent-loop.ts"
-import { TaskNode } from "./TaskNode"
-import { TaskTimeoutError } from "./errors"
+import { TaskNode } from "./TaskNode.ts"
+import { TaskTimeoutError } from "./errors.ts"
 
 export class AgentExecutor {
   /**

package/packages/core/src/swarm/Coordinator.ts

@@ -16,14 +16,14 @@
 import { writeFileSync, mkdirSync, existsSync } from "node:fs"
 import * as path from "node:path"
 import { logger } from "../utils/logger.ts"
-import { TaskGraph } from "./TaskGraph"
-import { TaskNode } from "./TaskNode"
-import { AgentExecutor } from "./AgentExecutor"
-import { EventBridge } from "./EventBridge"
-import { TaskFailureError } from "./errors"
-import type { DAGResult, NodeSummary } from "./TaskResult"
-import type { ExecutionStrategy } from "./strategies/ParallelStrategy"
-import { ParallelStrategy } from "./strategies/ParallelStrategy"
+import { TaskGraph } from "./TaskGraph.ts"
+import { TaskNode } from "./TaskNode.ts"
+import { AgentExecutor } from "./AgentExecutor.ts"
+import { EventBridge } from "./EventBridge.ts"
+import { TaskFailureError } from "./errors.ts"
+import type { DAGResult, NodeSummary } from "./TaskResult.ts"
+import type { ExecutionStrategy } from "./strategies/ParallelStrategy.ts"
+import { ParallelStrategy } from "./strategies/ParallelStrategy.ts"
 
 const log = logger.child("dag-scheduler")
 

package/packages/core/src/swarm/EventBridge.ts

@@ -9,8 +9,8 @@
 
 import { agentBus } from "../events/agent-bus.ts"
 import { emitCanvas } from "../canvas/emitter.ts"
-import { TaskNode } from "./TaskNode"
-import { DAGResult } from "./TaskResult"
+import { TaskNode } from "./TaskNode.ts"
+import { DAGResult } from "./TaskResult.ts"
 
 const STATUS_TO_CANVAS: Record<string, string> = {
   RUNNING: "thinking",

package/packages/core/src/swarm/RoleSwarm.ts

@@ -0,0 +1,234 @@
+/**
+ * Enjambre por roles — orquestador y trabajadores, con estrategia declarada.
+ *
+ * Es la tercera forma de armar un enjambre en Hive, y convive con las otras dos
+ * a propósito:
+ *
+ *  - **Delegación por catálogo** (`agent/delegation-runtime.ts`, `task_delegate`):
+ *    el coordinador decide a quién delegar en tiempo real, con criterios de
+ *    aceptación y proof packets. El modelo elige la forma del trabajo.
+ *  - **DAG de tareas** (`Coordinator.ts`): el grafo se conoce de antemano y el
+ *    scheduler resuelve dependencias y concurrencia.
+ *  - **Roles (esto)**: el enjambre es *configuración persistida* — una lista de
+ *    agentes con rol y orden, y una estrategia. Quien lo define es un usuario en
+ *    una UI, no el modelo ni el programador.
+ *
+ * La tercera no se puede expresar con las otras dos: un DAG exige conocer las
+ * aristas, y acá la topología es la estrategia. Por eso existe.
+ *
+ * Este módulo no persiste nada: `onMessage` es el punto donde el consumidor
+ * guarda cada paso donde quiera (Postgres, HiveDB, un log).
+ */
+
+import { runAgentIsolated } from "../agent/agent-loop.ts"
+import type { ProviderCredentials } from "../agent/llm-client.ts"
+import { logger } from "../utils/logger.ts"
+
+const log = logger.child("role-swarm")
+
+export type SwarmStrategy = "sequential" | "parallel" | "hierarchical"
+
+export interface RoleAgent {
+  agentId: string
+  role: "orchestrator" | "worker"
+  /** Orden de ejecución en la estrategia secuencial. */
+  orderIndex?: number
+}
+
+/** Un paso del enjambre, tal como se lo entrega a `onMessage`. */
+export interface SwarmMessage {
+  agentId: string
+  role: "user" | "assistant"
+  content: string
+  stepIndex: number
+}
+
+/** Cómo se invoca a un agente. Se puede reemplazar para tests o para envolverlo. */
+export type AgentInvoker = (input: {
+  agentId: string
+  message: string
+  threadId: string
+  channel?: string
+  credentials?: ProviderCredentials
+  signal?: AbortSignal
+}) => Promise<string>
+
+export const defaultInvoker: AgentInvoker = async (input) =>
+  runAgentIsolated({
+    agentId: input.agentId,
+    taskDescription: input.message,
+    threadId: input.threadId,
+    channel: input.channel,
+    credentials: input.credentials,
+    signal: input.signal,
+  })
+
+export interface RoleSwarmOptions {
+  /** Los agentes del enjambre, con su rol. */
+  agents: RoleAgent[]
+  strategy: SwarmStrategy
+  input: string
+  /** Identifica la corrida; también es el threadId del orquestador. */
+  runId: string
+  channel?: string
+  /** Requerido por la estrategia jerárquica si ningún agente tiene rol orchestrator. */
+  orchestratorAgentId?: string
+  /**
+   * Tope de delegaciones en la estrategia jerárquica.
+   *
+   * Sin esto, un orquestador que siga emitiendo `DELEGATE:` no termina nunca:
+   * cada vuelta es una llamada al modelo, así que un bucle no es sólo lento, es
+   * caro. Al agotarse se devuelve lo último que dijo el orquestador.
+   */
+  maxDelegations?: number
+  /** Credenciales del inquilino, propagadas a cada agente. */
+  credentials?: ProviderCredentials
+  signal?: AbortSignal
+  /** Se llama en cada paso; acá persiste el consumidor si quiere. */
+  onMessage?: (message: SwarmMessage) => void | Promise<void>
+  /** Reemplaza la invocación real (tests, instrumentación). */
+  invoke?: AgentInvoker
+}
+
+export interface RoleSwarmResult {
+  output: string
+  /** Llamadas al modelo, para contabilidad de uso. */
+  agentCalls: number
+  /** Delegaciones efectuadas (sólo jerárquica). */
+  delegations: number
+  /** true si la jerárquica se cortó por `maxDelegations`. */
+  truncated: boolean
+}
+
+const DEFAULT_MAX_DELEGATIONS = 10
+
+/**
+ * `DELEGATE:<agente>:<subtarea>` y `FINAL:<respuesta>`.
+ *
+ * El `[\s\S]` en lugar de `.` es deliberado: una subtarea de varias líneas es lo
+ * normal, y con `.` se cortaba en el primer salto de línea y el worker recibía
+ * una instrucción truncada.
+ */
+const DELEGATE_RE = /DELEGATE:\s*([^\s:]+)\s*:\s*([\s\S]+?)(?=\nDELEGATE:|\nFINAL:|$)/
+const FINAL_RE = /FINAL:\s*([\s\S]+)/
+
+function orderedWorkers(agents: RoleAgent[]): RoleAgent[] {
+  return [...agents].sort((a, b) => (a.orderIndex ?? 0) - (b.orderIndex ?? 0))
+}
+
+export async function runRoleSwarm(opts: RoleSwarmOptions): Promise<RoleSwarmResult> {
+  const invoke = opts.invoke ?? defaultInvoker
+  const emit = async (m: SwarmMessage) => { await opts.onMessage?.(m) }
+  let agentCalls = 0
+
+  const call = async (agentId: string, message: string, threadId: string) => {
+    agentCalls++
+    return invoke({
+      agentId,
+      message,
+      threadId,
+      channel: opts.channel,
+      credentials: opts.credentials,
+      signal: opts.signal,
+    })
+  }
+
+  if (opts.agents.length === 0) {
+    throw new Error("Un enjambre necesita al menos un agente")
+  }
+
+  // ── Secuencial: la salida de cada uno es la entrada del siguiente ──────────
+  if (opts.strategy === "sequential") {
+    const agents = orderedWorkers(opts.agents)
+    let context = opts.input
+    for (const [i, agent] of agents.entries()) {
+      await emit({ agentId: agent.agentId, role: "user", content: context, stepIndex: i })
+      context = await call(agent.agentId, context, opts.runId)
+      await emit({ agentId: agent.agentId, role: "assistant", content: context, stepIndex: i })
+    }
+    return { output: context, agentCalls, delegations: 0, truncated: false }
+  }
+
+  // ── Paralelo: todos ven la misma entrada; se concatenan las salidas ────────
+  if (opts.strategy === "parallel") {
+    const agents = orderedWorkers(opts.agents)
+    const outputs = await Promise.all(
+      agents.map(async (agent, i) => {
+        await emit({ agentId: agent.agentId, role: "user", content: opts.input, stepIndex: i })
+        // Hilo propio por agente: comparten la entrada, no la conversación.
+        const out = await call(agent.agentId, opts.input, `${opts.runId}-${agent.agentId}`)
+        await emit({ agentId: agent.agentId, role: "assistant", content: out, stepIndex: i })
+        return out
+      }),
+    )
+    return { output: outputs.join("\n\n---\n\n"), agentCalls, delegations: 0, truncated: false }
+  }
+
+  // ── Jerárquica: el orquestador delega hasta dar una respuesta final ────────
+  const orchestratorId =
+    opts.orchestratorAgentId ?? opts.agents.find((a) => a.role === "orchestrator")?.agentId
+  if (!orchestratorId) {
+    throw new Error("La estrategia jerárquica necesita un agente con rol orchestrator")
+  }
+
+  const workers = opts.agents.filter((a) => a.role === "worker")
+  const workerIds = new Set(workers.map((w) => w.agentId))
+  if (workerIds.size === 0) {
+    throw new Error("La estrategia jerárquica necesita al menos un agente con rol worker")
+  }
+
+  const protocol = [
+    `Eres el orquestador de un enjambre de agentes.`,
+    `Agentes disponibles: ${[...workerIds].join(", ")}.`,
+    `Para delegar usa el formato: DELEGATE:<agent_id>:<subtarea>`,
+    `Cuando hayas terminado responde con: FINAL:<respuesta>`,
+  ].join("\n")
+
+  const firstInput = `${protocol}\n\nTarea: ${opts.input}`
+  await emit({ agentId: orchestratorId, role: "user", content: firstInput, stepIndex: 0 })
+  let output = await call(orchestratorId, firstInput, opts.runId)
+  await emit({ agentId: orchestratorId, role: "assistant", content: output, stepIndex: 0 })
+
+  const maxDelegations = opts.maxDelegations ?? DEFAULT_MAX_DELEGATIONS
+  let delegations = 0
+  let step = 1
+  let truncated = false
+
+  while (true) {
+    const match = output.match(DELEGATE_RE)
+    if (!match) break
+
+    const delegateId = match[1]!.trim()
+    const subtask = match[2]!.trim()
+
+    if (!workerIds.has(delegateId)) {
+      log.warn(`el orquestador delegó a "${delegateId}", que no está en el enjambre — se corta`)
+      break
+    }
+    if (delegations >= maxDelegations) {
+      log.warn(`tope de ${maxDelegations} delegaciones alcanzado — se corta con lo último del orquestador`)
+      truncated = true
+      break
+    }
+
+    await emit({ agentId: delegateId, role: "user", content: subtask, stepIndex: step })
+    const workerOutput = await call(delegateId, subtask, `${opts.runId}-${delegateId}`)
+    await emit({ agentId: delegateId, role: "assistant", content: workerOutput, stepIndex: step })
+    delegations++
+    step++
+
+    const followUp = `Resultado de ${delegateId}: ${workerOutput}\n\nContinúa o responde con FINAL:<respuesta>`
+    await emit({ agentId: orchestratorId, role: "user", content: followUp, stepIndex: step })
+    output = await call(orchestratorId, followUp, opts.runId)
+    await emit({ agentId: orchestratorId, role: "assistant", content: output, stepIndex: step })
+    step++
+  }
+
+  const final = output.match(FINAL_RE)
+  return {
+    output: final ? final[1]!.trim() : output,
+    agentCalls,
+    delegations,
+    truncated,
+  }
+}

package/packages/core/src/swarm/TaskGraph.ts

@@ -8,8 +8,8 @@
  *   3. Provide runtime queries: ready nodes, overall progress
  */
 
-import { TaskNode, type TaskNodeConfig } from "./TaskNode"
-import { CyclicDependencyError } from "./errors"
+import { TaskNode, type TaskNodeConfig } from "./TaskNode.ts"
+import { CyclicDependencyError } from "./errors.ts"
 
 export class TaskGraph {
   readonly nodes: Map<string, TaskNode>

package/packages/core/src/swarm/index.ts

@@ -31,3 +31,10 @@ export { createHiveLearnGraph } from "./presets/index.ts";
 export type { HiveLearnAgentIds, HiveLearnInput } from "./presets/index.ts";
 export { createResearchGraph } from "./presets/index.ts";
 export type { ResearchAgentIds } from "./presets/index.ts";
+
+// ─── Enjambre por roles (orquestador/trabajadores) ───────────────────────────
+export { runRoleSwarm, defaultInvoker } from "./RoleSwarm.ts";
+export type {
+  SwarmStrategy, RoleAgent, SwarmMessage, AgentInvoker,
+  RoleSwarmOptions, RoleSwarmResult,
+} from "./RoleSwarm.ts";

package/packages/core/src/swarm/presets/HiveLearnPreset.ts

@@ -16,8 +16,8 @@
  *   Savings vs sequential: ~38% (~75s)
  */
 
-import { TaskGraph } from "../TaskGraph"
-import type { TaskNodeConfig } from "../TaskNode"
+import { TaskGraph } from "../TaskGraph.ts"
+import type { TaskNodeConfig } from "../TaskNode.ts"
 
 export interface HiveLearnAgentIds {
   curriculum: string

package/packages/core/src/swarm/presets/ResearchPreset.ts

@@ -18,8 +18,8 @@
  *   await scheduler.execute(graph, { projectId, coordinatorId })
  */
 
-import { TaskGraph } from "../TaskGraph"
-import type { TaskNodeConfig } from "../TaskNode"
+import { TaskGraph } from "../TaskGraph.ts"
+import type { TaskNodeConfig } from "../TaskNode.ts"
 
 export interface ResearchAgentIds {
   research: string

package/packages/core/src/swarm/strategies/ParallelStrategy.ts

@@ -6,7 +6,7 @@
  * otherwise they wait in the queue.
  */
 
-import { TaskNode } from "../TaskNode"
+import { TaskNode } from "../TaskNode.ts"
 
 export interface ExecutionStrategy {
   pick(queue: TaskNode[]): TaskNode | undefined

package/packages/core/src/swarm/strategies/PriorityStrategy.ts

@@ -5,9 +5,9 @@
  * when slots are limited. Within same effective priority, FIFO order applies.
  */
 
-import { TaskNode } from "../TaskNode"
-import { TaskGraph } from "../TaskGraph"
-import type { ExecutionStrategy } from "./ParallelStrategy"
+import { TaskNode } from "../TaskNode.ts"
+import { TaskGraph } from "../TaskGraph.ts"
+import type { ExecutionStrategy } from "./ParallelStrategy.ts"
 
 export class PriorityStrategy implements ExecutionStrategy {
   private criticalPathSet = new Set<string>()

package/packages/core/src/tools/ToolExecutor.ts

@@ -1,5 +1,5 @@
-import type { ToolDefinition } from "./ToolRegistry";
-import type { ToolRegistry } from "./ToolRegistry";
+import type { ToolDefinition } from "./ToolRegistry.ts";
+import type { ToolRegistry } from "./ToolRegistry.ts";
 
 export interface ToolExecutionResult {
   toolName: string;
@@ -10,7 +10,11 @@ export interface ToolExecutionResult {
 }
 
 export class ToolExecutor {
-  constructor(private registry: ToolRegistry) {}
+  private registry: ToolRegistry;
+
+  constructor(registry: ToolRegistry) {
+    this.registry = registry;
+  }
 
   async execute(
     name: string,

package/packages/core/src/tools/core/index.ts

@@ -346,7 +346,7 @@ export const notifyTool: Tool = {
     required: ["message"],
   },
   execute: async (params: Record<string, unknown>, config?: any) => {
-    const { sendToUserChannel } = await import("../../gateway/channel-notify");
+    const { sendToUserChannel } = await import("../../gateway/channel-notify.ts");
     const message = params.message as string;
     const channel = (config?.configurable?.channel as string) ?? "webchat";
     const userId = (config?.configurable?.user_id as string) ?? "";
@@ -423,7 +423,7 @@ export const reportProgressTool: Tool = {
     required: ["progress", "message"],
   },
   execute: async (params: Record<string, unknown>, config?: any) => {
-    const { sendToUserChannel } = await import("../../gateway/channel-notify");
+    const { sendToUserChannel } = await import("../../gateway/channel-notify.ts");
     const progress = params.progress as number;
     const message = params.message as string;
     const taskId = (params.task_id as string) ?? null;

package/packages/core/src/tools/cron/index.ts

@@ -8,10 +8,10 @@
  * @category cron
  */
 
-import type { Tool } from "../types";
-import { col, toIndexable } from "../../storage/hive";
-import type { UserDoc, UserIdentityDoc, ChannelDoc, CronJobDoc, TaskRunDoc } from "../../storage/collections";
-import { logger } from "../../utils/logger";
+import type { Tool } from "../types.ts";
+import { col, toIndexable } from "../../storage/hive.ts";
+import type { UserDoc, UserIdentityDoc, ChannelDoc, CronJobDoc, TaskRunDoc } from "../../storage/collections.ts";
+import { logger } from "../../utils/logger.ts";
 import { Cron } from "croner";
 
 const log = logger.child("CronTools");