@danieltmn/tamnora 0.22.0 → 0.23.0

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

@@ -1,933 +1,163 @@
-// 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, que ahora empieza eligiendo
-// proyecto (una carpeta de la raiz configurada en la consola).
-
-import path from 'node:path';
-import { readFile } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import {
-  runAgent,
-  createTools,
-  resolveMode,
-  listProviderModels,
-  PROVIDER_META,
-  sintetizar,
-  MAX_TEXTO,
-  screenshotsDir,
-} from '../core.js';
-import { resolveExistingDir, listSubdirs } from '../workspace.js';
-import {
-  combineToolset,
-  composeAgentMessages,
-  buildUserMessage,
-  resolveProviderFor,
-  toolCallPayload,
-} from '../agentRun.js';
-import { mp3AOgg } from '../ffmpeg.js';
-import { createRulesInjector } from '../rules.js';
-import { resolveTts } from '../ttsSettings.js';
-import { transcribeAudio } from '../transcribe.js';
-
-const API = 'https://api.telegram.org';
-const MAX_PROJECTS = 24;
-
-const RESUME_INSTRUCTION =
-  'Resumí la conversación para la persona: qué se pidió, qué se hizo, decisiones tomadas, archivos o comandos relevantes y el estado actual. Sé claro y conciso, en español, sin markdown pesado.';
-
-const HELP = [
-  'Tamnora Harness — bot',
-  '',
-  '/proyecto [nombre] — elegí el proyecto (sin argumento: lista)',
-  '/new — nueva sesión (vuelve a preguntar el proyecto)',
-  '/resumen — resumen en texto de la conversación',
-  '/audioresumen — el resumen como nota de voz',
-  '/menu — panel con botones (modelo, modo, proveedor)',
-  '/status — proveedor, modelo, modo, proyecto 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)',
-  '/estricto [on|off] — el agente hace solo lo pedido (sin arg: alterna)',
-  '/stop — cancela la respuesta en curso',
-  '/help — esta ayuda',
-  '',
-  'Podés mandar texto, imágenes o notas de voz.',
-].join('\n');
-
-function humanSize(bytes) {
-  const n = Number(bytes) || 0;
-  if (n < 1024) return `${n} B`;
-  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
-  return `${(n / 1024 / 1024).toFixed(1)} MB`;
-}
-
-function oneLine(value, max = 400) {
-  const text = String(value ?? '').replace(/\s+/g, ' ').trim();
-  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
-}
-
-/**
- * Explica en una frase qué va a hacer el agente si se aprueba el permiso, en
- * vez de volcar el JSON crudo (que para `write` mostraba medio archivo).
- */
-export function describePermission(name, args = {}) {
-  const a = args && typeof args === 'object' ? args : {};
-  switch (name) {
-    case 'bash':
-      return { action: 'ejecutar un comando en el proyecto', detail: oneLine(a.command, 700) };
-    case 'write':
-      return {
-        action: `escribir el archivo ${a.path ?? '(sin ruta)'}`,
-        detail: a.content ? `Contenido: ${humanSize(Buffer.byteLength(String(a.content)))}` : '',
-      };
-    case 'edit':
-      return {
-        action: `editar el archivo ${a.path ?? '(sin ruta)'}`,
-        detail: a.oldString ? `Reemplaza: "${oneLine(a.oldString, 100)}"` : '',
-      };
-    case 'git_commit':
-      return { action: 'hacer un commit', detail: oneLine(a.message, 200) };
-    case 'screenshot':
-      return { action: 'sacar una captura de la página', detail: oneLine(a.url, 200) };
-    case 'console_errors':
-      return { action: 'revisar la consola de una página', detail: oneLine(a.url, 200) };
-    case 'fetch_url':
-      return { action: 'consultar una URL', detail: oneLine(a.url, 200) };
-    case 'read':
-      return { action: `leer ${oneLine(a.path, 120) || 'un archivo'}`, detail: '' };
-    default:
-      return { action: `usar la herramienta "${name}"`, detail: oneLine(JSON.stringify(a), 200) };
-  }
-}
-
-function permissionMessage(project, name, args) {
-  const { action, detail } = describePermission(name, args);
-  const lines = [`⚠ [${project}] Permiso: el agente quiere ${action}.`];
-  if (detail) lines.push('', detail);
-  lines.push('', '¿Qué hacemos?');
-  return lines.join('\n');
-}
-
-function permissionKeyboard(askId) {
-  return {
-    inline_keyboard: [
-      [
-        { text: 'Permitir', callback_data: `perm:${askId}:allow` },
-        { text: 'Permitir todo', callback_data: `perm:${askId}:all` },
-      ],
-      [{ text: 'Denegar', callback_data: `perm:${askId}:deny` }],
-    ],
-  };
-}
-
-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());
-}
-
-/** Variante multipart de `tg` (sendVoice/sendAudio llevan el archivo adjunto). */
-async function tgForm(token, method, form) {
-  const res = await fetch(`${API}/bot${token}/${method}`, { method: 'POST', body: form });
-  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;
-}
-
-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 = ['max_rounds', 'no_progress', 'budget'].includes(stopReason);
-  return `${maxed ? '⚠ corte de seguridad' : '✓ terminado'} · ${parts.join(' · ')}`;
-}
-
-/**
- * Arranca el canal de Telegram. Devuelve `{ stop, notify }` o `null` sin token.
- */
-export function startTelegramChannel(
-  ctx,
-  {
-    token,
-    allowedChatIds = [],
-    transcribeModel = 'whisper-1',
-    transcribeProvider = '',
-    notify = {},
-    root = '',
-    log = () => {},
-  } = {}
-) {
-  if (!token) return null;
-  const allowed = new Set(allowedChatIds.map(String));
-  const notifyConfig = {
-    enabled: notify?.enabled === true,
-    done: notify?.done !== false,
-    error: notify?.error !== false,
-    permission: notify?.permission !== false,
-    agent: notify?.agent !== false,
-  };
-  const controllers = new Map();
-  const ownSessions = new Set();
-  const modelChoices = new Map();
-  const projectChoices = new Map();
-  const pendingInputs = new Map();
-  const askSessions = new Map(); // askId -> sessionId, para "Permitir todo"
-  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);
-    }
-  }
-
-  /**
-   * Nota de voz con un texto cualquiera. Con ffmpeg manda OGG/Opus
-   * (`sendVoice`, aparece como nota de voz); sin ffmpeg cae a audio MP3.
-   * Un fallo del TTS no debe romper el run: se loguea y sigue.
-   */
-  async function enviarNotaDeVoz(chatId, texto, { voice, rate, pitch } = {}) {
-    const tts = resolveTts(ctx.app);
-    const frase = String(texto ?? '').trim().slice(0, MAX_TEXTO);
-    if (!frase) return;
-    try {
-      const mp3 = await sintetizar(frase, {
-        voice: voice || tts.voice,
-        rate: rate || tts.rate,
-        pitch: pitch || tts.pitch,
-      });
-      const ogg = await mp3AOgg(mp3);
-      const form = new FormData();
-      form.append('chat_id', chatId);
-      if (ogg) {
-        form.append('voice', new Blob([ogg], { type: 'audio/ogg' }), 'resumen.ogg');
-        await tgForm(token, 'sendVoice', form);
-      } else {
-        form.append('audio', new Blob([mp3], { type: 'audio/mpeg' }), 'resumen.mp3');
-        await tgForm(token, 'sendAudio', form);
-      }
-    } catch (error) {
-      log(`telegram: nota de voz falló: ${error?.message ?? error}`);
-    }
-  }
-
-  /** Manda una imagen (una captura del tool `screenshot`). */
-  async function enviarFoto(chatId, buffer, caption) {
-    try {
-      const form = new FormData();
-      form.append('chat_id', chatId);
-      if (caption) form.append('caption', String(caption).slice(0, 1000));
-      form.append('photo', new Blob([buffer], { type: 'image/png' }), 'captura.png');
-      await tgForm(token, 'sendPhoto', form);
-    } catch (error) {
-      log(`telegram: foto falló: ${error?.message ?? error}`);
-    }
-  }
-
-  /** Entrega una captura guardada en la casa (por nombre, sin path traversal). */
-  async function enviarCaptura(chatId, name, caption) {
-    const safe = String(name ?? '');
-    if (!/^[a-z0-9][a-z0-9-]*\.png$/i.test(safe)) return;
-    let buffer;
-    try {
-      buffer = await readFile(path.join(screenshotsDir(), safe));
-    } catch {
-      return;
-    }
-    await enviarFoto(chatId, buffer, caption);
-  }
-
-  // --- proyectos ------------------------------------------------------------
-
-  /** Carpeta raíz para elegir proyecto: la predeterminada de la consola o el cwd. */
-  function projectRoot() {
-    const stored = ctx.store.getSetting('defaultCwd');
-    const candidate = stored || root || ctx.cwd;
-    try {
-      return resolveExistingDir(candidate);
-    } catch {
-      return ctx.cwd;
-    }
-  }
-
-  function listProjects() {
-    try {
-      return listSubdirs(projectRoot()).map((dir) => ({ name: dir.name, path: dir.path }));
-    } catch {
-      return [];
-    }
-  }
-
-  function projectLabel(session) {
-    const cwd = session?.cwd || '';
-    return cwd ? path.basename(cwd) : 'sin carpeta';
-  }
-
-  /** Un proyecto está habilitado si alguna pestaña abierta de la consola lo usa. */
-  function projectIsOpen(session) {
-    const ids = ctx.presence?.ids?.() ?? [];
-    if (!ids.length) return false;
-    const cwd = session?.cwd || '';
-    return ids.some((id) => {
-      const open = ctx.store.getSession(id);
-      return open && (open.cwd || '') === cwd;
-    });
-  }
-
-  function activeSessionId(chatId) {
-    const id = ctx.store.getSetting(sessionKey(chatId));
-    if (id && ctx.store.getSession(id)) return id;
-    return null;
-  }
-
-  function createSessionForProject(chatId, cwd) {
-    const sessionId = ctx.store.createSession({
-      title: path.basename(cwd) || `Telegram ${chatId}`,
-      provider: ctx.effectiveProviderId(),
-      model: ctx.effectiveModel(),
-      cwd,
-      meta: { telegramChatId: String(chatId) },
-    });
-    ctx.store.setSetting(sessionKey(chatId), sessionId);
-    ctx.store.setSetting(reverseKey(sessionId), String(chatId));
-    return sessionId;
-  }
-
-  function resolveProjectArg(arg) {
-    const value = String(arg ?? '').trim();
-    if (!value) return null;
-    if (/[\\/]/.test(value) || /^[a-zA-Z]:/.test(value)) return value;
-    const projects = listProjects();
-    const exact = projects.find((p) => p.name.toLowerCase() === value.toLowerCase());
-    if (exact) return exact.path;
-    const matches = projects.filter((p) => p.name.toLowerCase().includes(value.toLowerCase()));
-    return matches.length === 1 ? matches[0].path : null;
-  }
-
-  async function sendProjectPicker(chatId, { text } = {}) {
-    const base = projectRoot();
-    const all = listProjects();
-    const shown = all.slice(0, MAX_PROJECTS);
-    projectChoices.set(String(chatId), shown);
-    const rows = shown.map((project, index) => [{ text: project.name, callback_data: `proj:${index}` }]);
-    rows.push([{ text: `📁 usar «${path.basename(base)}»`, callback_data: 'proj:root' }]);
-    const intro = text || '¿En qué proyecto vas a trabajar?';
-    await send(chatId, `${intro}\n\nraíz: ${base}`, { reply_markup: { inline_keyboard: rows } });
-    if (all.length > shown.length) {
-      await send(chatId, `Hay ${all.length} proyectos; mostré ${shown.length}. Para otro, usá /proyecto <nombre>.`);
-    }
-  }
-
-  async function selectProject(chatId, projectPath) {
-    let cwd;
-    try {
-      cwd = resolveExistingDir(projectPath);
-    } catch (error) {
-      return send(chatId, `No pude usar ese proyecto: ${error.message}`);
-    }
-    createSessionForProject(chatId, cwd);
-    const key = String(chatId);
-    const pending = pendingInputs.get(key);
-    pendingInputs.delete(key);
-    await send(chatId, `Proyecto «${path.basename(cwd)}».${pending ? '' : ' Mandá tu mensaje.'}`);
-    if (pending) run(chatId, pending.input, pending.images).catch((error) => log(`telegram: ${error?.message ?? error}`));
-  }
-
-  function transcribe(buffer, filename) {
-    return transcribeAudio(ctx, {
-      buffer,
-      filename,
-      providerId: transcribeProvider || undefined,
-      model: transcribeModel,
-    });
-  }
-
-  /** Resumen de la conversación de una sesión (sin tocar el historial). */
-  async function resumirSesion(sessionId) {
-    const messages = ctx.store.getMessages(sessionId);
-    if (!messages.length) throw new Error('La conversación está vacía.');
-    const session = ctx.store.getSession(sessionId);
-    const providerId = session?.provider || ctx.effectiveProviderId();
-    const model = session?.model || ctx.effectiveModel();
-    if (!model) throw new Error('Falta el modelo.');
-    const transcript = messages
-      .map((m) => `${m.role}: ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`)
-      .join('\n');
-    const { provider, config } = resolveProviderFor(ctx, providerId);
-    const result = await runAgent({
-      provider,
-      config,
-      model,
-      messages: [
-        { role: 'system', content: RESUME_INSTRUCTION },
-        { role: 'user', content: transcript.slice(0, 60000) },
-      ],
-      tools: [],
-    });
-    const summary = result.content?.trim();
-    if (!summary) throw new Error('El modelo no devolvió un resumen.');
-    return { summary };
-  }
-
-  async function run(chatId, input, images = []) {
-    const sessionId = activeSessionId(chatId);
-    if (!sessionId) {
-      pendingInputs.set(String(chatId), { input, images });
-      return sendProjectPicker(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) => {
-      // "Permitir todo" activa el auto-approve de la sesion (compartido con la
-      // consola): a partir de ahi no se vuelve a preguntar.
-      if (ctx.isAutoApprove?.(sessionId)) return true;
-      const askId = randomUUID();
-      askSessions.set(askId, sessionId);
-      await send(chatId, permissionMessage(projectLabel(session), name, args), {
-        reply_markup: permissionKeyboard(askId),
-      });
-      return ctx.approvals.ask(askId, { sessionId, name, args });
-    };
-
-    const local = createTools({
-      root: cwd,
-      enabled: mode.tools ?? undefined,
-      permissions: ctx.config.permissions,
-      yes: false,
-      onAsk,
-      mcp,
-      mcpMode: ctx.effectiveMcpMode(),
-      mcpPinned: ctx.effectiveMcpPinned(),
-    });
-    const exposeAdmin = !mode.tools;
-    const admin = ctx.agentTools;
-    const { definitions, execute } = combineToolset({
-      local,
-      admin,
-      plugins: exposeAdmin ? ctx.plugins : null,
-      exposeAdmin,
-      approve: onAsk,
-    });
-    const { provider, config } = resolveProviderFor(ctx, providerId);
-    const userMessage = buildUserMessage(input, images);
-    const messages = await composeAgentMessages({ ctx, cwd, mode, 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,
-        toolContext: { cwd, sessionId },
-        onLifecycle: createRulesInjector({ cwd, patterns: ctx.config.rules ?? [] }) ?? undefined,
-        redactExtra: ctx.secretExtra?.() ?? [],
-        signal: controller.signal,
-        maxRounds: ctx.effectiveMaxRounds?.() ?? ctx.config.maxRounds,
-        maxTokens: ctx.effectiveMaxTokens?.() ?? 0,
-        maxDurationMs: ctx.effectiveMaxDurationMs?.() ?? 0,
-        maxOutputTokens: ctx.effectiveMaxOutputTokens?.() ?? ctx.config.maxOutputTokens ?? 0,
-        onEvent(event) {
-          if (event.type === 'text') {
-            full = event.full;
-          } else if (event.type === 'tool_call') {
-            activity = `${event.name} ${toolCallPayload(event).summary}`.trim();
-            if (event.name === 'speak') {
-              enviarNotaDeVoz(chatId, event.args?.texto, { voice: event.args?.voice, rate: event.args?.rate, pitch: event.args?.pitch });
-            }
-          } else if (event.type === 'tool_result') {
-            activity = `${event.name} ✓`;
-            if (event.name === 'screenshot' && event.meta?.screenshot?.name) {
-              enviarCaptura(chatId, event.meta.screenshot.name, event.meta.screenshot.url);
-            }
-          } 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 === 'no_progress') {
-          body = '⚠ El agente se quedó repitiendo las mismas herramientas sin avanzar.';
-        } else if (result.stopReason === 'budget') {
-          body = '⚠ El agente alcanzó el presupuesto de tokens/tiempo sin respuesta final.';
-        } else if (result.stopReason === 'max_rounds') {
-          body = `⚠ El agente alcanzó el máximo de rondas (${result.rounds}) sin respuesta final.${
-            toolCalls ? ` Hizo ${toolCalls} herramientas.` : ''
-          }`;
-        } 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 = activeSessionId(chatId);
-    const session = sessionId ? ctx.store.getSession(sessionId) : null;
-    const providerId = session?.provider || ctx.effectiveProviderId();
-    const model = session?.model || ctx.effectiveModel() || '—';
-    const mode = resolveMode(ctx.effectiveMode());
-    const text = [
-      '⚙ Panel',
-      `proyecto: ${session ? projectLabel(session) : '(elegí con /proyecto)'}`,
-      `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: '📁 proyecto', callback_data: 'menu:project' },
-            { text: '🆕 nueva', callback_data: 'menu:new' },
-          ],
-          [{ text: '⏹ detener', callback_data: 'menu:stop' }],
-        ],
-      },
-    });
-  }
-
-  async function sendModels(chatId) {
-    const sessionId = activeSessionId(chatId);
-    const session = sessionId ? ctx.store.getSession(sessionId) : null;
-    const providerId = session?.provider || ctx.effectiveProviderId();
-    const models = await listProviderModels({
-      ...ctx.providerSettings(providerId),
-      apiKey: ctx.apiKeyFor(providerId),
-    }).catch(() => []);
-
-    const current = session?.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 = activeSessionId(chatId);
-    if (cmd === 'start') {
-      if (sessionId) {
-        return send(chatId, `Hola. Proyecto actual: «${projectLabel(ctx.store.getSession(sessionId))}».\n\n${HELP}`);
-      }
-      return sendProjectPicker(chatId, { text: 'Hola. ¿En qué proyecto vas a trabajar?' });
-    }
-    if (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);
-      pendingInputs.delete(String(chatId));
-      return sendProjectPicker(chatId, { text: 'Nueva sesión. ¿En qué proyecto vas a trabajar?' });
-    }
-    if (cmd === 'proyecto' || cmd === 'proyectos' || cmd === 'project') {
-      if (!arg) return sendProjectPicker(chatId);
-      const projectPath = resolveProjectArg(arg);
-      if (!projectPath) {
-        return send(chatId, `No encontré el proyecto "${arg}". Usá /proyecto sin argumento para ver la lista.`);
-      }
-      return selectProject(chatId, projectPath);
-    }
-    if (cmd === 'status') {
-      const session = sessionId ? ctx.store.getSession(sessionId) : null;
-      return send(
-        chatId,
-        `proyecto: ${session ? projectLabel(session) : '—'}\nproveedor: ${session?.provider || ctx.effectiveProviderId()}\nmodelo: ${session?.model || ctx.effectiveModel() || '—'}\nmodo: ${ctx.effectiveMode()}\nsolo lo pedido: ${ctx.store.getSetting('strictScope') === true ? 'sí' : 'no'}\nsesión: ${session?.title || '—'}`
-      );
-    }
-    if (cmd === 'resumen' || cmd === 'resume') {
-      if (!sessionId) return send(chatId, 'No hay una conversación todavía. Elegí un proyecto con /proyecto.');
-      const data = await resumirSesion(sessionId).catch((error) => ({ error: error.message }));
-      if (data.error) return send(chatId, `No pude resumir: ${data.error}`);
-      return send(chatId, `📝 Resumen\n\n${data.summary}`);
-    }
-    if (cmd === 'audioresumen' || cmd === 'audio-resumen') {
-      if (!sessionId) return send(chatId, 'No hay una conversación todavía. Elegí un proyecto con /proyecto.');
-      await send(chatId, '🎧 Preparando el resumen…');
-      const data = await resumirSesion(sessionId).catch((error) => ({ error: error.message }));
-      if (data.error) return send(chatId, `No pude resumir: ${data.error}`);
-      await send(chatId, `📝 Resumen\n\n${data.summary}`);
-      return enviarNotaDeVoz(chatId, data.summary);
-    }
-    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…');
-    }
-    if (cmd === 'estricto' || cmd === 'strict') {
-      const current = ctx.store.getSetting('strictScope') === true;
-      const value = arg ? /^(on|si|sí|1|true)$/i.test(arg) : !current;
-      ctx.store.setSetting('strictScope', value);
-      return send(chatId, `solo lo pedido: ${value ? 'activado' : 'desactivado'}`);
-    }
-    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 deliver(chatId, text);
-    } catch (error) {
-      return send(chatId, `No pude procesar el audio: ${error.message}`);
-    }
-  }
-
-  /** Entrega un mensaje: si no hay proyecto elegido, primero pregunta cuál. */
-  async function deliver(chatId, input, images = []) {
-    if (!activeSessionId(chatId)) {
-      pendingInputs.set(String(chatId), { input, images });
-      return sendProjectPicker(chatId);
-    }
-    return run(chatId, input, images);
-  }
-
-  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 deliver(chatId, text || '(imagen)', [dataUrl]);
-      } catch (error) {
-        await send(chatId, `No pude procesar la imagen: ${error.message}`);
-      }
-      return;
-    }
-    if (text) await deliver(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') {
-      const all = b === 'all';
-      ctx.approvals.decide(a, b === 'allow' || all);
-      const sessionId = askSessions.get(a);
-      if (sessionId) askSessions.delete(a);
-      if (all && sessionId) ctx.setAutoApprove?.(sessionId, true);
-      toast = all ? 'Permitidos todos' : b === 'allow' ? 'Permitido' : 'Denegado';
-    } else if (kind === 'proj') {
-      if (a === 'root') {
-        await selectProject(chatId, projectRoot());
-        toast = 'Proyecto elegido';
-      } else {
-        const choice = (projectChoices.get(chatId) ?? [])[Number(a)];
-        if (choice) {
-          await selectProject(chatId, choice.path);
-          toast = `Proyecto ${choice.name}`;
-        } else {
-          toast = 'Elegí de nuevo';
-        }
-      }
-    } 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 = activeSessionId(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 = activeSessionId(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 === 'project') await sendProjectPicker(chatId, { text: 'Elegí el proyecto:' });
-      else if (a === 'new') {
-        ctx.store.setSetting(sessionKey(chatId), null);
-        pendingInputs.delete(String(chatId));
-        await sendProjectPicker(chatId, { text: 'Nueva sesión. ¿En qué proyecto vas a trabajar?' });
-      } 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}`));
-
-  /** Chats que deben recibir un aviso de una sesión (vínculo explícito o proyecto abierto). */
-  function notifyTargets(sessionId) {
-    const explicit = ctx.store.getSetting(reverseKey(sessionId));
-    if (explicit) return [String(explicit)];
-    if (!notifyConfig.enabled) return [];
-    const session = ctx.store.getSession(sessionId);
-    if (!session || !projectIsOpen(session)) return [];
-    return [...allowed];
-  }
-
-  return {
-    id: 'telegram',
-    stop() {
-      running = false;
-      for (const controller of controllers.values()) controller.abort();
-      controllers.clear();
-    },
-    /** Avisa sobre un run de otra interfaz (la consola), siempre con el proyecto. */
-    notify(sessionId, event) {
-      if (ownSessions.has(sessionId)) return;
-
-      // Las tools `speak` y `screenshot` entregan en vivo a un chat vinculado.
-      if (event.type === 'tool_call') {
-        if (event.data?.name !== 'speak') return;
-        const linked = ctx.store.getSetting(reverseKey(sessionId));
-        if (linked) {
-          enviarNotaDeVoz(linked, event.data?.args?.texto, {
-            voice: event.data?.args?.voice,
-            rate: event.data?.args?.rate,
-            pitch: event.data?.args?.pitch,
-          });
-        }
-        return;
-      }
-      if (event.type === 'tool_result' && event.data?.name === 'screenshot') {
-        const linked = ctx.store.getSetting(reverseKey(sessionId));
-        const shot = event.data?.meta?.screenshot;
-        if (linked && shot?.name) enviarCaptura(linked, shot.name, shot.url);
-        return;
-      }
-
-      const targets = notifyTargets(sessionId);
-      if (!targets.length) return;
-      const session = ctx.store.getSession(sessionId);
-      const project = projectLabel(session);
-
-      if (event.type === 'done' && notifyConfig.done) {
-        const text = `[${project}] ✅ Sesión terminada.\n\n${String(event.data?.content ?? '').slice(0, 3500)}`;
-        for (const chatId of targets) send(chatId, text).catch(() => {});
-      } else if (event.type === 'error' && notifyConfig.error) {
-        const text = `[${project}] ✗ Error en la sesión: ${event.data?.message ?? ''}`;
-        for (const chatId of targets) send(chatId, text).catch(() => {});
-      } else if (event.type === 'agent_end' && notifyConfig.agent) {
-        const text = `[${project}] 🤖 Subagente ${event.data?.status}: ${String(event.data?.content ?? '').slice(0, 1500)}`;
-        for (const chatId of targets) send(chatId, text).catch(() => {});
-      } else if (event.type === 'permission' && notifyConfig.permission) {
-        const askId = event.data?.askId;
-        if (!askId) return;
-        if (event.data?.sessionId) askSessions.set(askId, event.data.sessionId);
-        const text = permissionMessage(project, event.data?.name ?? 'una tool', event.data?.args);
-        for (const chatId of targets) {
-          send(chatId, text, { reply_markup: permissionKeyboard(askId) }).catch(() => {});
-        }
-      }
-    },
-  };
-}
+// 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, que ahora empieza eligiendo
+// proyecto (una carpeta de la raiz configurada en la consola).
+//
+// La logica vive en los modulos de `telegram/`: este ensambla el estado del
+// canal (`T`), corre el polling y maneja los avisos de otros canales.
+
+import { send, tg } from './telegram/api.js';
+import { permissionMessage, permissionKeyboard } from './telegram/permissions.js';
+import { projectIsOpen, projectLabel } from './telegram/projects.js';
+import { enviarCaptura, enviarNotaDeVoz } from './telegram/media.js';
+import { handleCallback, handleMessage } from './telegram/commands.js';
+import { run } from './telegram/run.js';
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export { describePermission, completionFooter } from './telegram/text.js';
+export { getTelegramBotInfo } from './telegram/api.js';
+
+/**
+ * Arranca el canal de Telegram. Devuelve `{ stop, notify }` o `null` sin token.
+ */
+export function startTelegramChannel(
+  ctx,
+  {
+    token,
+    allowedChatIds = [],
+    transcribeModel = 'whisper-1',
+    transcribeProvider = '',
+    notify = {},
+    root = '',
+    log = () => {},
+  } = {}
+) {
+  if (!token) return null;
+  const allowed = new Set(allowedChatIds.map(String));
+  const notifyConfig = {
+    enabled: notify?.enabled === true,
+    done: notify?.done !== false,
+    error: notify?.error !== false,
+    permission: notify?.permission !== false,
+    agent: notify?.agent !== false,
+  };
+
+  // Estado compartido entre los modulos de `telegram/`. Cada funcion recibe `T`
+  // como primer parametro y lee/escribe este estado.
+  const T = {
+    ctx,
+    token,
+    root,
+    log,
+    transcribeModel,
+    transcribeProvider,
+    controllers: new Map(),
+    ownSessions: new Set(),
+    modelChoices: new Map(),
+    projectChoices: new Map(),
+    pendingInputs: new Map(),
+    askSessions: new Map(), // askId -> sessionId, para "Permitir todo"
+    authorized: (chatId) => allowed.size > 0 && allowed.has(String(chatId)),
+    sessionKey: (chatId) => `telegram:chat:${chatId}`,
+    reverseKey: (sessionId) => `telegram:session:${sessionId}`,
+    run,
+  };
+  let running = true;
+  let offset = 0;
+
+  async function loop() {
+    while (running) {
+      let updates = [];
+      try {
+        updates = await tg(T.token, 'getUpdates', {
+          offset,
+          timeout: 25,
+          allowed_updates: ['message', 'callback_query'],
+        });
+      } catch (error) {
+        if (error.status === 401 || error.status === 404) {
+          log(`telegram: token invalido (${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(T, update.message).catch((error) => log(`telegram: ${error?.message ?? error}`));
+        else if (update.callback_query) handleCallback(T, update.callback_query).catch((error) => log(`telegram: ${error?.message ?? error}`));
+      }
+    }
+  }
+
+  loop().catch((error) => log(`telegram: ${error?.message ?? error}`));
+
+  /** Chats que deben recibir un aviso de una sesion (vinculo explicito o proyecto abierto). */
+  function notifyTargets(sessionId) {
+    const explicit = ctx.store.getSetting(T.reverseKey(sessionId));
+    if (explicit) return [String(explicit)];
+    if (!notifyConfig.enabled) return [];
+    const session = ctx.store.getSession(sessionId);
+    if (!session || !projectIsOpen(T, session)) return [];
+    return [...allowed];
+  }
+
+  return {
+    id: 'telegram',
+    stop() {
+      running = false;
+      for (const controller of T.controllers.values()) controller.abort();
+      T.controllers.clear();
+    },
+    /** Avisa sobre un run de otra interfaz (la consola), siempre con el proyecto. */
+    notify(sessionId, event) {
+      if (T.ownSessions.has(sessionId)) return;
+
+      // Las tools `speak` y `screenshot` entregan en vivo a un chat vinculado.
+      if (event.type === 'tool_call') {
+        if (event.data?.name !== 'speak') return;
+        const linked = ctx.store.getSetting(T.reverseKey(sessionId));
+        if (linked) {
+          enviarNotaDeVoz(T, linked, event.data?.args?.texto, {
+            voice: event.data?.args?.voice,
+            rate: event.data?.args?.rate,
+            pitch: event.data?.args?.pitch,
+          });
+        }
+        return;
+      }
+      if (event.type === 'tool_result' && event.data?.name === 'screenshot') {
+        const linked = ctx.store.getSetting(T.reverseKey(sessionId));
+        const shot = event.data?.meta?.screenshot;
+        if (linked && shot?.name) enviarCaptura(T, linked, shot.name, shot.url);
+        return;
+      }
+
+      const targets = notifyTargets(sessionId);
+      if (!targets.length) return;
+      const session = ctx.store.getSession(sessionId);
+      const project = projectLabel(session);
+
+      if (event.type === 'done' && notifyConfig.done) {
+        const text = `[${project}] ✓ Sesión terminada.\n\n${String(event.data?.content ?? '').slice(0, 3500)}`;
+        for (const chatId of targets) send(T, chatId, text).catch(() => {});
+      } else if (event.type === 'error' && notifyConfig.error) {
+        const text = `[${project}] ❌ Error en la sesión: ${event.data?.message ?? ''}`;
+        for (const chatId of targets) send(T, chatId, text).catch(() => {});
+      } else if (event.type === 'agent_end' && notifyConfig.agent) {
+        const text = `[${project}] 🤖 Subagente ${event.data?.status}: ${String(event.data?.content ?? '').slice(0, 1500)}`;
+        for (const chatId of targets) send(T, chatId, text).catch(() => {});
+      } else if (event.type === 'permission' && notifyConfig.permission) {
+        const askId = event.data?.askId;
+        if (!askId) return;
+        if (event.data?.sessionId) T.askSessions.set(askId, event.data.sessionId);
+        const text = permissionMessage(project, event.data?.name ?? 'una tool', event.data?.args);
+        for (const chatId of targets) {
+          send(T, chatId, text, { reply_markup: permissionKeyboard(askId) }).catch(() => {});
+        }
+      }
+    },
+  };
+}