@goodandready/dsh-remote-workspace 0.1.1 → 0.2.0

package/lib/routes.js

@@ -1,41 +1,45 @@
-export function writeJson(res, code, data) {
-  try {
-    res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
-    res.end(JSON.stringify(data));
-  } catch {}
-}
+export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelService, store) {
+  function writeJson(res, statusCode, body) {
+    if (typeof res.setHeader === 'function') {
+      res.setHeader('Content-Type', 'application/json; charset=utf-8');
+      res.statusCode = statusCode;
+    } else if (typeof res.writeHead === 'function') {
+      res.writeHead(statusCode, { 'Content-Type': 'application/json; charset=utf-8' });
+    } else {
+      res.statusCode = statusCode;
+    }
+    res.end(JSON.stringify(body));
+  }
 
-export function readBody(req, maxBytes = 256 * 1024) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    let size = 0;
-    req.on('data', (c) => {
-      size += c.length;
-      if (size > maxBytes) {
-        reject(new Error('Payload too large'));
-        req.destroy();
-        return;
-      }
-      chunks.push(c);
-    });
-    req.on('end', () => {
-      try {
-        const raw = Buffer.concat(chunks).toString('utf8');
-        resolve(raw ? JSON.parse(raw) : {});
-      } catch (err) {
-        reject(new Error('Invalid JSON'));
-      }
+  function readBody(req) {
+    return new Promise((resolve, reject) => {
+      let body = '';
+      req.on('data', (chunk) => { body += chunk.toString(); });
+      req.on('end', () => {
+        try {
+          resolve(body ? JSON.parse(body) : {});
+        } catch (err) {
+          reject(err);
+        }
+      });
+      req.on('error', reject);
     });
-    req.on('error', reject);
-  });
-}
+  }
 
-/** Reject cross-site writes. LAN / reverse-proxy UIs are allowed. */
-export function isTrustedSettingsRequest(request) {
-  return request.headers['sec-fetch-site'] !== 'cross-site';
-}
+  function isTrustedSettingsRequest(req) {
+    const rawAuth = req.headers['authorization'];
+    if (typeof rawAuth === 'string' && rawAuth.startsWith('Bearer ')) return true;
+    const cookieHeader = req.headers['cookie'];
+    if (typeof cookieHeader === 'string' && (cookieHeader.includes('token=') || cookieHeader.includes('dsh_token='))) {
+      return true;
+    }
+    const secFetch = req.headers['sec-fetch-site'];
+    if (secFetch === 'same-origin') return true;
+    const ip = req.socket?.remoteAddress || '';
+    if (ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1') return true;
+    return false;
+  }
 
-export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelService, store) {
   ctx.inject(['webServer'], (sctx) => {
     const webServer = sctx.get ? (sctx.get('webServer') ?? sctx.webServer) : sctx.webServer;
     if (!webServer || typeof webServer.register !== 'function') return;
@@ -46,10 +50,20 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
       path: '/dsh-remote-workspace/state',
       handler: async (req, res) => {
         if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' });
-        const profiles = store.getProfiles();
-        const activeId = store.getActiveId();
-        const tunnels = tunnelService.listActiveTunnels();
-        writeJson(res, 200, { ok: true, profiles, activeId, tunnels });
+        try {
+          const profiles = store.getProfiles();
+          const activeId = store.getActiveId() || (profiles[0]?.id || '');
+          const tunnels = tunnelService.listActiveTunnels();
+          writeJson(res, 200, {
+            ok: true,
+            profiles,
+            activeId,
+            tunnels,
+            vaultProtected: true
+          });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
       }
     }), 'dsh-remote-workspace: /state');
 
@@ -67,7 +81,8 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
           }
           sshService.invalidate(profile.id);
           await store.saveProfile(profile);
-          writeJson(res, 200, { ok: true, profile });
+          const sanitized = store.vault ? store.vault.sanitizeProfile(profile) : profile;
+          writeJson(res, 200, { ok: true, profile: sanitized });
         } catch (err) {
           writeJson(res, 500, { ok: false, error: err.message });
         }
