@johpaz/hive-sdk 0.2.0 → 0.3.1

package/packages/core/src/agent/thread-store.ts

@@ -14,6 +14,7 @@ import { col, updateDoc } from "../storage/hive.ts"
 import { logger } from "../utils/logger.ts"
 import type { ConversationThreadDoc, ConversationDoc, SummaryDoc } from "../storage/collections.ts"
 import { makeThreadId, parseThreadId, newWebConversationId } from "./thread-id.ts"
+import { runSessionStart, runSessionEnd } from "../hooks/index.ts"
 
 const log = logger.child("thread-store")
 
@@ -65,7 +66,17 @@ export async function ensureThread(input: EnsureThreadInput): Promise<string> {
     }, { expectedVersion: 0 })
   } catch {
     // Otro turno del mismo canal la creó primero — ambos quieren lo mismo.
+    return threadId
   }
+
+  // `sessionStart` se dispara acá y no en `createSession` porque esa función es
+  // idempotente y se llama en cada turno: engancharla ahí haría que el hook
+  // corriera con cada mensaje. El `put` con `expectedVersion: 0` es el punto de
+  // serialización, así que dispararlo justo después de que ese put haya salido
+  // bien evita el doble disparo cuando dos turnos del mismo canal llegan juntos
+  // — el perdedor se fue por el catch de arriba. Cubre además a quien llame
+  // `ensureThread` directamente desde un canal, sin pasar por `sessions`.
+  await runSessionStart({ threadId, userId: input.userId, channel: input.channel })
   return threadId
 }
 
@@ -176,6 +187,29 @@ export async function renameThread(threadId: string, title: string): Promise<voi
   await updateDoc<ConversationThreadDoc>("conversationThreads", threadId, { title: clean || null })
 }
 
+/**
+ * Archiva el hilo: sale de la lista pero no se pierde nada.
+ *
+ * Vive acá y no en `sessions/index.ts` para que las cuatro transiciones del
+ * ciclo de vida —crear, archivar, reabrir, borrar— disparen sus hooks desde un
+ * solo archivo. Repartidas, la próxima que se agregue se olvida de disparar.
+ */
+export async function archiveThread(threadId: string): Promise<void> {
+  const anterior = await getThread(threadId)
+  await updateDoc<ConversationThreadDoc>("conversationThreads", threadId, { archived: true })
+  // Archivar dos veces es un no-op, y el hook no debería enterarse dos veces.
+  if (anterior?.archived) return
+  await runSessionEnd({ threadId, userId: anterior?.user_id, channel: anterior?.channel })
+}
+
+/** Reabre un hilo archivado: vuelve a estar activo, y eso es un `sessionStart`. */
+export async function unarchiveThread(threadId: string): Promise<void> {
+  const anterior = await getThread(threadId)
+  await updateDoc<ConversationThreadDoc>("conversationThreads", threadId, { archived: false })
+  if (anterior && !anterior.archived) return
+  await runSessionStart({ threadId, userId: anterior?.user_id, channel: anterior?.channel })
+}
+
 /**
  * Borra la conversación entera: mensajes, resumen, notas y la fila del registro.
  * Los mensajes se localizan por prefijo, igual que los lee conversation-store.
@@ -193,9 +227,18 @@ export async function deleteThread(threadId: string): Promise<void> {
   for (const n of notes) await scratchpad.delete(n.id)
 
   const c = await threadsCol()
+  // La fila se lee antes de borrarla: después no hay de dónde sacar el usuario
+  // ni el canal para el contexto del hook. El threadId los lleva codificados,
+  // pero el hilo legacy es id = userId pelado y no parsea.
+  const fila = (await c.get(threadId))?.doc
   await c.delete(threadId).catch(() => {})
 
   log.info(`conversación ${threadId} borrada (${messages.length} mensajes)`)
+  await runSessionEnd({
+    threadId,
+    userId: fila?.user_id ?? parseThreadId(threadId)?.userId,
+    channel: fila?.channel ?? parseThreadId(threadId)?.channel,
+  })
 }
 
 /**

package/packages/core/src/agent/tool-selector.ts

@@ -203,6 +203,8 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     { name: "computer_use_task", description: "Operate the browser by looking at the screen: click by coordinates, type and navigate when no stable CSS selector exists (canvas, generated UIs, embedded viewers). Acts on Hive's own browser, never on the user screen. Spanish keywords: usar el navegador, hacer clic donde veas, operar una página, rellenar formulario, computer use, mirar la pantalla", category: "browser", abstractionLevel: "orchestration" },
     { name: "artifact_inspect", description: "Inspect a managed artifact's integrity and metadata without modifying it. Spanish keywords: inspeccionar artefacto, verificar archivo generado, metadatos artefacto, comprobar entrega", category: "web", abstractionLevel: "atomic" },
     { name: "artifact_read", description: "Read a managed artifact's text content in slices, or search inside it — the way to open any artifact_ref a tool returned. Spanish keywords: leer artefacto, ver contenido del artefacto, abrir resultado grande, buscar dentro del artefacto", category: "web", abstractionLevel: "atomic" },
+    { name: "image_metadata", description: "Read a stored image's dimensions and format without loading it into context. Spanish keywords: medir imagen, dimensiones de la imagen, tamaño de la foto, formato de imagen", category: "images", abstractionLevel: "atomic" },
+    { name: "image_transform", description: "Resize, rotate or convert a stored image, returning a new artifact — the original is untouched. Spanish keywords: redimensionar imagen, cambiar tamaño, convertir a webp, comprimir imagen, rotar foto, achicar imagen", category: "images", abstractionLevel: "atomic" },
 
     // Office documents — read
     { name: "office_leer_pdf", description: "Read and extract text from a PDF document. Spanish keywords: leer pdf, extraer texto pdf, abrir pdf, contenido pdf", category: "office", abstractionLevel: "atomic" },

package/packages/core/src/api/createAgent.ts

@@ -9,6 +9,7 @@
  */
 
 import { z } from "zod";
