@danieltmn/tamnora 0.7.1 → 0.9.0

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

@@ -0,0 +1,92 @@
+// Frases habladas del agente: un resumen corto de lo que esta haciendo, armado
+// por plantillas a partir de los eventos del run (sin llamar al modelo). Se
+// adjuntan como `say` a los eventos del turno (start/tool_call/done) para que
+// la consola las sintetice con el TTS, y las usa Telegram para la nota de voz
+// final. La idea es narrar el progreso, no leer la respuesta entera.
+
+const MAX_FRASE = 200;
+
+/** Recorta una frase al tope, sin cortar una palabra a la mitad. */
+function recortar(frase) {
+  const value = String(frase ?? '').replace(/\s+/g, ' ').trim();
+  if (value.length <= MAX_FRASE) return value;
+  return `${value.slice(0, MAX_FRASE - 1).replace(/\s+\S*$/, '')}…`;
+}
+
+const VERBOS = {
+  read: 'Leyendo',
+  list: 'Explorando',
+  glob: 'Buscando',
+  grep: 'Buscando',
+  write: 'Escribiendo',
+  edit: 'Editando',
+  bash: 'Ejecutando',
+  fetch_url: 'Consultando',
+  git_status: 'Mirando el estado de git',
+  git_diff: 'Mirando los cambios de git',
+  git_log: 'Mirando el historial de git',
+  git_commit: 'Commiteando',
+  task: 'Delegando en un subagente',
+  spawn_agent: 'Delegando en un subagente',
+};
+
+/**
+ * Frase para un tool-call: verbo + resumen de la tool. Devuelve '' para tools
+ * mudas (la consola ya las colapsa por ser ruido de lectura).
+ */
+export function fraseTool(name, summary) {
+  const tool = String(name ?? '');
+  if (tool.startsWith('mcp__')) {
+    const server = tool.split('__')[1] ?? '';
+    return server ? `Usando una herramienta de ${server}` : '';
+  }
+  const verbo = VERBOS[tool];
+  if (!verbo) return '';
+  if (tool === 'git_status' || tool === 'git_diff' || tool === 'git_log' || tool === 'git_commit') {
+    return summary ? `${verbo}: ${summary}` : verbo;
+  }
+  if (!summary) return verbo;
+  return recortar(`${verbo} ${summary}`);
+}
+
+/** Frase de arranque del turno. */
+export function fraseInicio() {
+  return 'Empecé a trabajar en tu pedido.';
+}
+
+/** Frase de cierre: rondas, herramientas y duracion, o el motivo del corte. */
+export function fraseFin({ stopReason, rounds, toolCalls, durationMs } = {}) {
+  const segundos = Math.round((Number(durationMs) || 0) / 1000);
+  const tiempo = segundos >= 1 ? `, ${segundos} segundo${segundos === 1 ? '' : 's'}` : '';
+  if (stopReason === 'aborted') return 'Cancelado.';
+  if (['max_rounds', 'no_progress', 'budget'].includes(stopReason)) {
+    return `Terminé por un corte de seguridad tras ${rounds ?? '?'} ronda${rounds === 1 ? '' : 's'}${tiempo}.`;
+  }
+  const rondas = Number(rounds) || 0;
+  const herramientas = Number(toolCalls) || 0;
+  if (!herramientas) return 'Listo. Respondí sin usar herramientas.';
+  return `Listo. ${rondas} ronda${rondas === 1 ? '' : 's'}, ${herramientas} herramienta${herramientas === 1 ? '' : 's'}${tiempo}.`;
+}
+
+/** Frase para un error del turno. */
+export function fraseError() {
+  return 'Ocurrió un error.';
+}
+
+/**
+ * Filtro con memoria para no hablar cada tool-call: descarta la misma frase
+ * consecutiva y aplica una ventana minima entre frases de tools.
+ */
+export function createFiltroTools({ minGapMs = 20000 } = {}) {
+  let ultima = 0;
+  let ultimaFrase = '';
+  return (name, summary) => {
+    const frase = fraseTool(name, summary);
+    if (!frase || frase === ultimaFrase) return '';
+    const ahora = Date.now();
+    if (ahora - ultima < minGapMs) return '';
+    ultima = ahora;
+    ultimaFrase = frase;
+    return frase;
+  };
+}

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