@@ -119,7 +134,10 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
         if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'Forbidden' });
         try {
           const body = await readBody(req);
-          const profile = body.profile || (body.id ? store.getProfile(body.id) : body);
+          let profile = body.profile || (body.id ? store.getProfile(body.id) : body);
+          if (store.vault && profile) {
+            profile = store.vault.hydrateProfile(profile);
+          }
           if (!profile || !profile.host) {
             return writeJson(res, 400, { ok: false, error: 'Invalid profile configuration' });
           }
@@ -152,7 +170,7 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
             return writeJson(res, 400, { ok: false, error: 'No profile specified' });
           }
           const remotePath = body.remotePath || '/';
-          const entries = await remoteFs.listDir(profile, remotePath);
+          const entries = await remoteFs.listDir(profile, remotePath, Boolean(body.refresh));
           writeJson(res, 200, { ok: true, currentPath: remotePath, entries });
         } catch (err) {
           writeJson(res, 500, { ok: false, error: err.message });
@@ -160,7 +178,144 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
       }
     }), 'dsh-remote-workspace: /browse');
 
-    // 7. POST /dsh-remote-workspace/sync
+    // 7. POST /dsh-remote-workspace/file/view
+    sctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/dsh-remote-workspace/file/view',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' });
+        if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'Forbidden' });
+        try {
+          const { profileId, filePath } = await readBody(req);
+          const profile = (profileId ? store.getProfile(profileId) : null) || store.getActiveProfile();
+          if (!profile) return writeJson(res, 404, { ok: false, error: 'Profile not found' });
+          if (!filePath) return writeJson(res, 400, { ok: false, error: 'filePath required' });
+
+          const stat = await remoteFs.stat(profile, filePath);
+          if (stat.size > 1024 * 512) {
+            return writeJson(res, 400, { ok: false, error: `File too large for preview (${Math.round(stat.size / 1024)} KB). Max 512 KB.` });
+          }
+
+          const content = await remoteFs.readFile(profile, filePath, 'utf8');
+          writeJson(res, 200, { ok: true, filePath, content, size: stat.size, mtime: stat.mtime });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      }
+    }), 'dsh-remote-workspace: /file/view');
+
+    // 8. POST /dsh-remote-workspace/file/save
+    sctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/dsh-remote-workspace/file/save',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' });
+        if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'Forbidden' });
+        try {
+          const { profileId, filePath, content } = await readBody(req);
+          const profile = (profileId ? store.getProfile(profileId) : null) || store.getActiveProfile();
+          if (!profile) return writeJson(res, 404, { ok: false, error: 'Profile not found' });
+          if (!filePath || content === undefined) return writeJson(res, 400, { ok: false, error: 'filePath and content required' });
+
+          const result = await remoteFs.writeFile(profile, filePath, content, 'utf8');
+          writeJson(res, 200, { ok: true, ...result });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      }
+    }), 'dsh-remote-workspace: /file/save');
+
+    // 9. POST /dsh-remote-workspace/terminal/create
+    sctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/dsh-remote-workspace/terminal/create',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' });
+        if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'Forbidden' });
+        try {
+          const { profileId, cols, rows } = await readBody(req);
+          const profile = (profileId ? store.getProfile(profileId) : null) || store.getActiveProfile();
+          if (!profile) return writeJson(res, 404, { ok: false, error: 'Profile not found' });
+
+          const session = await sshService.createTerminalSession(profile, { cols, rows });
+          writeJson(res, 200, { ok: true, sessionId: session.id });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      }
+    }), 'dsh-remote-workspace: /terminal/create');
+
+    // 10. POST /dsh-remote-workspace/terminal/input
+    sctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/dsh-remote-workspace/terminal/input',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' });
+        if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'Forbidden' });
+        try {
+          const { sessionId, data } = await readBody(req);
+          const session = sshService.getTerminalSession(sessionId);
+          if (!session) return writeJson(res, 404, { ok: false, error: 'Terminal session not found' });
+          session.write(data || '');
+          writeJson(res, 200, { ok: true });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      }
+    }), 'dsh-remote-workspace: /terminal/input');
+
+    // 11. GET /dsh-remote-workspace/terminal/stream (SSE)
+    sctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/dsh-remote-workspace/terminal/stream',
+      handler: async (req, res) => {
+        const url = new URL(req.url, 'http://localhost');
+        const sessionId = url.searchParams.get('sessionId');
+        const session = sshService.getTerminalSession(sessionId);
+        if (!session) return writeJson(res, 404, { ok: false, error: 'Terminal session not found' });
+
+        if (typeof res.writeHead === 'function') {
+          res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            'Connection': 'keep-alive'
+          });
+        }
+
+        // Send historical buffer
+        for (const chunk of session.buffer) {
+          res.write(`data: ${JSON.stringify({ chunk })}\n\n`);
+        }
+
+        const listener = (chunk) => {
+          res.write(`data: ${JSON.stringify({ chunk })}\n\n`);
+        };
+        session.subscribers.add(listener);
+
+        req.on('close', () => {
+          session.subscribers.delete(listener);
+        });
+      }
+    }), 'dsh-remote-workspace: /terminal/stream');
+
+    // 12. POST /dsh-remote-workspace/terminal/close
+    sctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/dsh-remote-workspace/terminal/close',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' });
+        if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'Forbidden' });
+        try {
+          const { sessionId } = await readBody(req);
+          const ok = sshService.closeTerminalSession(sessionId);
+          writeJson(res, 200, { ok });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      }
+    }), 'dsh-remote-workspace: /terminal/close');
+
+    // 13. POST /dsh-remote-workspace/sync
     sctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/dsh-remote-workspace/sync',
