@danieltmn/tamnora 0.8.0 → 0.9.0

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);

package/harness/packages/server/src/routes/chat.js

@@ -4,12 +4,19 @@ import {
   createTools,
   resolveMode,
   MAX_TOOL_ROUNDS,
-  summarizeToolCall,
-  previewToolResult,
 } from '../lib/core.js';
 import { openSse, readJson, sendJson, sendError } from '../lib/http.js';
 import { workspaceForRequest, resolveExistingDir } from '../lib/workspace.js';
 import { createSubagentTool } from '../lib/tasks.js';
+import {
+  combineToolset,
+  composeAgentMessages,
+  buildUserMessage,
+  resolveProviderFor,
+  toolCallPayload,
+  toolResultPayload,
+} from '../lib/agentRun.js';
+import { fraseInicio, fraseFin, fraseError, createFiltroTools } from '../lib/announcer.js';
 
 /**
  * Emit streaming partials at most once per `ms` window, keeping only the
@@ -57,6 +64,13 @@ export function registerChat(route, ctx) {
     sendJson(res, 200, { ok: true, allow, scope });
   });
 
+  // Lo pendiente, para que un cliente sin stream abierto (el celular mirando
+  // otra sesion) sepa igual que hay un permiso esperando.
+  route('GET', '/api/permissions', ({ res, query }) => {
+    const sessionId = query.get('sessionId') ?? undefined;
+    sendJson(res, 200, { pending: ctx.approvals.list({ sessionId }) });
+  });
+
   route('POST', '/api/sessions/:id/stop', ({ res, params }) => {
     if (!ctx.runs.isActive(params.id)) return sendJson(res, 200, { ok: true, stopped: false });
     ctx.runs.cancel(params.id);
@@ -146,7 +160,14 @@ export function registerChat(route, ctx) {
     const autoApprove = body.yes ?? ctx.yes;
     const asked = new Set();
 
-    ctx.runs.emit(sessionId, 'start', { sessionId, provider: providerId, model, mode: mode.id, cwd: sessionCwd });
+    ctx.runs.emit(sessionId, 'start', {
+      sessionId,
+      provider: providerId,
+      model,
+      mode: mode.id,
+      cwd: sessionCwd,
+      say: fraseInicio(),
+    });
     ctx.runs.emit(sessionId, 'user', { content: input });
 
     let mcp = null;
@@ -165,7 +186,7 @@ export function registerChat(route, ctx) {
           asked.add(askId);
           askMeta.set(askId, { sessionId });
           ctx.runs.emit(sessionId, 'permission', { askId, sessionId, name, args });
-          const allow = await ctx.approvals.ask(askId);
+          const allow = await ctx.approvals.ask(askId, { sessionId, name, args });
           asked.delete(askId);
           askMeta.delete(askId);
           ctx.runs.emit(sessionId, 'permission_resolved', { askId, allow });
@@ -194,45 +215,24 @@ export function registerChat(route, ctx) {
       exclude: admin.definitions.map((d) => d.function.name),
       emit: emitAgent,
     });
-    const definitions = [
-      ...(exposeAdmin ? [...local.definitions, ...admin.definitions] : local.definitions),
-      ...tasks.definitions,
-    ];
-    const execute = (name, args, context) => {
-      if (tasks.handles(name)) return tasks.execute(name, args);
-      if (exposeAdmin && admin.handles(name)) {
-        return admin.execute(name, args, { approve: autoApprove ? async () => true : onAsk });
-      }
-      return local.execute(name, args, context);
-    };
+    const approve = autoApprove ? async () => true : (name, args) => onAsk(name, args);
+    const { definitions, execute } = combineToolset({ local, admin, tasks, exposeAdmin, approve });
 
-    const { provider, config } = ctx.resolveProvider({
-      ...ctx.providerSettings(providerId),
-      apiKey: ctx.apiKeyFor(providerId),
+    const { provider, config } = resolveProviderFor(ctx, providerId, {
       baseUrl: body.baseUrl || ctx.providerSettings(providerId).baseUrl,
     });
 
-    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 userMessage = buildUserMessage(input, images);
 
     const sessionRecord = ctx.store.getSession(sessionId);
-    const goal = sessionRecord?.meta?.goal;
-    const summary = sessionRecord?.meta?.summary;
-    const basePrompt = await ctx.systemPromptFor(sessionCwd);
-    const messages = [
-      { role: 'system', content: mode.systemPrompt ? `${basePrompt}\n\n${mode.systemPrompt}` : basePrompt },
-      ...(goal ? [{ role: 'system', content: `Objetivo de la sesión: ${goal}` }] : []),
-      ...(summary ? [{ role: 'system', content: `Resumen de la conversación anterior:\n${summary}` }] : []),
-      ...history,
+    const messages = await composeAgentMessages({
+      ctx,
+      cwd: sessionCwd,
+      mode,
+      history,
       userMessage,
-    ];
+      sessionRecord,
+    });
     // Persistimos el mensaje del usuario ya: asi sobrevive a un corte y la
     // reconexion puede reconstruir el turno desde el historial.
     ctx.store.addMessage(sessionId, userMessage);
@@ -240,6 +240,7 @@ export function registerChat(route, ctx) {
 
     (async () => {
       const startedAt = Date.now();
+      const filtroTools = createFiltroTools();
       const partials = createPartialThrottle(300, (name, payload) => ctx.runs.emit(sessionId, name, payload));
       try {
         const result = await runAgent({
@@ -275,17 +276,15 @@ export function registerChat(route, ctx) {
               ctx.runs.emit(sessionId, 'tools', { toolCalls: event.toolCalls });
             } else if (event.type === 'tool_call') {
               partials.flush();
-              ctx.runs.emit(sessionId, 'tool_call', {
+              const payload = toolCallPayload(event);
+              ctx.runs.emit(sessionId, 'tool_call', { ...payload, say: filtroTools(event.name, payload.summary) });
+            } else if (event.type === 'tool_result') {
+              partials.flush();
+              ctx.runs.emit(sessionId, 'tool_result', {
                 id: event.id,
                 name: event.name,
-                args: event.args,
-                summary: summarizeToolCall(event.name, event.args),
+                ...toolResultPayload(event),
               });
-            } else if (event.type === 'tool_result') {
-              partials.flush();
-              const { preview, truncated } = previewToolResult(event.name, event.result);
-              const failed = /^Error|^Permiso denegado/i.test(String(event.result));
-              ctx.runs.emit(sessionId, 'tool_result', { id: event.id, name: event.name, preview, truncated, failed });
             } else if (event.type === 'repeat') {
               partials.flush();
               ctx.runs.emit(sessionId, 'repeat', { name: event.name, count: event.count });
@@ -304,7 +303,8 @@ export function registerChat(route, ctx) {
         ctx.store.touchSession(sessionId, { provider: providerId, model, title });
         const toolCalls = newMessages.filter((message) => message.role === 'tool').length;
         const durationMs = Date.now() - startedAt;
-        if (result.stopReason === 'aborted') ctx.runs.emit(sessionId, 'aborted', { durationMs, toolCalls });
+        if (result.stopReason === 'aborted')
+          ctx.runs.emit(sessionId, 'aborted', { durationMs, toolCalls, say: fraseFin({ stopReason: 'aborted' }) });
         else
           ctx.runs.emit(sessionId, 'done', {
             sessionId,
@@ -316,11 +316,12 @@ export function registerChat(route, ctx) {
             tokens: result.usage ?? null,
             toolCalls,
             durationMs,
+            say: fraseFin({ stopReason: result.stopReason, rounds: result.rounds, toolCalls, durationMs }),
           });
       } catch (error) {
         partials.flush();
-        if (error?.name === 'AbortError') ctx.runs.emit(sessionId, 'aborted', {});
-        else ctx.runs.emit(sessionId, 'error', { message: error?.message ?? String(error) });
+        if (error?.name === 'AbortError') ctx.runs.emit(sessionId, 'aborted', { say: fraseFin({ stopReason: 'aborted' }) });
+        else ctx.runs.emit(sessionId, 'error', { message: error?.message ?? String(error), say: fraseError() });
       } finally {
         unsubscribe();
         sse.close();

package/harness/packages/server/src/routes/events.js

@@ -0,0 +1,35 @@
+import { openSse } from '../lib/http.js';
+
+/**
+ * Canal global de eventos: un SSE por pestaña de la consola.
+ *
+ * Sirve para que varias ventanas (o la PC y el celular a la vez) se enteren de
+ * que un run arranco en una sesion, sin tener cada una su propio stream por
+ * sesion abierto.
+ *
+ * Solo van eventos de ciclo de vida y **los permisos**. El detalle del turno
+ * sigue yendo por `/api/sessions/:id/stream`: filtrar es obligatorio, porque
+ * `subscribeAll` ve cada parcial de texto de todos los runs y reenviarlos seria
+ * duplicar el stream por sesion.
+ *
+ * Los permisos van aparte justamente porque son lo unico que, si solo viviera
+ * en el stream, un cliente no suscrito a esa sesion no tendria forma de saber
+ * que esta esperando una decision suya.
+ *
+ * Al conectar se manda `snapshot` con las sesiones que ya estan corriendo y con
+ * los permisos pendientes: es lo que hace el canal auto-sanador. Si el stream se
+ * corta y vuelve, el snapshot le dice al cliente que se quedo a medio camino.
+ */
+const GLOBAL_EVENTS = new Set(['run_start', 'run_end', 'permission', 'permission_resolved']);
+
+export function registerEvents(route, ctx) {
+  route('GET', '/api/events', ({ req, res }) => {
+    const sse = openSse(req, res);
+    const unsubscribe = ctx.runs.subscribeAll((sessionId, event) => {
+      if (!GLOBAL_EVENTS.has(event.type)) return;
+      sse.event(event.type, event.data);
+    });
+    sse.event('snapshot', { active: ctx.runs.activeSessions(), permissions: ctx.approvals.list() });
+    req.on('close', unsubscribe);
+  });
+}

