@johpaz/hive-sdk 0.1.6 → 0.3.0

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

@@ -8,9 +8,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { extname, join } from "node:path";
-import { getHiveDir } from "../config/loader";
-import { col, updateDoc } from "../storage/hive";
-import type { ArtifactDoc } from "../storage/collections";
+import { getHiveDir } from "../config/loader.ts";
+import { col, updateDoc } from "../storage/hive.ts";
+import type { ArtifactDoc } from "../storage/collections.ts";
 
 const ARTIFACT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -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,
   };
 
@@ -91,6 +96,87 @@ export async function createArtifact(input: {
   }
 }
 
+/**
+ * Reads an artifact's bytes straight off disk — for server-side consumers
+ * that don't need an HTTP round trip (routes/artifacts.ts is for the
+ * browser; channels/*.ts send()s use this directly to build a Telegram/
+ * Discord/Slack/WhatsApp photo attachment from the same file).
+ */
+export async function readArtifactBytes(
+  artifactId: string,
+): Promise<{ bytes: Buffer; mimeType: string } | null> {
+  const artifacts = await col<ArtifactDoc>("artifacts");
+  const entry = await artifacts.get(artifactId);
+  if (!entry || entry.doc.status !== "active") return null;
+  if (!existsSync(entry.doc.path)) return null;
+  return { bytes: readFileSync(entry.doc.path), mimeType: entry.doc.mime_type };
+}
+
+/** Beyond this an artifact stops being something an agent can read into a context window. */
+const MAX_TEXT_ARTIFACT_BYTES = 25 * 1024 * 1024;
+
+function looksBinary(mimeType: string, bytes: Buffer): boolean {
+  if (/^(image|audio|video)\//.test(mimeType)) return true;
+  if (mimeType === "application/octet-stream") return true;
+  // A NUL byte in the first KB is the classic "this is not text" tell — a
+  // mislabelled text/plain artifact would otherwise decode to garbage.
+  return bytes.subarray(0, 1024).includes(0x00);
+}
+
+export type ArtifactTextResult = {
+  ok: boolean;
+  text?: string;
+  artifact?: ArtifactDoc;
+  error?: string;
+  status?: string;
+};
+
+/**
+ * Decodes a text artifact for in-process consumers that need its *content*,
+ * not just its metadata (inspectArtifact) or its raw bytes (readArtifactBytes).
+ *
+ * This exists because mcp-result-normalizer.ts moves oversized MCP text results
+ * out of the context window and hands the model an `artifact_ref` instead. Until
+ * this, nothing could read that reference back: the agent held a receipt it
+ * could not cash, burned its iterations guessing, and the turn died on an empty
+ * synthesis. Ownership and status checks mirror inspectArtifact's.
+ */
+export async function readArtifactText(
+  artifactId: string,
+  options: { userId?: string } = {},
+): Promise<ArtifactTextResult> {
+  const artifacts = await col<ArtifactDoc>("artifacts");
+  const entry = await artifacts.get(artifactId);
+  if (!entry) return { ok: false, error: "Artifact not found" };
+  const artifact = entry.doc;
+
+  if (options.userId && artifact.user_id && artifact.user_id !== options.userId) {
+    return { ok: false, error: "Artifact not accessible" };
+  }
+  if (artifact.status !== "active") {
+    return { ok: false, error: "Artifact binary has expired", status: artifact.status };
+  }
+  if (!existsSync(artifact.path)) {
+    return { ok: false, error: "Artifact binary is missing", status: "missing" };
+  }
+  if (artifact.size > MAX_TEXT_ARTIFACT_BYTES) {
+    return {
+      ok: false,
+      error: `Artifact is too large to read as text (${artifact.size} bytes, limit ${MAX_TEXT_ARTIFACT_BYTES})`,
+    };
+  }
+
+  const bytes = readFileSync(artifact.path);
+  if (looksBinary(detectedMime(bytes, artifact.mime_type), bytes)) {
+    return {
+      ok: false,
+      error: `Artifact is binary (${detectedMime(bytes, artifact.mime_type)}) — use artifact_inspect for its metadata`,
+    };
+  }
+
+  return { ok: true, text: bytes.toString("utf-8"), artifact };
+}
+
 export async function inspectArtifact(
   artifactId: string,
   options: { userId?: string } = {},
@@ -141,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/emitter.ts

@@ -1,5 +1,5 @@
-import { col, fromIndexable } from "../storage/hive"
-import type { AgentDoc, McpServerDoc } from "../storage/collections"
+import { col, fromIndexable } from "../storage/hive.ts"
+import type { AgentDoc, McpServerDoc } from "../storage/collections.ts"
 
 export interface CanvasEvent {
   type: CanvasEventType

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/channels/telegram.ts

@@ -3,7 +3,7 @@ import { BaseChannel, type ChannelConfig, type IncomingMessage, type OutboundMes
 import { logger } from "../utils/logger.ts";
 import { col, updateDoc } from "../storage/hive.ts";
 import type { ChannelDoc, UserIdentityDoc } from "../storage/collections.ts";
-import { resolveUserId } from "../storage/onboarding";
+import { resolveUserId } from "../storage/onboarding.ts";
 
 export interface TelegramConfig extends ChannelConfig {
   botToken: string;

package/packages/core/src/channels/webchat.ts

@@ -1,7 +1,7 @@
 import type { ServerWebSocket } from "bun";
 import { BaseChannel, type ChannelConfig, type IncomingMessage, type OutboundMessage } from "./base.ts";
 import { logger } from "../utils/logger.ts";
-import { resolveUserId } from "../storage/onboarding";
+import { resolveUserId } from "../storage/onboarding.ts";
 
 export interface WebChatConfig extends ChannelConfig {
   accountId?: string;

package/packages/core/src/config/loader.ts

@@ -20,7 +20,14 @@ export function loadEnv(hiveDir: string): void {
         const [key, ...valueParts] = trimmed.split("=");
         if (key && valueParts.length > 0) {
           const value = valueParts.join("=").trim().replace(/^['"]|['"]$/g, "");
-          process.env[key.trim()] = value;
+          const normalizedKey = key.trim();
+          // Explicit process environment values (for example the random
+          // port assigned by the desktop shell) must take precedence over the
+          // persisted .env file. This follows dotenv conventions and prevents
+          // a previous CLI port from breaking desktop startup.
+          if (process.env[normalizedKey] === undefined) {
+            process.env[normalizedKey] = value;
+          }
         }
       }
     } catch (e) {
@@ -120,11 +127,13 @@ const BrowserConfigSchema = z.object({
   headless: z.boolean().optional(),
   timeoutMs: z.number().optional(),
   sessionName: z.string().optional(),
-  // "agent-browser" (default) usa Chrome via CLI y sirve headless/Docker.
-  // "webview" usa Bun.WebView in-process — mucho más rápido y sin instalación,
-  // pero requiere Chrome instalado (o macOS con WebKit). "auto" toma webview
-  // sólo si hay motor. Lo pisa HIVE_BROWSER_BACKEND.
+  // Queda un solo backend: Bun.WebView in-process. La clave sobrevive para no
+  // romper configs viejas —"agent-browser" se acepta, avisa y usa el WebView—
+  // y se puede quitar sin más. Lo pisa HIVE_BROWSER_BACKEND.
   backend: z.enum(["agent-browser", "webview", "auto"]).optional(),
+  // Guarda las cookies para que los logins sobrevivan a un reinicio. Default
+  // activo; apagarlo hace que cada arranque empiece sin historia.
+  persistSession: z.boolean().optional(),
 });
 
 const CanvasConfigSchema = z.object({

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/agent-bus.ts

@@ -10,9 +10,9 @@
  */
 
 import { EventEmitter } from "events";
-import { logger } from "../utils/logger";
-import { col, nextId, toIndexable, fromIndexable, BROADCAST } from "../storage/hive";
-import type { AgentBusMessageDoc, TaskDoc } from "../storage/collections";
+import { logger } from "../utils/logger.ts";
+import { col, nextId, toIndexable, fromIndexable, BROADCAST } from "../storage/hive.ts";
+import type { AgentBusMessageDoc, TaskDoc } from "../storage/collections.ts";
 
 const log = logger.child("agent-bus");
 

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

@@ -6,9 +6,9 @@
 // messages before the actual answer — noise for the user and a rate-limit /
 // ban risk on WhatsApp. This module decides what reaches those channels.
 
-import { col } from "../storage/hive";
-import type { ChannelDoc, NarrationEventDoc } from "../storage/collections";
-import { logger } from "../utils/logger";
+import { col } from "../storage/hive.ts";
+import type { ChannelDoc, NarrationEventDoc } from "../storage/collections.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("narration:channel");
 

package/packages/core/src/events/event-bus.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from "events";
-import { logger } from "../utils/logger";
+import { logger } from "../utils/logger.ts";
 
 export interface EventMap {
   "message:received": {

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/narration.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { col } from "../storage/hive";
-import type { NarrationEventDoc } from "../storage/collections";
-import { logger } from "../utils/logger";
+import { col } from "../storage/hive.ts";
+import type { NarrationEventDoc } from "../storage/collections.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("narration");
 

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/delegation-groups.ts

@@ -1,10 +1,10 @@
-import { col } from "../storage/hive";
+import { col } from "../storage/hive.ts";
 import type {
   DelegationGroupDoc,
   DelegationGroupOutcome,
-} from "../storage/collections";
-import { logger } from "../utils/logger";
-import { publishNarration } from "../events/narration";
+} from "../storage/collections.ts";
+import { logger } from "../utils/logger.ts";
+import { publishNarration } from "../events/narration.ts";
 
 const log = logger.child("delegation-groups");
 const MAX_RETRIES = 8;

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

@@ -14,7 +14,7 @@
  * is preserved, while all queue state is mirrored to the DB.
  */
 
-import { logger } from "../utils/logger";
+import { logger } from "../utils/logger.ts";
 import {
   createJob,
   claimJob,
@@ -30,9 +30,9 @@ import {
   loadJobRetryPolicy,
   DEFAULT_JOB_RETRY_POLICY,
   type JobRetryPolicy,
-} from "./job-store";
-import type { JobDoc } from "../storage/collections";
-import { getBootId } from "../storage/boot-id";
+} from "./job-store.ts";
+import type { JobDoc } from "../storage/collections.ts";
+import { getBootId } from "../storage/boot-id.ts";
 
 const log = logger.child("durable-queue");
 
@@ -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 {
@@ -287,7 +299,7 @@ export class DurableLaneQueue {
     let leasedHere = true;
     const leaseRenewer = setInterval(async () => {
       if (leasedHere) {
-        const { renewLease } = await import("./job-store");
+        const { renewLease } = await import("./job-store.ts");
         await renewLease(job.id, this.bootId).catch(() => {});
       }
     }, 30_000);

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

@@ -5,11 +5,11 @@
  * path guarantees only one process wins the race for the same job.
  */
 
-import { col, nextId, updateDoc, toIndexable } from "../storage/hive";
-import type { JobDoc } from "../storage/collections";
-import { getBootId } from "../storage/boot-id";
-import { logger } from "../utils/logger";
-import { loadConfig } from "../config/loader";
+import { col, nextId, updateDoc, toIndexable } from "../storage/hive.ts";
+import type { JobDoc } from "../storage/collections.ts";
+import { getBootId } from "../storage/boot-id.ts";
+import { logger } from "../utils/logger.ts";
+import { loadConfig } from "../config/loader.ts";
 
 const log = logger.child("job-store");
 
@@ -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);

package/packages/core/src/gateway/notification-inbox.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
-import type { NotificationDoc } from "../storage/collections";
-import { col, updateDoc } from "../storage/hive";
+import type { NotificationDoc } from "../storage/collections.ts";
+import { col, updateDoc } from "../storage/hive.ts";
 
 export async function createNotification(input: {
   userId: string;

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

@@ -7,9 +7,9 @@
  * - WebSocket /ws — real-time streaming
  */
 
-import { logger } from "../utils/logger";
+import { logger } from "../utils/logger.ts";
 import { runAgent } from "../agent/agent-loop.ts";
-import type { MCPClientManager } from "../mcp/index";
+import type { MCPClientManager } from "../mcp/index.ts";
 
 const log = logger.child("gateway");