@@ -168,14 +323,14 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
         if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' });
         if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'Forbidden' });
         try {
-          const { profileId, direction } = await readBody(req);
+          const { profileId, direction, force } = await readBody(req);
           const profile = (profileId ? store.getProfile(profileId) : null) || store.getActiveProfile();
           if (!profile) return writeJson(res, 404, { ok: false, error: 'Profile not found' });
           if (!profile.remoteWorkspace || !profile.localMirrorPath) {
             return writeJson(res, 400, { ok: false, error: 'Both remoteWorkspace and localMirrorPath must be configured' });
           }
           const resSync = direction === 'push'
-            ? await mirrorSync.push(profile, profile.localMirrorPath, profile.remoteWorkspace)
+            ? await mirrorSync.push(profile, profile.localMirrorPath, profile.remoteWorkspace, Boolean(force))
             : await mirrorSync.pull(profile, profile.remoteWorkspace, profile.localMirrorPath);
           writeJson(res, 200, { ok: resSync.success, ...resSync });
         } catch (err) {
@@ -184,7 +339,7 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
       }
     }), 'dsh-remote-workspace: /sync');
 
-    // 8. POST /dsh-remote-workspace/tunnels/start
+    // 14. POST /dsh-remote-workspace/tunnels/start
     sctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/dsh-remote-workspace/tunnels/start',
@@ -208,7 +363,7 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
       }
     }), 'dsh-remote-workspace: /tunnels/start');
 
-    // 9. POST /dsh-remote-workspace/tunnels/stop
+    // 15. POST /dsh-remote-workspace/tunnels/stop
     sctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/dsh-remote-workspace/tunnels/stop',
@@ -225,5 +380,19 @@ export function registerApiRoutes(ctx, sshService, remoteFs, mirrorSync, tunnelS
         }
       }
     }), 'dsh-remote-workspace: /tunnels/stop');
+
+    // 16. GET /dsh-remote-workspace/tunnels/telemetry
+    sctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/dsh-remote-workspace/tunnels/telemetry',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' });
+        try {
+          writeJson(res, 200, { ok: true, tunnels: tunnelService.listActiveTunnels() });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      }
+    }), 'dsh-remote-workspace: /tunnels/telemetry');
   });
 }

package/lib/ssh-service.js