package/harness/packages/server/src/routes/files.js

@@ -3,28 +3,20 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { readJson, sendJson, sendError } from '../lib/http.js';
 import { staticServerChip } from '../lib/core.js';
-import { isLoopback, resolveExistingDir } from '../lib/workspace.js';
+import { isInside, localOk, requireLocal, resolveDirOr400 } from '../lib/workspace.js';
 
 const MAX_PREVIEW = 200 * 1024;
 const IGNORED = new Set(['node_modules', '.git', '.tamnora', '.playwright-mcp', 'dist', '.cache']);
 
-function isInside(root, target) {
-  const rel = path.relative(root, target);
-  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-}
-
 /** Resolve `?root` + `?path` into a confined filesystem target, or send an error. */
-function resolveTarget(req, res, query, fallback) {
-  if (!isLoopback(req.socket.localAddress)) {
-    sendError(res, 403, 'Explorar archivos solo está disponible en conexiones locales.');
-    return null;
-  }
+function resolveTarget(req, res, query, fallback, { allowAnyRoot }) {
   let root;
-  try {
-    root = resolveExistingDir(query.get('root') || fallback);
-  } catch (error) {
-    sendError(res, 400, error.message);
-    return null;
+  if (allowAnyRoot) {
+    root = resolveDirOr400(res, query.get('root'), fallback);
+    if (!root) return null;
+  } else {
+    // Sin conexion local de verdad: root fijo al workspace, se ignora ?root.
+    root = fallback;
   }
   const rel = String(query.get('path') ?? '').replace(/^[/\\]+/, '');
   const target = path.resolve(root, rel);
@@ -39,7 +31,11 @@ const toPosix = (value) => value.split(path.sep).join('/');
 
 export function registerFiles(route, ctx) {
   route('GET', '/api/files', ({ req, res, query }) => {
-    const resolved = resolveTarget(req, res, query, ctx.cwd);
+    const local = localOk(req);
+    if (!local && !ctx.authEnabled) {
+      return sendError(res, 403, 'Explorar archivos solo está disponible en conexiones locales.');
+    }
+    const resolved = resolveTarget(req, res, query, ctx.cwd, { allowAnyRoot: local });
     if (!resolved) return;
 
     let stat;
@@ -87,7 +83,11 @@ export function registerFiles(route, ctx) {
   });
 
   route('GET', '/api/files/content', async ({ req, res, query }) => {
-    const resolved = resolveTarget(req, res, query, ctx.cwd);
+    const local = localOk(req);
+    if (!local && !ctx.authEnabled) {
+      return sendError(res, 403, 'Explorar archivos solo está disponible en conexiones locales.');
+    }
+    const resolved = resolveTarget(req, res, query, ctx.cwd, { allowAnyRoot: local });
     if (!resolved) return;
 
     let stat;
@@ -117,19 +117,15 @@ export function registerFiles(route, ctx) {
   });
 
   route('POST', '/api/files/preview', async ({ req, res }) => {
-    if (!isLoopback(req.socket.localAddress)) {
-      return sendError(res, 403, 'La vista previa solo está disponible en conexiones locales.');
+    if (!requireLocal(req, res, 'La vista previa solo está disponible en conexiones locales.')) {
+      return;
     }
     if (!ctx.procsEnabled) {
       return sendError(res, 403, 'Los procesos están deshabilitados (processes.enabled = false).');
     }
     const body = await readJson(req);
-    let root;
-    try {
-      root = resolveExistingDir(body.root || ctx.cwd);
-    } catch (error) {
-      return sendError(res, 400, error.message);
-    }
+    const root = resolveDirOr400(res, body.root, ctx.cwd);
+    if (!root) return;
     const rel = String(body.path ?? '').replace(/^[/\\]+/, '');
     const target = path.resolve(root, rel);
     if (!isInside(root, target)) return sendError(res, 400, 'La ruta queda fuera del workspace.');