@@ -4,6 +4,11 @@
  * event; the console answers by POSTing to `/api/permissions/:id`, which calls
  * `decide`. Requests that nobody answers expire to `false` (deny).
  *
+ * `ask` guarda tambien los `meta` de que se pidio. Eso es lo que permite que un
+ * cliente que **no** esta suscrito al stream de la sesion sepa igual que hay un
+ * permiso esperando: sin esto el permiso solo existe dentro del SSE y un celular
+ * sin stream no tiene forma de enterarse.
+ *
  * @param {object} [opts]
  * @param {number} [opts.timeoutMs] - how long to wait before denying
  */
@@ -20,12 +25,16 @@ export function createApprovalBroker({ timeoutMs = 300000 } = {}) {
   }
 
   return {
-    /** Register a pending request; resolves to a boolean decision. */
-    ask(id) {
+    /**
+     * Register a pending request; resolves to a boolean decision.
+     * `meta` (sessionId, name, args...) es opcional y solo sirve para poder
+     * listar lo pendiente.
+     */
+    ask(id, meta = {}) {
       return new Promise((resolve) => {
         const timer = setTimeout(() => settle(id, false), timeoutMs);
         timer.unref?.();
-        pending.set(id, { resolve, timer });
+        pending.set(id, { resolve, timer, requestedAt: Date.now(), ...meta });
       });
     },
 
@@ -44,6 +53,19 @@ export function createApprovalBroker({ timeoutMs = 300000 } = {}) {
       for (const id of [...pending.keys()]) settle(id, false);
     },
 
+    /**
+     * Lo que sigue esperando, para que cualquier cliente pueda mostrarlo sin
+     * depender de tener un stream abierto. `sessionId` filtra por sesion.
+     */
+    list({ sessionId } = {}) {
+      const items = [];
+      for (const [askId, entry] of pending) {
+        if (sessionId !== undefined && entry.sessionId !== sessionId) continue;
+        items.push({ askId, sessionId: entry.sessionId ?? null, name: entry.name ?? '', args: entry.args ?? {}, requestedAt: entry.requestedAt });
+      }
+      return items.sort((a, b) => a.requestedAt - b.requestedAt);
+    },
+
     get pending() {
       return pending.size;
     },

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

@@ -3,8 +3,18 @@
 // 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 { runAgent, createTools, resolveMode, listProviderModels, PROVIDER_META, sintetizar, MAX_TEXTO } from '../core.js';
 import { resolveExistingDir } from '../workspace.js';
+import {
+  combineToolset,
+  composeAgentMessages,
+  buildUserMessage,
+  resolveProviderFor,
+  toolCallPayload,
+} from '../agentRun.js';
+import { fraseFin } from '../announcer.js';
+import { mp3AOgg } from '../ffmpeg.js';
+import { resolveTts } from '../ttsSettings.js';
 
 const API = 'https://api.telegram.org';
 
@@ -61,6 +71,23 @@ async function downloadFile(token, fileId) {
   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 = [];
@@ -115,6 +142,39 @@ export function startTelegramChannel(
     }
   }
 
+  /**
+   * 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 } = {}) {
+    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 });
+      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}`);
+    }
+  }
+
+  /** Resumen hablado del cierre del turno, según los ajustes de voz. */
+  async function sendResumenDeVoz(chatId, texto) {
+    const tts = resolveTts(ctx.app);
+    if (!tts.enabled || tts.announce.end === false) return;
+    await enviarNotaDeVoz(chatId, texto);
+  }
+
   function ensureSession(chatId) {
     const key = sessionKey(chatId);
     let sessionId = ctx.store.getSetting(key);
@@ -205,24 +265,10 @@ export function startTelegramChannel(
     });
     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 { definitions, execute } = combineToolset({ local, admin, 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);
@@ -256,7 +302,10 @@ export function startTelegramChannel(
           if (event.type === 'text') {
             full = event.full;
           } else if (event.type === 'tool_call') {
-            activity = `${event.name} ${summarizeToolCall(event.name, event.args)}`.trim();
+            activity = `${event.name} ${toolCallPayload(event).summary}`.trim();
+            if (event.name === 'speak') {
+              enviarNotaDeVoz(chatId, event.args?.texto, { voice: event.args?.voice, rate: event.args?.rate });
+            }
           } else if (event.type === 'tool_result') {
             activity = `${event.name} ✓`;
           } else {
@@ -290,6 +339,7 @@ export function startTelegramChannel(
       }
       const footer = completionFooter(result.stopReason, result.rounds, toolCalls, durationMs);
       await edit(chatId, message.message_id, `${body}\n\n— ${footer}`);
+      await sendResumenDeVoz(chatId, fraseFin({ stopReason: result.stopReason, rounds: result.rounds, toolCalls, durationMs }));
       ctx.store.addMessages(sessionId, newMessages);
       ctx.store.touchSession(sessionId, { provider: providerId, model });
     } catch (error) {
@@ -527,8 +577,23 @@ export function startTelegramChannel(
       if (!chatId) return;
       if (event.type === 'done') {
         send(chatId, `✅ Sesión terminada.\n\n${String(event.data?.content ?? '').slice(0, 3500)}`).catch(() => {});
+        sendResumenDeVoz(
+          chatId,
+          event.data?.say ??
+            fraseFin({
+              stopReason: event.data?.stopReason,
+              rounds: event.data?.rounds,
+              toolCalls: event.data?.toolCalls,
+              durationMs: event.data?.durationMs,
+            })
+        );
       } else if (event.type === 'error') {
         send(chatId, `✗ Error en la sesión: ${event.data?.message ?? ''}`).catch(() => {});
+      } else if (event.type === 'tool_call' && event.data?.name === 'speak') {
+        enviarNotaDeVoz(chatId, event.data?.args?.texto, {
+          voice: event.data?.args?.voice,
+          rate: event.data?.args?.rate,
+        });
       } 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') {

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

@@ -0,0 +1,48 @@
+// Conversion MP3 -> OGG/Opus para las notas de voz de Telegram (sendVoice
+// exige OGG con Opus). Telegram acepta MP3 solo como audio normal, asi que sin
+// ffmpeg caemos a ese formato. Se detecta una sola vez por proceso.
+
+import { spawn } from 'node:child_process';
+
+let disponible = null;
+
+/** `true` si hay un ffmpeg ejecutable en el PATH (se cachea). */
+export function ffmpegDisponible() {
+  if (disponible === null) {
+    disponible = new Promise((resolve) => {
+      const hijo = spawn('ffmpeg', ['-version'], { stdio: 'ignore', windowsHide: true });
+      hijo.on('error', () => resolve(false));
+      hijo.on('close', (code) => resolve(code === 0));
+    });
+  }
+  return disponible;
+}
+
+/**
+ * Convierte un buffer de MP3 a OGG/Opus por stdin/stdout.
+ * Devuelve el buffer o `null` si no hay ffmpeg o la conversion falla.
+ */
+export async function mp3AOgg(mp3) {
+  if (!Buffer.isBuffer(mp3) || !mp3.length) return null;
+  if (!(await ffmpegDisponible())) return null;
+  return new Promise((resolve) => {
+    const hijo = spawn(
+      'ffmpeg',
+      ['-hide_banner', '-loglevel', 'error', '-i', 'pipe:0', '-c:a', 'libopus', '-b:a', '32k', '-f', 'ogg', 'pipe:1'],
+      { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true }
+    );
+    const chunks = [];
+    let fallo = false;
+    hijo.stdout.on('data', (chunk) => chunks.push(chunk));
+    hijo.on('error', () => {
+      fallo = true;
+      resolve(null);
+    });
+    hijo.on('close', (code) => {
+      if (fallo) return;
+      resolve(code === 0 && chunks.length ? Buffer.concat(chunks) : null);
+    });
+    hijo.stdin.on('error', () => {});
+    hijo.stdin.end(mp3);
+  });
+}

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

@@ -1,30 +1,15 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
-import { DEFAULT_PROCESS_ALLOW } from './core.js';
+import { DEFAULT_PROCESS_ALLOW, killPidTree } from './core.js';
 
 const MAX_LOG_LINES = 400;
 
 function killTree(child) {
   if (!child || child.killed) return;
-  const pid = child.pid;
+  killPidTree(child.pid);
   try {
-    if (process.platform === 'win32' && pid) {
-      spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true });
-    } else {
-      if (pid) {
-        try {
-          process.kill(-pid, 'SIGTERM');
-        } catch {
-          /* sin grupo */
-        }
-      }
-      try {
-        child.kill('SIGTERM');
-      } catch {
-        /* ya murio */
-      }
-    }
+    child.kill('SIGTERM');
   } catch {
     /* ya murio */
   }

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

@@ -38,6 +38,25 @@ export function createRunManager({ store }) {
         }
       }
     }
+    notify(sessionId, type, data, event.id);
+    return event;
+  }
+
+  /**
+   * Ciclo de vida del run hacia los suscriptores globales (`subscribeAll`).
+   *
+   * A diferencia de `emit`, esto NO se persiste: es una notificacion, no parte
+   * del log del run. Persistirla desalinearia el cursor de `?from=` y ademas la
+   * borraria `clearSessionEvents` al empezar el siguiente run. El `id: 0` marca
+   * "esto no viene del log".
+   */
+  function announce(sessionId, phase, extra = {}) {
+    const type = phase === 'start' ? 'run_start' : 'run_end';
+    notify(sessionId, type, { sessionId, ...extra }, 0);
+  }
+
+  function notify(sessionId, type, data, id) {
+    const event = { id, type, data, agentId: null };
     for (const listener of [...listeners]) {
       try {
         listener(sessionId, event);
@@ -45,7 +64,6 @@ export function createRunManager({ store }) {
         // un listener caido no debe frenar el run
       }
     }
-    return event;
   }
 
   function start(sessionId) {
@@ -54,6 +72,7 @@ export function createRunManager({ store }) {
     const run = { sessionId, controller, subscribers: new Set(), lastEvent: null, startedAt: Date.now() };
     runs.set(sessionId, run);
     store.clearSessionEvents(sessionId);
+    announce(sessionId, 'start', { at: run.startedAt });
     return run;
   }
 
@@ -62,6 +81,7 @@ export function createRunManager({ store }) {
     if (!run) return;
     run.subscribers.clear();
     runs.delete(sessionId);
+    announce(sessionId, 'end', { durationMs: Date.now() - run.startedAt });
   }
 
   function cancel(sessionId) {
@@ -69,8 +89,10 @@ export function createRunManager({ store }) {
   }
 
   function cancelAll() {
-    for (const run of runs.values()) run.controller.abort();
+    const active = [...runs.values()];
+    for (const run of active) run.controller.abort();
     runs.clear();
+    for (const run of active) announce(run.sessionId, 'end', { durationMs: Date.now() - run.startedAt, reason: 'shutdown' });
   }
 
   function isActive(sessionId) {

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

@@ -0,0 +1,43 @@
+/**
+ * Vista publica de una sesion, compartida por `/api/sessions` y `/api/state`.
+ *
+ * Vive aparte para que las dos rutas no diverjan: el cliente reconcilia contra
+ * `/api/state` y dibuja el sidebar con esa misma forma, asi que un campo nuevo
+ * tiene que salir de un solo lugar.
+ */
+export function sessionView(session) {
+  return {
+    id: session.id,
+    title: session.title,
+    provider: session.provider,
+    model: session.model,
+    cwd: session.cwd,
+    goal: session.meta?.goal ?? null,
+    hasSummary: Boolean(session.meta?.summary),
+    createdAt: session.created_at,
+    updatedAt: session.updated_at,
+  };
+}
+
+/** La sesion + su estado de vida, tal como la ve el cliente. */
+export function sessionState(session, ctx, awaiting = 0) {
+  return {
+    ...sessionView(session),
+    running: ctx.runs?.isActive(session.id) ?? false,
+    awaiting,
+  };
+}
+
+/**
+ * Cuenta los permisos pendientes por sesion.
+ *
+ * "Trabajando" y "esperandote a vos" son cosas distintas: un run que avanza solo
+ * no necesita tu atencion, un permiso si.
+ */
+export function awaitingBySession(pending) {
+  const counts = new Map();
+  for (const ask of pending) {
+    counts.set(ask.sessionId, (counts.get(ask.sessionId) ?? 0) + 1);
+  }
+  return counts;
+}

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

@@ -3,7 +3,8 @@
 // del subagente se emiten con `agentId` para que la consola los anide, y su
 // resumen final se devuelve como resultado de la tool.
 
-import { runAgent, createTools, resolveMode, summarizeToolCall, previewToolResult } from './core.js';
+import { runAgent, createTools, resolveMode } from './core.js';
+import { toolCallPayload, toolResultPayload } from './agentRun.js';
 
 const SUBAGENT_PROMPT = [
   'Sos un subagente de Tamnora. Ejecutá de forma autónoma la tarea encomendada',
@@ -91,15 +92,9 @@ export function createSubagentTool(ctx, options) {
           if (event.type === 'text') emit('text', { full: event.full, agentId }, agentId);
           else if (event.type === 'reasoning') emit('reasoning', { full: event.full, agentId }, agentId);
           else if (event.type === 'tool_call') {
-            emit(
-              'tool_call',
-              { id: event.id, name: event.name, args: event.args, summary: summarizeToolCall(event.name, event.args), agentId },
-              agentId
-            );
+            emit('tool_call', { ...toolCallPayload(event), agentId }, agentId);
           } else if (event.type === 'tool_result') {
-            const { preview, truncated } = previewToolResult(event.name, event.result);
-            const failed = /^Error|^Permiso denegado/i.test(String(event.result));
-            emit('tool_result', { id: event.id, name: event.name, preview, truncated, failed, agentId }, agentId);
+            emit('tool_result', { id: event.id, name: event.name, ...toolResultPayload(event), agentId }, agentId);
           }
         },
       });

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

@@ -0,0 +1,42 @@
+// Config de voz (TTS) efectiva: lo guardado en app.json (la casa) sobre los
+// defaults. La leen la ruta de ajustes y el canal de Telegram en el momento de
+// hablar, asi un cambio no necesita recargar nada.
+
+import { VOZ_POR_DEFECTO } from './core.js';
+
+export const DEFAULT_TTS = {
+  enabled: false,
+  voice: VOZ_POR_DEFECTO,
+  rate: '+0%',
+  announce: { start: true, tools: true, end: true },
+};
+
+/** Merge de defaults + lo guardado (con `announce` aplanado a booleans). */
+export function resolveTts(app) {
+  const saved = app?.tts && typeof app.tts === 'object' ? app.tts : {};
+  const announce = { ...DEFAULT_TTS.announce, ...(saved.announce ?? {}) };
+  for (const key of ['start', 'tools', 'end']) announce[key] = announce[key] === true;
+  return {
+    ...DEFAULT_TTS,
+    ...saved,
+    announce,
+    enabled: saved.enabled === true,
+    voice: typeof saved.voice === 'string' && saved.voice ? saved.voice : DEFAULT_TTS.voice,
+    rate: typeof saved.rate === 'string' && saved.rate ? saved.rate : DEFAULT_TTS.rate,
+  };
+}
+
+/** Sanitiza un nombre de voz (ej. "es-AR-ElenaNeural"). */
+export function sanearVoz(value, fallback = VOZ_POR_DEFECTO) {
+  const voz = String(value ?? '').trim();
+  return /^[a-zA-Z]{2}-[a-zA-Z]{2}-[a-zA-Z]+$/.test(voz) ? voz : fallback;
+}
+
+/** Sanitiza una velocidad: "+20%", "-15%", "20%" -> "+20%". */
+export function sanearRate(value, fallback = '+0%') {
+  const match = /^([+-]?)(\d+)%$/.exec(String(value ?? '').trim());
+  if (!match) return fallback;
+  const numero = Math.min(100, Number(match[2]));
+  if (numero === 0) return '+0%';
+  return `${match[1] === '-' ? '-' : '+'}${numero}%`;
+}

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

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { sendError } from './http.js';
+import { tunnelState } from './core.js';
 
 /** True for 127.x / ::1 / ::ffff:127.x addresses. */
 export function isLoopback(address) {
@@ -7,6 +9,24 @@ export function isLoopback(address) {
   return addr === '::1' || addr === '0:0:0:0:0:0:0:1' || addr.startsWith('127.') || addr === '::ffff:127.0.0.1';
 }
 
+/**
+ * "Local de verdad": el par TCP es loopback (remoteAddress, no localAddress:
+ * esa es la direccion donde bindea el server, siempre 127.0.0.1) y no hay un
+ * tunel publico activo. Con el tunel abierto las peticiones remotas TAMBIEN
+ * llegan desde loopback (el cliente del tunel corre en la misma maquina), asi
+ * que la ausencia de tunel es parte del check.
+ */
+export function localOk(req) {
+  return isLoopback(req?.socket?.remoteAddress) && !tunnelState();
+}
+
+/** `localOk` o 403. Devuelve true si la request puede seguir. */
+export function requireLocal(req, res, mensaje = 'Solo disponible en conexiones locales.') {
+  if (localOk(req)) return true;
+  sendError(res, 403, tunnelState() ? `${mensaje} Hay un túnel público activo.` : mensaje);
+  return false;
+}
+
 /** Filesystem roots (drive letters on Windows, `/` elsewhere). */
 export function rootDirs() {
   if (process.platform !== 'win32') return ['/'];
@@ -40,6 +60,22 @@ export function resolveExistingDir(input) {
   return target;
 }
 
+/** `resolveExistingDir` con 400 en vez de throw (patron comun en las routes). */
+export function resolveDirOr400(res, raw, fallback) {
+  try {
+    return resolveExistingDir(raw || fallback);
+  } catch (error) {
+    sendError(res, 400, error.message);
+    return null;
+  }
+}
+
+/** True si `target` es `root` o vive dentro de el (sin salirse por `..`). */
+export function isInside(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
 /**
  * Workspace for an HTTP request: the requested `cwd` (loopback-only) or the
  * server's default. Throws on invalid input.
@@ -47,7 +83,7 @@ export function resolveExistingDir(input) {
 export function workspaceForRequest({ req, raw, fallback }) {
   const value = String(raw ?? '').trim();
   if (!value) return fallback;
-  if (!isLoopback(req.socket.localAddress)) {
+  if (!localOk(req)) {
     throw new Error('Cambiar la carpeta de trabajo solo está permitido en conexiones locales.');
   }
   return resolveExistingDir(value);