+import type { MCPClientManager } from "../mcp/index.ts";
 import type { ToolDefinition } from "../tools/ToolRegistry.ts";
 import type { SkillDefinition } from "../skills/defineSkill.ts";
 import type { Tool, ToolParameter } from "../tools/types.ts";
@@ -35,11 +36,28 @@ export interface Agent {
 	readonly name: string;
 	readonly id: string;
 	readonly config: AgentConfig;
-	chat(message: string, opts?: { threadId?: string; channel?: string }): AsyncGenerator<AgentEvent>;
+	/**
+	 * Con `stream: true` se emiten eventos `token` con los deltas del proveedor
+	 * a medida que llegan, además del `text` con la respuesta completa del turno.
+	 */
+	chat(
+		message: string,
+		opts?: { threadId?: string; channel?: string; stream?: boolean },
+	): AsyncGenerator<AgentEvent>;
 	run(task: string, opts?: { threadId?: string; channel?: string }): Promise<string>;
 }
 
 export type AgentEvent =
+	/**
+	 * Un fragmento recién llegado del proveedor, para pintar la respuesta
+	 * mientras se genera.
+	 *
+	 * Sólo aparece si se pide `stream: true`. Los proveedores ya emitían estos
+	 * deltas —el mecanismo estaba implementado— pero ningún punto de entrada los
+	 * pasaba, así que nunca llegaban a nadie: la respuesta aparecía de golpe al
+	 * terminar el turno.
+	 */
+	| { type: "token"; content: string }
 	| { type: "text"; content: string }
 	| { type: "tool_call"; name: string; args: Record<string, unknown> }
 	| { type: "tool_result"; name: string; result: unknown }
@@ -128,6 +146,40 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 		}
 	}
 
