@danieltmn/tamnora 0.5.1 → 0.6.1

package/harness/packages/server/src/lib/channels/telegram.js

@@ -0,0 +1,532 @@
+// Canal de Telegram: long polling (no necesita URL publica) con soporte de
+// texto, imagenes, notas de voz (transcripcion) y aprobaciones por botones
+// inline. Cada chat mapea a una sesion del harness.
+
+import { randomUUID } from 'node:crypto';
+import { runAgent, createTools, resolveMode, summarizeToolCall, listProviderModels, PROVIDER_META } from '../core.js';
+import { resolveExistingDir } from '../workspace.js';
+
+const API = 'https://api.telegram.org';
+
+const HELP = [
+  'Tamnora Harness — bot',
+  '',
+  '/menu — panel con botones (modelo, modo, proveedor)',
+  '/new — nueva sesión',
+  '/status — proveedor, modelo, modo y sesión',
+  '/model [id] — cambia el modelo (sin id: lista con botones)',
+  '/provider [id] — cambia el proveedor (sin id: lista)',
+  '/mode [plan|build] — cambia el modo (sin arg: panel)',
+  '/stop — cancela la respuesta en curso',
+  '/help — esta ayuda',
+  '',
+  'Podés mandar texto, imágenes o notas de voz.',
+].join('\n');
+
+async function tg(token, method, payload) {
+  const res = await fetch(`${API}/bot${token}/${method}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload ?? {}),
+  });
+  let data = null;
+  try {
+    data = await res.json();
+  } catch {
+    data = null;
+  }
+  if (!data?.ok) {
+    const error = new Error(data?.description || `HTTP ${res.status}`);
+    error.status = res.status;
+    throw error;
+  }
+  return data.result;
+}
+
+/** Valida un token consultando `getMe`. Devuelve `{ ok, username, name }` o `{ ok:false, error }`. */
+export async function getTelegramBotInfo(token) {
+  if (!token) return { ok: false, error: 'Falta el token.' };
+  try {
+    const result = await tg(token, 'getMe', {});
+    return { ok: true, username: result?.username ?? null, name: result?.first_name ?? null };
+  } catch (error) {
+    return { ok: false, error: error?.message ?? String(error) };
+  }
+}
+
+async function downloadFile(token, fileId) {
+  const file = await tg(token, 'getFile', { file_id: fileId });
+  const res = await fetch(`${API}/file/bot${token}/${file.file_path}`);
+  if (!res.ok) throw new Error(`no se pudo bajar el archivo (HTTP ${res.status})`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+function splitMessage(text, max = 3900) {
+  const value = String(text ?? '').trim() || '(sin texto)';
+  const parts = [];
+  for (let i = 0; i < value.length; i += max) parts.push(value.slice(i, i + max));
+  return parts;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Linea de cierre del turno (rondas, herramientas, duración). */
+export function completionFooter(stopReason, rounds, toolCalls, durationMs) {
+  const parts = [`${rounds ?? '?'} ronda${rounds === 1 ? '' : 's'}`];
+  if (toolCalls) parts.push(`${toolCalls} herramienta${toolCalls === 1 ? '' : 's'}`);
+  if (durationMs > 0) parts.push(durationMs >= 1000 ? `${(durationMs / 1000).toFixed(1)}s` : `${durationMs}ms`);
+  const maxed = stopReason === 'max_rounds';
+  return `${maxed ? '⚠ máximo de rondas' : '✓ terminado'} · ${parts.join(' · ')}`;
+}
+
+/**
+ * Arranca el canal de Telegram. Devuelve `{ stop, notify }` o `null` sin token.
+ */
+export function startTelegramChannel(ctx, { token, allowedChatIds = [], transcribeModel = 'whisper-1', log = () => {} } = {}) {
+  if (!token) return null;
+  const allowed = new Set(allowedChatIds.map(String));
+  const controllers = new Map();
+  const ownSessions = new Set();
+  const modelChoices = new Map();
+  let running = true;
+  let offset = 0;
+
+  const authorized = (chatId) => allowed.size > 0 && allowed.has(String(chatId));
+  const sessionKey = (chatId) => `telegram:chat:${chatId}`;
+  const reverseKey = (sessionId) => `telegram:session:${sessionId}`;
+
+  async function send(chatId, text, extra = {}) {
+    let first = null;
+    for (const chunk of splitMessage(text)) {
+      const result = await tg(token, 'sendMessage', { chat_id: chatId, text: chunk, disable_web_page_preview: true, ...extra });
+      if (!first) first = result;
+    }
+    return first;
+  }
+
+  async function edit(chatId, messageId, text) {
+    const parts = splitMessage(text);
+    await tg(token, 'editMessageText', { chat_id: chatId, message_id: messageId, text: parts[0], disable_web_page_preview: true }).catch(() => null);
+    for (let i = 1; i < parts.length; i++) {
+      await tg(token, 'sendMessage', { chat_id: chatId, text: parts[i], disable_web_page_preview: true }).catch(() => null);
+    }
+  }
+
+  function ensureSession(chatId) {
+    const key = sessionKey(chatId);
+    let sessionId = ctx.store.getSetting(key);
+    if (!sessionId || !ctx.store.getSession(sessionId)) {
+      sessionId = ctx.store.createSession({
+        title: `Telegram ${chatId}`,
+        provider: ctx.effectiveProviderId(),
+        model: ctx.effectiveModel(),
+        cwd: ctx.cwd,
+        meta: { telegramChatId: String(chatId) },
+      });
+      ctx.store.setSetting(key, sessionId);
+    }
+    ctx.store.setSetting(reverseKey(sessionId), String(chatId));
+    return sessionId;
+  }
+
+  async function transcribe(buffer, filename) {
+    const providerId = ctx.effectiveProviderId();
+    const baseUrl = (ctx.providerSettings(providerId).baseUrl || '').replace(/\/+$/, '');
+    const apiKey = ctx.apiKeyFor(providerId);
+    if (!baseUrl) throw new Error('el proveedor no tiene baseUrl para transcribir');
+    const form = new FormData();
+    form.append('file', new Blob([buffer]), filename);
+    form.append('model', transcribeModel);
+    const res = await fetch(`${baseUrl}/audio/transcriptions`, {
+      method: 'POST',
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      body: form,
+    });
+    if (!res.ok) throw new Error(`transcripción falló (HTTP ${res.status})`);
+    const data = await res.json();
+    return String(data.text ?? '').trim();
+  }
+
+  async function run(chatId, input, images = []) {
+    const sessionId = ensureSession(chatId);
+    const session = ctx.store.getSession(sessionId);
+    const providerId = session.provider || ctx.effectiveProviderId();
+    const model = session.model || ctx.effectiveModel();
+    if (!model) {
+      await send(chatId, 'Falta el modelo. Usá /model <id> o configurá uno en Ajustes.');
+      return;
+    }
+    const mode = resolveMode(ctx.effectiveMode());
+    const cwd = resolveExistingDir(session.cwd || ctx.cwd);
+    const history = ctx.store.getMessages(sessionId);
+
+    let mcp = null;
+    try {
+      mcp = await ctx.getMcp();
+    } catch {
+      mcp = null;
+    }
+
+    const onAsk = async (name, args) => {
+      const askId = randomUUID();
+      const preview = JSON.stringify(args ?? {}).slice(0, 300);
+      await send(chatId, `⚠ Permiso para ${name}\n${preview}`, {
+        reply_markup: {
+          inline_keyboard: [
+            [
+              { text: 'Permitir', callback_data: `perm:${askId}:allow` },
+              { text: 'Denegar', callback_data: `perm:${askId}:deny` },
+            ],
+          ],
+        },
+      });
+      return ctx.approvals.ask(askId);
+    };
+
+    const local = createTools({
+      root: cwd,
+      enabled: mode.tools ?? undefined,
+      permissions: ctx.config.permissions,
+      yes: false,
+      onAsk,
+      mcp,
+    });
+    const exposeAdmin = !mode.tools;
+    const admin = ctx.agentTools;
+    const definitions = exposeAdmin ? [...local.definitions, ...admin.definitions] : local.definitions;
+    const execute = (name, args, context) =>
+      exposeAdmin && admin.handles(name)
+        ? admin.execute(name, args, { approve: onAsk })
+        : local.execute(name, args, context);
+    const { provider, config } = ctx.resolveProvider({
+      ...ctx.providerSettings(providerId),
+      apiKey: ctx.apiKeyFor(providerId),
+    });
+    const basePrompt = await ctx.systemPromptFor(cwd);
+    const userMessage = images.length
+      ? { role: 'user', content: [{ type: 'text', text: input }, ...images.map((url) => ({ type: 'image_url', image_url: { url } }))] }
+      : { role: 'user', content: input };
+    const messages = [
+      { role: 'system', content: mode.systemPrompt ? `${basePrompt}\n\n${mode.systemPrompt}` : basePrompt },
+      ...history,
+      userMessage,
+    ];
+
+    const controller = new AbortController();
+    controllers.set(String(chatId), controller);
+    ownSessions.add(sessionId);
+    const startedAt = Date.now();
+    const message = await send(chatId, '…');
+    let full = '';
+    let activity = '';
+    let lastEdit = 0;
+
+    const render = () => {
+      const body = full.trim();
+      const suffix = activity ? `\n\n— ${activity}` : '';
+      return `${body || '…'}${suffix}`;
+    };
+
+    try {
+      await tg(token, 'sendChatAction', { chat_id: chatId, action: 'typing' }).catch(() => null);
+      const result = await runAgent({
+        provider,
+        config,
+        model,
+        messages,
+        tools: definitions,
+        execute,
+        signal: controller.signal,
+        maxRounds: ctx.config.maxRounds,
+        onEvent(event) {
+          if (event.type === 'text') {
+            full = event.full;
+          } else if (event.type === 'tool_call') {
+            activity = `${event.name} ${summarizeToolCall(event.name, event.args)}`.trim();
+          } else if (event.type === 'tool_result') {
+            activity = `${event.name} ✓`;
+          } else {
+            return;
+          }
+          const now = Date.now();
+          if (now - lastEdit > 1200) {
+            lastEdit = now;
+            edit(chatId, message.message_id, render());
+          }
+        },
+      });
+      const newMessages = result.messages.slice(messages.length);
+      const toolCalls = newMessages.filter((m) => m.role === 'tool').length;
+      const durationMs = Date.now() - startedAt;
+      let body = result.content?.trim() || full.trim();
+      if (!body) {
+        if (result.stopReason === 'max_rounds') {
+          body = `⚠ El agente alcanzó el máximo de rondas (${result.rounds}) sin respuesta final.${
+            toolCalls ? ` Hizo ${toolCalls} herramientas.` : ''
+          } Pedile que continúe o subí maxRounds.`;
+        } else if (toolCalls) {
+          body = '✓ El agente terminó sus herramientas, pero no devolvió un mensaje final.';
+        } else {
+          body = '(sin texto)';
+        }
+      }
+      const footer = completionFooter(result.stopReason, result.rounds, toolCalls, durationMs);
+      await edit(chatId, message.message_id, `${body}\n\n— ${footer}`);
+      ctx.store.addMessages(sessionId, newMessages);
+      ctx.store.touchSession(sessionId, { provider: providerId, model });
+    } catch (error) {
+      await edit(chatId, message.message_id, error?.name === 'AbortError' ? 'Cancelado.' : `Error: ${error?.message ?? error}`);
+    } finally {
+      controllers.delete(String(chatId));
+      ownSessions.delete(sessionId);
+      mcp?.close?.();
+    }
+  }
+
+  async function sendMenu(chatId) {
+    const sessionId = ensureSession(chatId);
+    const session = ctx.store.getSession(sessionId);
+    const providerId = session?.provider || ctx.effectiveProviderId();
+    const model = session?.model || ctx.effectiveModel() || '—';
+    const mode = resolveMode(ctx.effectiveMode());
+    const text = ['⚙ Panel', `proveedor: ${providerId}`, `modelo: ${model}`, `modo: ${mode.label}`].join('\n');
+    await send(chatId, text, {
+      reply_markup: {
+        inline_keyboard: [
+          [
+            { text: mode.id === 'plan' ? '● Plan' : 'Plan', callback_data: 'mode:plan' },
+            { text: mode.id === 'agent' ? '● Build' : 'Build', callback_data: 'mode:agent' },
+          ],
+          [
+            { text: 'modelos', callback_data: 'menu:models' },
+            { text: 'proveedores', callback_data: 'menu:providers' },
+          ],
+          [
+            { text: '🆕 nueva', callback_data: 'menu:new' },
+            { text: '⏹ detener', callback_data: 'menu:stop' },
+          ],
+        ],
+      },
+    });
+  }
+
+  async function sendModels(chatId) {
+    const sessionId = ensureSession(chatId);
+    const providerId = ctx.store.getSession(sessionId)?.provider || ctx.effectiveProviderId();
+    const models = await listProviderModels({
+      ...ctx.providerSettings(providerId),
+      apiKey: ctx.apiKeyFor(providerId),
+    }).catch(() => []);
+
+    const current = ctx.store.getSession(sessionId)?.model || ctx.effectiveModel();
+    if (!models?.length) return send(chatId, 'No pude listar modelos. Usá /model <id>.');
+    const capped = models.slice(0, 12);
+    modelChoices.set(String(chatId), capped.map((m) => m.id));
+    const rows = capped.map((m, i) => [
+      { text: `${m.id === current ? '● ' : ''}${m.label || m.id}`, callback_data: `model:${i}` },
+    ]);
+    rows.push([{ text: '‹ panel', callback_data: 'menu:home' }]);
+    await send(chatId, `Modelos de ${providerId} (elegí uno):`, { reply_markup: { inline_keyboard: rows } });
+    if (models.length > capped.length) {
+      send(chatId, `Hay ${models.length} modelos; mostré 12. Para otro, usá /model <id>.`).catch(() => {});
+    }
+  }
+
+  async function sendProviders(chatId) {
+    const custom = ctx.customProviderDefs?.() ?? [];
+    const ids = [...new Set([...PROVIDER_META.map((p) => p.id), ...custom.map((p) => p.id)])];
+    const current = ctx.effectiveProviderId();
+    const rows = ids.map((id) => [{ text: `${id === current ? '● ' : ''}${id}`, callback_data: `provider:${id}` }]);
+    rows.push([{ text: '‹ panel', callback_data: 'menu:home' }]);
+    await send(chatId, 'Proveedores (elegí uno):', { reply_markup: { inline_keyboard: rows } });
+  }
+
+  async function handleCommand(chatId, text) {
+    const [raw, ...rest] = text.slice(1).split(/\s+/);
+    const cmd = raw.toLowerCase();
+    const arg = rest.join(' ').trim();
+    const sessionId = ctx.store.getSetting(sessionKey(chatId));
+    if (cmd === 'start' || cmd === 'help' || cmd === 'ayuda') return send(chatId, HELP);
+    if (cmd === 'menu' || cmd === 'panel' || cmd === 'config') return sendMenu(chatId);
+    if (cmd === 'new' || cmd === 'nueva') {
+      ctx.store.setSetting(sessionKey(chatId), null);
+      return send(chatId, 'Nueva sesión. Mandá tu mensaje.');
+    }
+    if (cmd === 'status') {
+      const session = sessionId ? ctx.store.getSession(sessionId) : null;
+      return send(
+        chatId,
+        `proveedor: ${session?.provider || ctx.effectiveProviderId()}\nmodelo: ${session?.model || ctx.effectiveModel() || '—'}\nmodo: ${ctx.effectiveMode()}\nsesión: ${session?.title || '—'}`
+      );
+    }
+    if (cmd === 'model' || cmd === 'modelo') {
+      if (!arg) return sendModels(chatId);
+      ctx.store.setSetting('activeModel', arg);
+      if (sessionId) ctx.store.touchSession(sessionId, { model: arg });
+      return send(chatId, `modelo: ${arg}`);
+    }
+    if (cmd === 'provider' || cmd === 'proveedor') {
+      if (!arg) return sendProviders(chatId);
+      ctx.store.setSetting('activeProvider', arg);
+      if (sessionId) ctx.store.touchSession(sessionId, { provider: arg });
+      return send(chatId, `proveedor: ${arg}`);
+    }
+    if (cmd === 'mode' || cmd === 'modo') {
+      if (!arg) return sendMenu(chatId);
+      const id = arg.toLowerCase() === 'build' ? 'agent' : arg.toLowerCase();
+      ctx.store.setSetting('activeMode', resolveMode(id).id);
+      return send(chatId, `modo: ${resolveMode(id).label}`);
+    }
+    if (cmd === 'stop' || cmd === 'parar') {
+      controllers.get(String(chatId))?.abort();
+      return send(chatId, 'Cancelando…');
+    }
+    return send(chatId, `Comando desconocido: /${cmd}.\n\n${HELP}`);
+  }
+
+  async function handleVoice(chatId, voice) {
+    await send(chatId, '🎧 Transcribiendo…');
+    try {
+      const buffer = await downloadFile(token, voice.file_id);
+      const text = await transcribe(buffer, voice.file_name || 'audio.ogg');
+      if (!text) return send(chatId, 'No pude transcribir el audio.');
+      await send(chatId, `📝 ${text}`);
+      return run(chatId, text);
+    } catch (error) {
+      return send(chatId, `No pude procesar el audio: ${error.message}`);
+    }
+  }
+
+  async function handleMessage(message) {
+    const chatId = String(message.chat.id);
+    if (!authorized(chatId)) {
+      await send(chatId, `No autorizado. Tu chat id es ${chatId}; agregalo a telegram.allowedChatIds para habilitarlo.`);
+      return;
+    }
+    const text = String(message.text ?? message.caption ?? '').trim();
+    if (text.startsWith('/')) {
+      await handleCommand(chatId, text);
+      return;
+    }
+    if (message.voice || message.audio) {
+      await handleVoice(chatId, message.voice ?? message.audio);
+      return;
+    }
+    if (message.photo?.length) {
+      try {
+        const largest = message.photo[message.photo.length - 1];
+        const buffer = await downloadFile(token, largest.file_id);
+        const dataUrl = `data:image/jpeg;base64,${buffer.toString('base64')}`;
+        await run(chatId, text || '(imagen)', [dataUrl]);
+      } catch (error) {
+        await send(chatId, `No pude procesar la imagen: ${error.message}`);
+      }
+      return;
+    }
+    if (text) await run(chatId, text);
+  }
+
+  async function handleCallback(query) {
+    const chatId = String(query.message?.chat.id ?? '');
+    const [kind, a, b] = String(query.data ?? '').split(':');
+    let toast = '';
+
+    if (kind === 'perm') {
+      ctx.approvals.decide(a, b === 'allow');
+      toast = b === 'allow' ? 'Permitido' : 'Denegado';
+    } else if (kind === 'mode') {
+      ctx.store.setSetting('activeMode', resolveMode(a).id);
+      toast = `Modo ${resolveMode(a).label}`;
+    } else if (kind === 'provider') {
+      ctx.store.setSetting('activeProvider', a);
+      const sid = ctx.store.getSetting(sessionKey(chatId));
+      if (sid) ctx.store.touchSession(sid, { provider: a });
+      toast = `Proveedor ${a}`;
+    } else if (kind === 'model') {
+      const id = (modelChoices.get(chatId) ?? [])[Number(a)];
+      if (id) {
+        ctx.store.setSetting('activeModel', id);
+        const sid = ctx.store.getSetting(sessionKey(chatId));
+        if (sid) ctx.store.touchSession(sid, { model: id });
+        toast = `Modelo ${id}`;
+      }
+    } else if (kind === 'menu') {
+      if (a === 'models') await sendModels(chatId);
+      else if (a === 'providers') await sendProviders(chatId);
+      else if (a === 'home') await sendMenu(chatId);
+      else if (a === 'new') {
+        ctx.store.setSetting(sessionKey(chatId), null);
+        await send(chatId, 'Nueva sesión. Mandá tu mensaje.');
+      } else if (a === 'stop') {
+        controllers.get(chatId)?.abort();
+        await send(chatId, 'Cancelando…');
+      }
+      toast = 'ok';
+    }
+
+    await tg(token, 'answerCallbackQuery', { callback_query_id: query.id, text: toast }).catch(() => null);
+    // Solo los permisos cierran su tarjeta; el panel conserva los botones.
+    if (kind === 'perm' && query.message) {
+      await tg(token, 'editMessageReplyMarkup', { chat_id: query.message.chat.id, message_id: query.message.message_id }).catch(() => null);
+    }
+  }
+
+  async function loop() {
+    while (running) {
+      let updates = [];
+      try {
+        updates = await tg(token, 'getUpdates', { offset, timeout: 25, allowed_updates: ['message', 'callback_query'] });
+      } catch (error) {
+        if (error.status === 401 || error.status === 404) {
+          log(`telegram: token inválido (${error.message}); se detiene el bot.`);
+          running = false;
+          return;
+        }
+        await sleep(3000);
+        continue;
+      }
+      for (const update of updates) {
+        offset = update.update_id + 1;
+        if (update.message) handleMessage(update.message).catch((error) => log(`telegram: ${error?.message ?? error}`));
+        else if (update.callback_query) handleCallback(update.callback_query).catch((error) => log(`telegram: ${error?.message ?? error}`));
+      }
+    }
+  }
+
+  loop().catch((error) => log(`telegram: ${error?.message ?? error}`));
+
+  return {
+    id: 'telegram',
+    stop() {
+      running = false;
+      for (const controller of controllers.values()) controller.abort();
+      controllers.clear();
+    },
+    /** Avisa a un chat vinculado sobre un run de otra interfaz (p.ej. la consola). */
+    notify(sessionId, event) {
+      if (ownSessions.has(sessionId)) return;
+      const chatId = ctx.store.getSetting(reverseKey(sessionId));
+      if (!chatId) return;
+      if (event.type === 'done') {
+        send(chatId, `✅ Sesión terminada.\n\n${String(event.data?.content ?? '').slice(0, 3500)}`).catch(() => {});
+      } else if (event.type === 'error') {
+        send(chatId, `✗ Error en la sesión: ${event.data?.message ?? ''}`).catch(() => {});
+      } else if (event.type === 'agent_end') {
+        send(chatId, `🤖 Subagente ${event.data?.status}: ${String(event.data?.content ?? '').slice(0, 1500)}`).catch(() => {});
+      } else if (event.type === 'permission') {
+        const askId = event.data?.askId;
+        if (!askId) return;
+        send(chatId, `⚠ Permiso para ${event.data?.name ?? 'una tool'} (desde la consola)`, {
+          reply_markup: {
+            inline_keyboard: [
+              [
+                { text: 'Permitir', callback_data: `perm:${askId}:allow` },
+                { text: 'Denegar', callback_data: `perm:${askId}:deny` },
+              ],
+            ],
+          },
+        }).catch(() => {});
+      }
+    },
+  };
+}

package/harness/packages/server/src/lib/http.js

@@ -55,9 +55,10 @@ export function openSse(req, res) {
   });
 
   return {
-    event(name, data) {
+    event(name, data, id) {
       if (closed || res.writableEnded) return;
-      res.write(`event: ${name}\ndata: ${JSON.stringify(data ?? {})}\n\n`);
+      const cursor = id === undefined || id === null ? '' : `id: ${id}\n`;
+      res.write(`${cursor}event: ${name}\ndata: ${JSON.stringify(data ?? {})}\n\n`);
     },
     comment(text) {
       if (closed || res.writableEnded) return;

package/harness/packages/server/src/lib/runManager.js

@@ -0,0 +1,102 @@
+// Gestiona los runs activos del server, desacoplados del request HTTP: si el
+// cliente se desconecta (por ejemplo, el celular bloquea la pantalla), el run
+// sigue; cada evento se persiste con un cursor para que un cliente nuevo pueda
+// reconectar y reconstruir el turno en curso.
+
+/**
+ * @param {object} deps
+ * @param {import('../../../core/src/storage/sqlite.js').Store} deps.store
+ */
+export function createRunManager({ store }) {
+  const runs = new Map();
+  const listeners = new Set();
+
+  function persist(run, sessionId, type, data, agentId) {
+    const coalesce =
+      (type === 'text' || type === 'reasoning') &&
+      run?.lastEvent &&
+      run.lastEvent.type === type &&
+      run.lastEvent.agentId === agentId;
+    if (coalesce) {
+      store.updateSessionEvent(run.lastEvent.id, data);
+      return { id: run.lastEvent.id, type, data, agentId };
+    }
+    const id = store.addSessionEvent(sessionId, { agentId, type, data });
+    if (run) run.lastEvent = { id, type, agentId };
+    return { id, type, data, agentId };
+  }
+
+  function emit(sessionId, type, data, { agentId = null } = {}) {
+    const run = runs.get(sessionId) ?? null;
+    const event = persist(run, sessionId, type, data, agentId);
+    if (run) {
+      for (const subscriber of [...run.subscribers]) {
+        try {
+          subscriber(event);
+        } catch {
+          // un suscriptor caido no debe frenar el run
+        }
+      }
+    }
+    for (const listener of [...listeners]) {
+      try {
+        listener(sessionId, event);
+      } catch {
+        // un listener caido no debe frenar el run
+      }
+    }
+    return event;
+  }
+
+  function start(sessionId) {
+    if (runs.has(sessionId)) return null;
+    const controller = new AbortController();
+    const run = { sessionId, controller, subscribers: new Set(), lastEvent: null, startedAt: Date.now() };
+    runs.set(sessionId, run);
+    store.clearSessionEvents(sessionId);
+    return run;
+  }
+
+  function finish(sessionId) {
+    const run = runs.get(sessionId);
+    if (!run) return;
+    run.subscribers.clear();
+    runs.delete(sessionId);
+  }
+
+  function cancel(sessionId) {
+    runs.get(sessionId)?.controller.abort();
+  }
+
+  function cancelAll() {
+    for (const run of runs.values()) run.controller.abort();
+    runs.clear();
+  }
+
+  function isActive(sessionId) {
+    return runs.has(sessionId);
+  }
+
+  function signal(sessionId) {
+    return runs.get(sessionId)?.controller.signal;
+  }
+
+  function subscribe(sessionId, fn) {
+    const run = runs.get(sessionId);
+    if (!run) return () => {};
+    run.subscribers.add(fn);
+    return () => run.subscribers.delete(fn);
+  }
+
+  function activeSessions() {
+    return [...runs.keys()];
+  }
+
+  /** Suscriptor global de todos los runs (usado por los canales). */
+  function subscribeAll(fn) {
+    listeners.add(fn);
+    return () => listeners.delete(fn);
+  }
+
+  return { emit, start, finish, cancel, cancelAll, isActive, signal, subscribe, subscribeAll, activeSessions };
+}