@@ -3,13 +3,33 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
+/**
+ * Utility to strip ANSI escape sequences from terminal output for clean LLM ingestion
+ */
+export function stripAnsi(str) {
+  if (!str) return '';
+  // Match standard ANSI escape codes, OSC sequences, and CSI codes
+  return str.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '');
+}
+
 export class SshService {
-  constructor(ctx) {
+  /**
+   * @param {any} ctx
+   * @param {import('./vault-service.js').VaultService} [vaultService]
+   */
+  constructor(ctx, vaultService = null) {
     this.ctx = ctx;
+    this.vaultService = vaultService;
     /** @type {Map<string, Client>} */
     this.connections = new Map();
     /** @type {Map<string, any>} */
     this.sftpSessions = new Map();
+    /** @type {Map<string, any>} */
+    this.terminalSessions = new Map();
+  }
+
+  setVaultService(vault) {
+    this.vaultService = vault;
   }
 
   /**
@@ -34,15 +54,21 @@ export class SshService {
   }
 
   /**
-   * Connect to remote machine with pooling and keep-alive
+   * Connect to remote machine with pooling, keep-alive, and auto-reconnect
    */
-  async getConnection(profile) {
+  async getConnection(rawProfile) {
+    const profile = this.vaultService ? this.vaultService.hydrateProfile(rawProfile) : rawProfile;
     const connId = profile.id;
+
     const existing = this.connections.get(connId);
     if (existing && existing._sock && !existing._sock.destroyed) {
       return existing;
     }
 
+    // Clean any broken reference
+    this.connections.delete(connId);
+    this.sftpSessions.delete(connId);
+
     return new Promise((resolve, reject) => {
       const conn = new Client();
       const connConfig = {
@@ -94,7 +120,6 @@ export class SshService {
    * Test connection and measure ping / detect OS
    */
   async testConnection(profile) {
-    // Invalidate any existing connection for this profile id to ensure fresh credentials are used
     if (profile.id) {
       this.disconnect(profile.id);
     }
@@ -130,7 +155,7 @@ export class SshService {
   }
 
   /**
-   * Obtain active SFTP wrapper
+   * Obtain active SFTP wrapper with connection reuse
    */
   async getSftp(profile) {
     const connId = profile.id;
@@ -148,34 +173,153 @@ export class SshService {
   }
 
   /**
-   * Execute command on remote host
+   * Execute command on remote host with PTY, streaming, timeout, and ANSI sanitization
+   * @param {any} profile
+   * @param {string} command
+   * @param {string|object} [optionsOrCwd] - cwd string or options object
+   * @param {function} [legacyOnData]
    */
-  async exec(profile, command, cwd, onData) {
+  async exec(profile, command, optionsOrCwd = null, legacyOnData = null) {
+    let cwd = null;
+    let onData = legacyOnData;
+    let pty = false;
+    let timeoutMs = 0;
+    let cleanAnsi = false;
+
+    if (typeof optionsOrCwd === 'string') {
+      cwd = optionsOrCwd;
+    } else if (optionsOrCwd && typeof optionsOrCwd === 'object') {
+      cwd = optionsOrCwd.cwd || null;
+      onData = optionsOrCwd.onData || legacyOnData;
+      pty = Boolean(optionsOrCwd.pty);
+      timeoutMs = optionsOrCwd.timeout ? optionsOrCwd.timeout * 1000 : 0;
+      cleanAnsi = Boolean(optionsOrCwd.cleanAnsi);
+    }
+
     const conn = await this.getConnection(profile);
     const shellCmd = cwd ? `cd ${JSON.stringify(cwd)} && ${command}` : command;
 
+    const execOptions = {};
+    if (pty) {
+      execOptions.pty = {
+        rows: typeof pty === 'object' ? (pty.rows || 24) : 24,
+        cols: typeof pty === 'object' ? (pty.cols || 80) : 80,
+        term: typeof pty === 'object' ? (pty.term || 'xterm-256color') : 'xterm-256color'
+      };
+    }
+
     return new Promise((resolve, reject) => {
-      conn.exec(shellCmd, (err, stream) => {
+      let timer = null;
+
+      conn.exec(shellCmd, execOptions, (err, stream) => {
         if (err) return reject(err);
         let stdout = '';
         let stderr = '';
+
+        if (timeoutMs > 0) {
+          timer = setTimeout(() => {
+            try {
+              stream.signal('SIGTERM');
+              stream.close();
+            } catch (_) {}
+            const errTimeout = new Error(`Command timed out after ${timeoutMs / 1000}s: ${command}`);
+            errTimeout.code = 'ETIMEDOUT';
+            errTimeout.stdout = cleanAnsi ? stripAnsi(stdout) : stdout;
+            errTimeout.stderr = cleanAnsi ? stripAnsi(stderr) : stderr;
+            reject(errTimeout);
+          }, timeoutMs);
+        }
+
         stream.on('data', (data) => {
           const str = data.toString();
           stdout += str;
           if (onData) onData({ type: 'stdout', data: str });
         });
-        stream.stderr.on('data', (data) => {
+
+        stream.stderr?.on('data', (data) => {
           const str = data.toString();
           stderr += str;
           if (onData) onData({ type: 'stderr', data: str });
         });
+
         stream.on('close', (code, signal) => {
-          resolve({ code: code ?? 0, signal, stdout, stderr });
+          if (timer) clearTimeout(timer);
+          resolve({
+            code: code ?? 0,
+            signal,
+            stdout: cleanAnsi ? stripAnsi(stdout) : stdout,
+            stderr: cleanAnsi ? stripAnsi(stderr) : stderr
+          });
+        });
+      });
+    });
+  }
+
+  /**
+   * Create an interactive PTY terminal session for Web UI
+   */
+  async createTerminalSession(profile, options = {}) {
+    const conn = await this.getConnection(profile);
+    const cols = options.cols || 80;
+    const rows = options.rows || 24;
+    const term = options.term || 'xterm-256color';
+    const sessionId = `term_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    return new Promise((resolve, reject) => {
+      conn.shell({ term, cols, rows }, (err, stream) => {
+        if (err) return reject(err);
+
+        const session = {
+          id: sessionId,
+          profileId: profile.id,
+          stream,
+          createdAt: Date.now(),
+          buffer: [],
+          subscribers: new Set(),
+          write(data) {
+            try { stream.write(data); } catch (_) {}
+          },
+          resize(c, r) {
+            try { stream.setWindow(r, c, 0, 0); } catch (_) {}
+          },
+          close() {
+            try { stream.end(); } catch (_) {}
+          }
+        };
+
+        stream.on('data', (d) => {
+          const chunk = d.toString('utf8');
+          session.buffer.push(chunk);
+          if (session.buffer.length > 500) session.buffer.shift();
+          for (const sub of session.subscribers) {
+            try { sub(chunk); } catch (_) {}
+          }
+        });
+
+        stream.on('close', () => {
+          this.terminalSessions.delete(sessionId);
         });
+
+        this.terminalSessions.set(sessionId, session);
+        resolve(session);
       });
     });
   }
 
+  getTerminalSession(sessionId) {
+    return this.terminalSessions.get(sessionId);
+  }
+
+  closeTerminalSession(sessionId) {
+    const session = this.terminalSessions.get(sessionId);
+    if (session) {
+      session.close();
+      this.terminalSessions.delete(sessionId);
+      return true;
+    }
+    return false;
+  }
+
   invalidate(profileId) {
     this.disconnect(profileId);
   }
@@ -195,5 +339,9 @@ export class SshService {
     }
     this.connections.clear();
     this.sftpSessions.clear();
+    for (const [id, term] of this.terminalSessions.entries()) {
+      try { term.close(); } catch (_) {}
+    }
+    this.terminalSessions.clear();
   }
 }

package/lib/tools.js

@@ -11,21 +11,34 @@ export function registerRemoteTools(ctx, sshService, remoteFs, mirrorSync, tunne
   // 1. remote_exec
   ctx.tools.register({
     name: 'remote_exec',
-    description: 'Execute bash/shell command on the active remote workspace host',
+    description: 'Execute bash/shell command on the active remote workspace host with timeout and ANSI cleaning',
     parameters: {
       command: { type: 'string', required: true, description: 'Command line to execute on remote server' },
-      cwd: { type: 'string', description: 'Working directory on remote server (defaults to remote workspace)' }
+      cwd: { type: 'string', description: 'Working directory on remote server (defaults to remote workspace)' },
+      timeout: { type: 'number', description: 'Execution timeout in seconds (default 60s, 0 to disable)' },
+      pty: { type: 'boolean', description: 'Allocate pseudo-terminal for colored or interactive outputs' },
+      cleanAnsi: { type: 'boolean', description: 'Strip ANSI escape codes from output for clean LLM context (default true)' }
     },
     output: genericOutput,
     async execute(args) {
       const profile = getActiveProfile();
       if (!profile) throw new Error('No active remote workspace profile selected');
       const dir = args.cwd || profile.remoteWorkspace;
-      const res = await sshService.exec(profile, args.command, dir);
+      const timeout = args.timeout !== undefined ? args.timeout : 60;
+      const cleanAnsi = args.cleanAnsi !== undefined ? args.cleanAnsi : true;
+
+      const res = await sshService.exec(profile, args.command, {
+        cwd: dir,
+        timeout,
+        pty: Boolean(args.pty),
+        cleanAnsi
+      });
+
       return {
         exitCode: res.code,
         stdout: res.stdout,
-        stderr: res.stderr
+        stderr: res.stderr,
+        signal: res.signal
       };
     }
   });
@@ -33,7 +46,7 @@ export function registerRemoteTools(ctx, sshService, remoteFs, mirrorSync, tunne
   // 2. remote_fs
   ctx.tools.register({
     name: 'remote_fs',
-    description: 'Perform file operations (read, write, stat, list, mkdir, remove) on remote workspace',
+    description: 'Perform file operations (read, write, stat, list, mkdir, remove) on remote workspace with caching',
     parameters: {
       action: {
         type: 'string',
@@ -42,13 +55,14 @@ export function registerRemoteTools(ctx, sshService, remoteFs, mirrorSync, tunne
       },
       path: { type: 'string', required: true, description: 'Absolute or workspace-relative remote path' },
       content: { type: 'string', description: 'Content for write action' },
-      recursive: { type: 'boolean', description: 'Recursive flag for remove action' }
+      recursive: { type: 'boolean', description: 'Recursive flag for remove action' },
+      bypassCache: { type: 'boolean', description: 'Bypass in-memory cache for fresh results' }
     },
     output: genericOutput,
     async execute(args) {
       const profile = getActiveProfile();
       if (!profile) throw new Error('No active remote workspace profile selected');
-      const { action, path: targetPath, content, recursive } = args;
+      const { action, path: targetPath, content, recursive, bypassCache } = args;
 
       switch (action) {
         case 'read': {
@@ -61,10 +75,10 @@ export function registerRemoteTools(ctx, sshService, remoteFs, mirrorSync, tunne
           return res;
         }
         case 'stat': {
-          return await remoteFs.stat(profile, targetPath);
+          return await remoteFs.stat(profile, targetPath, Boolean(bypassCache));
         }
         case 'list': {
-          const entries = await remoteFs.listDir(profile, targetPath);
+          const entries = await remoteFs.listDir(profile, targetPath, Boolean(bypassCache));
           return { entries };
         }
         case 'mkdir': {
@@ -82,7 +96,7 @@ export function registerRemoteTools(ctx, sshService, remoteFs, mirrorSync, tunne
   // 3. remote_sync
   ctx.tools.register({
     name: 'remote_sync',
-    description: 'Perform 3-way conflict-aware synchronization between local mirror and remote server',
+    description: 'Perform fast 3-way delta synchronization between local mirror and remote server',
     parameters: {
       direction: { type: 'string', required: true, description: 'pull (remote -> local) or push (local -> remote)' },
       force: { type: 'boolean', description: 'Overwrite conflicts if true (use with caution)' },
@@ -107,7 +121,7 @@ export function registerRemoteTools(ctx, sshService, remoteFs, mirrorSync, tunne
   // 4. remote_tunnel
   ctx.tools.register({
     name: 'remote_tunnel',
-    description: 'Manage SSH port forwarding tunnels (start, stop, list)',
+    description: 'Manage SSH port forwarding tunnels (start, stop, list) with telemetry metrics',
     parameters: {
       action: { type: 'string', required: true, description: 'start, stop, or list' },
       localPort: { type: 'number', description: 'Local listening port' },