+	// Las skills declaradas seguían el mismo camino que las tools —y hasta acá no
+	// lo seguían: `config.skills` estaba tipado y se descartaba en silencio, así
+	// que declarar una skill no hacía absolutamente nada. Una skill no necesita
+	// ejecutor (es instruccional: metadatos más el cuerpo que se le inyecta al
+	// agente), pero sí necesita su fila y su entrada en el índice, o el modelo
+	// nunca la descubre.
+	if (config.skills?.length) {
+		const { createSkill, getSkill, updateSkill } = await import("../services/skills.ts");
+
+		for (const skill of config.skills) {
+			// El cuerpo se arma con los pasos declarados: es lo que lee el agente.
+			const body = [
+				skill.description,
+				"",
+				...skill.steps.map((s, i) => `${i + 1}. **${s.action}** — ${s.instruction}`),
+			].join("\n");
+
+			const campos = {
+				name: skill.name,
+				description: skill.description,
+				category: skill.category,
+				body,
+				tools: skill.tools,
+				triggers: skill.triggers,
+				version: skill.version,
+			};
+
+			// Idempotente: declarar la misma skill dos veces la actualiza.
+			const existente = await getSkill(skill.name);
+			if (existente) await updateSkill(skill.name, campos);
+			else await createSkill({ id: skill.name, ...campos });
+		}
+	}
+
 	// ─── Provider y modelo ────────────────────────────────────────────────────
 	// El loop los lee de la fila del agente, así que hay que dejarlos escritos.
 	const providerId = config.provider ?? "";
@@ -209,7 +261,7 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 	await syncCapabilityIndexes();
 
 	// ─── MCP ──────────────────────────────────────────────────────────────────
-	let mcpManager = null;
+	let mcpManager: MCPClientManager | null = null;
 	if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
 		const { MCPClientManager } = await import("../mcp/index.ts");
 		const mcpConfig = {
@@ -241,6 +293,17 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 			const threadId = opts?.threadId ?? crypto.randomUUID();
 			let response = "";
 
+			// `onToken` es un callback y esto es un generador: los deltas se
+			// encolan y se drenan entre chunks. Sin buffer habría que elegir entre
+			// perder tokens o bloquear al proveedor mientras el consumidor lee.
+			const pendientes: string[] = [];
+			const onToken = opts?.stream ? (t: string) => { pendientes.push(t); } : undefined;
+			const drenar = function* () {
+				while (pendientes.length > 0) {
+					yield { type: "token" as const, content: pendientes.shift()! };
+				}
+			};
+
 			for await (const chunk of runAgent({
 				agentId,
 				userMessage: message,
@@ -248,7 +311,9 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 				channel: opts?.channel ?? "cli",
 				mcpManager,
 				userId,
+				onToken,
 			})) {
+				yield* drenar();
 				for (const msg of chunk.agent?.messages ?? []) {
 					if (typeof msg.content === "string" && msg.content) {
 						response = msg.content;
@@ -268,6 +333,7 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 				}
 			}
 
+			yield* drenar();
 			yield { type: "done" as const, response };
 		},
 		async run(task, opts) {

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

@@ -0,0 +1,15 @@
+/**
+ * Artifacts — los archivos que produce un agente, fuera de la ventana de contexto.
+ *
+ * Cuando una tool devuelve algo grande —una imagen, un PDF, la salida enorme de
+ * un servidor MCP— serializarlo entero al prompt es lo peor que se puede hacer:
+ * se come el contexto y no aporta. En su lugar se guarda como artefacto y al
+ * modelo le llega una referencia (`artifact_ref`) que puede abrir con la tool
+ * `artifact_read` si de verdad necesita el contenido.
+ *
+ * `createArtifact` guarda; `inspectArtifact` da metadatos sin abrirlo;
+ * `readArtifactText` lo lee para consumo del propio proceso; `readArtifactBytes`
+ * devuelve los bytes crudos, que es lo que usa un canal para mandar la imagen.
+ */
+
+export * from "./store.ts";

package/packages/core/src/artifacts/store.ts

@@ -52,6 +52,11 @@ export async function createArtifact(input: {
   width?: number | null;
   height?: number | null;
   now?: number;
+  /**
+   * Cuándo caduca. `null` = nunca, para lo que es del usuario y no basura
+   * transitoria. Por omisión, los 7 días de siempre.
+   */
+  expiresAt?: number | null;
 }): Promise<ArtifactDoc> {
   const now = input.now ?? Date.now();
   const id = randomUUID();
@@ -77,7 +82,7 @@ export async function createArtifact(input: {
     height: input.height ?? null,
     status: "active",
     created_at: now,
-    expires_at: now + ARTIFACT_RETENTION_MS,
+    expires_at: input.expiresAt !== undefined ? input.expiresAt : now + ARTIFACT_RETENTION_MS,
     expired_at: null,
   };
 
@@ -222,12 +227,82 @@ export async function inspectArtifact(
   };
 }
 
+export interface ListArtifactsOptions {
+  /** Filtra por tipo: `image`, `document`… */
+  kind?: string;
+  includeExpired?: boolean;
+  limit?: number;
+}
+
+/**
+ * Los artefactos de un usuario, del más reciente al más viejo.
+ *
+ * No existía, y sin esto una interfaz no puede mostrarle a alguien lo que tiene
+ * guardado — ni una galería de imágenes ni la lista de adjuntos de una
+ * conversación.
+ */
+export async function listArtifacts(
+  userId: string,
+  opts: ListArtifactsOptions = {},
+): Promise<ArtifactDoc[]> {
+  const artifacts = await col<ArtifactDoc>("artifacts");
+  const rows = await artifacts.findBy("user_id", userId);
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (opts.includeExpired ? true : d.status === "active"))
+    .filter((d) => (opts.kind ? d.kind === opts.kind : true))
+    .sort((a, b) => b.created_at - a.created_at)
+    .slice(0, opts.limit ?? Number.MAX_SAFE_INTEGER);
+}
+
+/**
+ * Cambia cuándo caduca un artefacto. `null` = conservarlo indefinidamente.
+ *
+ * Es lo que le da al usuario el control: puede marcar como permanente algo que
+ * nació temporal, o ponerle fecha a algo que ya no necesita.
+ */
+export async function setArtifactRetention(
+  artifactId: string,
+  expiresAt: number | null,
+): Promise<ArtifactDoc | null> {
+  const artifacts = await col<ArtifactDoc>("artifacts");
+  const entry = await artifacts.get(artifactId);
+  if (!entry) return null;
+
+  const doc: ArtifactDoc = { ...entry.doc, expires_at: expiresAt };
+  await artifacts.put(artifactId, doc, { expectedVersion: entry.version });
+  return doc;
+}
+
+/**
+ * Borra el artefacto y su archivo, sin esperar a que caduque.
+ *
+ * A diferencia de `expireArtifacts`, que marca `status: "expired"` y conserva la
+ * fila como registro, esto la elimina: es un borrado pedido por el usuario, y
+ * dejar el rastro de algo que pidió borrar sería lo contrario de lo que pidió.
+ */
+export async function deleteArtifact(artifactId: string): Promise<boolean> {
+  const artifacts = await col<ArtifactDoc>("artifacts");
+  const entry = await artifacts.get(artifactId);
+  if (!entry) return false;
+
+  try {
+    if (existsSync(entry.doc.path)) unlinkSync(entry.doc.path);
+  } catch {
+    // El archivo puede haber desaparecido; la fila igual se va.
+  }
+  await artifacts.delete(artifactId);
+  return true;
+}
+
 export async function expireArtifacts(now = Date.now()): Promise<{ expired: number }> {
   const artifacts = await col<ArtifactDoc>("artifacts");
   const rows = await artifacts.scan({});
   let expired = 0;
   for (const row of rows) {
-    if (row.doc.status !== "active" || row.doc.expires_at > now) continue;
+    // `null` es explícito: el usuario pidió conservarlo. Saltarlo ANTES de
+    // comparar fechas evita que un `null > now` (que es false) lo borre.
+    if (row.doc.status !== "active" || row.doc.expires_at === null || row.doc.expires_at > now) continue;
     try {
       if (existsSync(row.doc.path)) unlinkSync(row.doc.path);
     } catch {

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

@@ -1 +1,10 @@
+/**
+ * Canvas — el estado visual de un enjambre corriendo.
+ *
+ * `canvas-manager.ts` guarda y sirve el snapshot; `emitter.ts` es por donde el
+ * runtime publica los cambios (un nodo que empieza a pensar, una delegación que
+ * arranca o termina). Quien construya una UI sobre el SDK consume ambos.
+ */
+
 export * from "./canvas-manager.ts";
+export * from "./emitter.ts";

package/packages/core/src/ethics/EthicsGuard.ts

@@ -37,8 +37,12 @@ export class EthicsGuard {
 	 * Con `agentRole` filtra por las que lo declaran en `applicable_to`; si
 	 * ninguna coincide devuelve todas, para no dejar al agente sin capa por un
 	 * `applicable_to` mal cargado.
+	 *
+	 * `userId` acota lo aprendido a quien corresponde: entran las globales
+	 * (`user_id === ""`, sembradas con el producto) y las que salieron de las
+	 * trazas de ese mismo usuario. Omitirlo deja sólo las globales.
 	 */
-	async getRules(agentRole?: string): Promise<EthicsRule[]> {
+	async getRules(agentRole?: string, userId?: string): Promise<EthicsRule[]> {
 		const playbookCol = await col<PlaybookDoc>("playbook");
 		const all = (await playbookCol.scan({}))
 			.map((e) => ({
@@ -48,8 +52,10 @@ export class EthicsGuard {
 				applicable_to: e.doc.applicable_to,
 				helpful_count: e.doc.helpful_count ?? 0,
 				active: e.doc.active,
+				user_id: e.doc.user_id ?? "",
 			}))
 			.filter((r) => r.active && r.category === RESPONSE_QUALITY)
+			.filter((r) => r.user_id === "" || r.user_id === (userId ?? ""))
 			.sort(byUsefulness);
 
 		if (!agentRole) return all;

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

@@ -0,0 +1,18 @@
+/**
+ * Events — el bus de eventos del runtime y la narración de lo que hace un agente.
+ *
+ * Dos buses con propósitos distintos:
+ *  - `eventBus`: eventos del proceso, tipados (`event-bus.ts`).
+ *  - `agentBus`: mensajería entre workers de un enjambre, con respaldo
+ *    persistente en HiveDB para que un worker lea lo que le dejaron mientras
+ *    no estaba (`agent-bus.ts`).
+ *
+ * La narración traduce una tool call a una frase que se le puede mostrar a
+ * alguien ("Buscando en la web...") en vez del nombre crudo de la tool.
+ */
+
+export * from "./event-bus.ts";
+export * from "./agent-bus.ts";
+export * from "./narration.ts";
+export * from "./tool-narration.ts";
+export * from "./channel-narration.ts";

package/packages/core/src/events/tool-narration.ts

@@ -43,7 +43,11 @@ const TOOL_NARRATIONS: Record<string, string> = {
   browser_click: "Haciendo clic...",
   browser_type: "Escribiendo en la página...",
   browser_screenshot: "Tomando captura de pantalla...",
+  computer_use_task: "Operando el navegador...",
   browser_extract: "Extrayendo información de la página...",
+  // Artefactos
+  artifact_inspect: "Verificando el archivo generado...",
+  artifact_read: "Leyendo el resultado completo...",
   // Canvas
   canvas_add_node: "Actualizando canvas...",
   canvas_update: "Actualizando canvas...",

package/packages/core/src/gateway/channel-notify.ts

@@ -1,16 +1,110 @@
 /**
- * Channel Notify — stub for SDK compatibility.
- * In the full harness this sends messages back to channels.
+ * Channel Notify — el camino de salida hacia el usuario.
+ *
+ * Esto era un stub que sólo hacía `console.log`, y estaba en el camino real: la
+ * tool `notify`, los reportes de progreso, el aviso de que una tarea programada
+ * terminó, el de un turno interrumpido por un crash y el de compactación pasan
+ * todos por acá. Es decir, un agente sobre el SDK **no podía hablarle al
+ * usuario por ningún canal** — mientras `channels/manager.ts` tenía adaptadores
+ * funcionales de Slack, Discord, Telegram y WhatsApp, sin nada que los conectara.
+ *
+ * El cableado es explícito y opcional: la app registra su `ChannelManager` con
+ * `setChannelManager()`. Sin registro se conserva el comportamiento anterior
+ * —un log— porque un proceso que no maneja canales (un script, un test) no
+ * debería fallar por intentar notificar.
+ *
+ * Resolver a quién enviar es la otra mitad. `ChannelManager.send` necesita un
+ * `sessionId`, que es el contacto o grupo dentro del canal. Se obtiene del
+ * `threadId` (`${userId}/${canal}/${peer}`) cuando viene, y si no, buscando la
+ * conversación de ese usuario en ese canal. Sin eso el mensaje no sabe a qué
+ * chat volver.
  */
 
+import { logger } from "../utils/logger.ts";
+import { parseThreadId } from "../agent/thread-id.ts";
+import { threadForChannel, listThreads } from "../agent/thread-store.ts";
+
+const log = logger.child("channel-notify");
+
+/** Lo mínimo que se necesita de un ChannelManager, para no atarse a su clase. */
+export interface ChannelSender {
+  send(channelName: string, sessionId: string, message: unknown, accountId?: string): Promise<void>;
+}
+
+let _sender: ChannelSender | null = null;
+
+/**
+ * Conecta el manager de canales. Llamalo una vez al arrancar, después de
+ * `channelManager.initialize()`.
+ */
+export function setChannelManager(sender: ChannelSender | null): void {
+  _sender = sender;
+  log.info(sender ? "canales conectados: las notificaciones salen de verdad" : "canales desconectados");
+}
+
+export function getChannelManager(): ChannelSender | null {
+  return _sender;
+}
+
+/**
+ * A qué conversación del canal enviar.
+ *
+ * El `threadId` ya lleva el peer adentro, así que si viene se usa. Si no, se
+ * busca el hilo del usuario en ese canal; y como último recurso se usa el
+ * `userId`, que es lo que hacían las instalaciones anteriores a la separación
+ * por canal.
+ */
+async function resolveSessionId(
+  channel: string,
+  userId: string,
+  threadId?: string,
+): Promise<string | null> {
+  if (threadId) {
+    const parts = parseThreadId(threadId);
+    if (parts?.peerId) return parts.peerId;
+  }
+  // `threadForChannel` mira `userIdentities`, que es el registro canónico de
+  // "por dónde se alcanza a este usuario".
+  const delCanal = await threadForChannel(userId, channel).catch(() => null);
+  if (delCanal) {
+    const parts = parseThreadId(delCanal);
+    if (parts?.peerId) return parts.peerId;
+  }
+
+  // Si no hay identidad registrada pero sí una conversación abierta en ese
+  // canal, ahí es donde responder: es evidencia igual de válida de dónde está
+  // el usuario, y evita perder el aviso por un registro que nadie llenó.
+  const hilos = await listThreads(userId, { channel }).catch(() => []);
+  const reciente = hilos[0];
+  if (reciente) {
+    const parts = parseThreadId(reciente.id);
+    if (parts?.peerId) return parts.peerId;
+  }
+
+  return userId || null;
+}
+
 export async function notifyChannel(
   channel: string,
   userId: string,
   message: string,
   opts?: { threadId?: string; metadata?: Record<string, unknown> }
 ): Promise<void> {
-  // TODO: integrate with ChannelManager for full functionality
-  console.log(`[channel-notify] ${channel}: ${message}`);
+  if (!_sender) {
+    // Sin canales conectados no es un error: hay procesos que legítimamente no
+    // los tienen. Pero conviene que se note, porque un `notify` que no llega es
+    // silencioso por naturaleza.
+    log.warn(`sin ChannelManager conectado — el mensaje para ${channel} no sale: ${message.slice(0, 80)}`);
+    return;
+  }
+
+  const sessionId = await resolveSessionId(channel, userId, opts?.threadId);
+  if (!sessionId) {
+    log.warn(`no pude resolver a qué conversación de ${channel} enviarle a ${userId}`);
+    return;
+  }
+
+  await _sender.send(channel, sessionId, message);
 }
 
 export async function sendToUserChannel(
@@ -23,15 +117,18 @@ export async function sendToUserChannel(
     await notifyChannel(channel, userId, message, opts);
     return { ok: true };
   } catch (err) {
+    // Un canal caído no debe tumbar el turno que estaba notificando.
+    log.warn(`falló el envío a ${channel}: ${(err as Error).message}`);
     return { ok: false, error: (err as Error).message };
   }
 }
 
 export async function broadcastNotification(
   channels: string[],
-  message: string
+  message: string,
+  userId = "",
 ): Promise<void> {
   for (const channel of channels) {
-    await notifyChannel(channel, "", message);
+    await notifyChannel(channel, userId, message).catch(() => {});
   }
 }

package/packages/core/src/gateway/durable-queue.ts

@@ -76,6 +76,17 @@ export function registerExecutor(type: JobType, executor: JobExecutor): void {
   log.info(`[registerExecutor] Registered executor for type=${type}`);
 }
 
+/**
+ * Los tipos de job que este proceso sabe ejecutar.
+ *
+ * El registro era privado, así que no había forma de comprobar desde fuera si
+ * un tipo quedó cableado — y un job encolado sin ejecutor no falla al encolarse
+ * sino al tomarse, que es tarde y lejos de donde está el error.
+ */
+export function getRegisteredExecutorTypes(): JobType[] {
+  return [...executors.keys()];
+}
+
 export interface JobTerminalOutcome {
   ok: boolean;
   result?: unknown;
@@ -92,7 +103,8 @@ export function registerTerminalHook(type: JobType, hook: JobTerminalHook): void
   terminalHooks.set(type, hook);
 }
 
-async function runTerminalHook(job: JobDoc, outcome: JobTerminalOutcome): Promise<void> {
+/** Exported so job-store.ts's reclaimOrInterrupt can fire it too (dynamic import there — see its call site). */
+export async function runTerminalHook(job: JobDoc, outcome: JobTerminalOutcome): Promise<void> {
   const hook = terminalHooks.get(job.type);
   if (!hook) return;
   try {

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

@@ -1,2 +1,5 @@
 export { startGateway } from "./server.ts";
 export type { GatewayConfig } from "./server.ts";
+
+// Salida hacia el usuario: la app conecta su ChannelManager con setChannelManager().
+export { setChannelManager, getChannelManager, notifyChannel, sendToUserChannel, broadcastNotification, type ChannelSender } from "./channel-notify.ts";

package/packages/core/src/gateway/job-store.ts

@@ -337,6 +337,12 @@ export async function reclaimOrInterrupt(jobId: string, opts?: { force?: boolean
       try {
         await c.put(jobId, updated, { expectedVersion: entry.version });
         log.warn(`[reclaimOrInterrupt] Job ${jobId} interrupted (attempts exhausted)`);
+        // Terminal via lease-expiry, not executeJob's normal fail path — that
+        // path already fires the hook, this one didn't before. Dynamic import
+        // avoids a static circular import (durable-queue.ts imports
+        // reclaimOrInterrupt from this module).
+        const { runTerminalHook } = await import("./durable-queue.ts");
+        await runTerminalHook(updated, { ok: false, error: updated.error ?? "Job interrupted after lease expiry" }).catch(() => {});
         return updated;
       } catch {
         await occRetryDelay(attempt);