Harden Skills + CLI SFTP workflow

Author: tces1

electron/bridges/aiBridge.cjs

@@ -98,8 +98,13 @@ function buildExternalAgentContextualPrompt({ mode, prompt, chatSessionId, defau
       `${scopeHint}` +
       `${defaultTargetHint}` +
       `Use Skills + CLI instead of the "netcatty-remote-hosts" MCP server for Netcatty session access. ` +
+      `First classify the task: remote command execution tasks go through \`exec\`, while remote file or directory tasks go through \`sftp\`. If the user explicitly says to avoid shell or \`exec\`, do not use \`exec\`. ` +
       `${discoveryHint}` +
       `After choosing a target session ID, call \`${cliCommandPrefix} session --session <id> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\` before executing anything. Do not infer protocol, shell type, device type, or connection readiness from the \`env\` result alone when you are about to run a command. ` +
+      `For remote file operations, use the Netcatty SFTP CLI surface instead of trying to reconstruct SSH credentials or open your own SSH/SFTP connection. Treat file and directory tasks as SFTP tasks by default, not shell tasks. Prefer one-off commands such as \`${cliCommandPrefix} sftp list --session <id> --remote-path <remote-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, \`${cliCommandPrefix} sftp read --session <id> --remote-path <remote-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, \`${cliCommandPrefix} sftp write --session <id> --remote-path <remote-path> --content <text> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, \`${cliCommandPrefix} sftp download --session <id> --remote-path <remote-path> --local-path <local-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, or \`${cliCommandPrefix} sftp upload --session <id> --local-path <local-path> --remote-path <remote-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`. ` +
+      `Keep local and remote path semantics strict: \`--remote-path\` always refers to the remote host, while \`--local-path\` always refers to the local machine running Netcatty. If the user asks to download a file to a local destination such as \`/tmp\`, \`~/Downloads\`, or a desktop path, use \`sftp download\`, not \`sftp read\` or \`sftp write\`. If the user asks to create or modify a file on the remote host, use \`sftp write\` or another remote SFTP operation, not \`sftp download\`. ` +
+      `If you need to create or update a small text file with known content on the remote host, prefer \`${cliCommandPrefix} sftp write ...\` directly. Use \`sftp upload\` only when a real local file already exists and must be transferred to the remote host. Do not create temporary local files just to upload text that could be sent with \`sftp write\`. ` +
+      `Keep SFTP usage one-off and explicit: every \`sftp\` command should include both \`--session <id>\` and \`--chat-session ${chatSessionId || "<chat-session-id>"}\`. Do not open reusable SFTP handles or use \`--sftp <id>\`. ` +
       `Run Netcatty CLI calls strictly one at a time. Do not issue concurrent or background Netcatty CLI commands for the same chat session, and always wait for each call to finish before starting the next one. ` +
       `For simple read-only requests such as hostname, IP address, CPU info, memory info, disk usage, pwd, whoami, uname, or process checks, use the shortest possible path: one \`env\`, one \`session\`, then one \`exec\`. Prefer a single straightforward command over creating helper scripts or multi-step shell orchestration. ` +
       `For those simple read-only requests, do not spend time reading extra files, designing scripts, or narrating a plan unless the first direct command fails or the session metadata shows a special device type. ` +

electron/bridges/mcpServerBridge.cjs

@@ -16,6 +16,7 @@ const { toUnpackedAsarPath } = require("./ai/shellUtils.cjs");
 const { execViaPty, execViaChannel, execViaRawPty } = require("./ai/ptyExec.cjs");
 const { safeSend } = require("./ipcUtils.cjs");
 const { getCliDiscoveryFilePath } = require("../cli/discoveryPath.cjs");
+const sftpBridge = require("./sftpBridge.cjs");
 
 const DEBUG_MCP = process.env.NETCATTY_MCP_DEBUG === "1";
 
@@ -500,6 +501,12 @@ async function handleMessage(socket, line) {
 // Methods that modify remote state — blocked in observer mode
 const WRITE_METHODS = new Set([
   "netcatty/exec",
+  "netcatty/sftp/write",
+  "netcatty/sftp/upload",
+  "netcatty/sftp/mkdir",
+  "netcatty/sftp/delete",
+  "netcatty/sftp/rename",
+  "netcatty/sftp/chmod",
 ]);
 
 /**
@@ -527,27 +534,55 @@ async function dispatch(method, params) {
     return { ok: false, error: "Operation cancelled: the ACP session was stopped." };
   }
 
+  // Scope validation for session-targeted operations
+  if (method !== "netcatty/getContext" && params?.sessionId) {
+    const scopeErr = validateSessionScope(params.sessionId, params?.chatSessionId);
+    if (scopeErr) return { ok: false, error: scopeErr };
+  }
+
   // Confirm mode: request user approval for write operations
   if (permissionMode === "confirm" && WRITE_METHODS.has(method)) {
+    if (!params?.chatSessionId) {
+      return {
+        ok: false,
+        error: 'Operation denied: permission mode is "confirm", but this CLI request is not attached to an AI chat session. Manual CLI write operations are non-interactive; switch Settings → AI → Safety to "autonomous" to allow this action.',
+      };
+    }
     const { chatSessionId, ...toolArgs } = params || {};
     const approved = await requestApprovalFromRenderer(method, toolArgs, chatSessionId);
     if (!approved) {
       return { ok: false, error: "Operation denied by user." };
     }
   }
-
-  // Scope validation for session-targeted operations
-  if (method !== "netcatty/getContext" && params?.sessionId) {
-    const scopeErr = validateSessionScope(params.sessionId, params?.chatSessionId);
-    if (scopeErr) return { ok: false, error: scopeErr };
-  }
   switch (method) {
     case "netcatty/getContext":
       return handleGetContext(params);
     case "netcatty/getStatus":
       return handleGetStatus();
     case "netcatty/exec":
       return handleExec(params);
+    case "netcatty/sftp/list":
+      return handleSftpList(params);
+    case "netcatty/sftp/read":
+      return handleSftpRead(params);
+    case "netcatty/sftp/write":
+      return handleSftpWrite(params);
+    case "netcatty/sftp/download":
+      return handleSftpDownload(params);
+    case "netcatty/sftp/upload":
+      return handleSftpUpload(params);
+    case "netcatty/sftp/mkdir":
+      return handleSftpMkdir(params);
+    case "netcatty/sftp/delete":
+      return handleSftpDelete(params);
+    case "netcatty/sftp/rename":
+      return handleSftpRename(params);
+    case "netcatty/sftp/stat":
+      return handleSftpStat(params);
+    case "netcatty/sftp/chmod":
+      return handleSftpChmod(params);
+    case "netcatty/sftp/home":
+      return handleSftpHome(params);
     case "netcatty/setCancelled":
       return handleSetCancelled(params);
     default:
@@ -656,6 +691,149 @@ function handleSetCancelled(params) {
   };
 }
 
+async function withSessionBackedSftp(params, action, options = {}) {
+  if (!params?.sessionId) throw new Error("sessionId is required");
+  const opened = await sftpBridge.openSftpForSession(null, { sessionId: params.sessionId });
+  const sftpId = opened?.sftpId;
+  if (!sftpId) throw new Error("Failed to open session-backed SFTP handle");
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 0;
+  const operationName = options.operationName || "SFTP operation";
+  let timeoutId = null;
+  let timedOut = false;
+  try {
+    const payload = {
+      ...params,
+      sftpId,
+    };
+    if (!timeoutMs) {
+      return await action(payload);
+    }
+    return await new Promise((resolve, reject) => {
+      let settled = false;
+      const finishResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        if (timeoutId) clearTimeout(timeoutId);
+        resolve(value);
+      };
+      const finishReject = (err) => {
+        if (settled) return;
+        settled = true;
+        if (timeoutId) clearTimeout(timeoutId);
+        reject(err);
+      };
+      timeoutId = setTimeout(async () => {
+        if (settled) return;
+        timedOut = true;
+        try {
+          await sftpBridge.closeSftp(null, { sftpId });
+        } catch {
+          // Ignore close failures during forced timeout cleanup.
+        }
+        finishReject(new Error(`${operationName} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      Promise.resolve()
+        .then(() => action(payload))
+        .then(finishResolve, finishReject);
+    });
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+    if (!timedOut) {
+      try {
+        await sftpBridge.closeSftp(null, { sftpId });
+      } catch {
+        // Ignore close failures for one-off internal SFTP handles.
+      }
+    }
+  }
+}
+
+async function handleSftpList(params) {
+  const entries = await withSessionBackedSftp(params, (payload) => sftpBridge.listSftp(null, payload));
+  return { ok: true, entries };
+}
+
+async function handleSftpRead(params) {
+  if (!params?.path) throw new Error("path is required");
+  const content = await withSessionBackedSftp(params, (payload) => sftpBridge.readSftp(null, payload));
+  return { ok: true, path: params.path, content };
+}
+
+async function handleSftpWrite(params) {
+  if (!params?.path) throw new Error("path is required");
+  if (typeof params?.content !== "string") throw new Error("content is required");
+  await withSessionBackedSftp(
+    params,
+    (payload) => sftpBridge.writeSftp(null, payload),
+    { timeoutMs: commandTimeoutMs, operationName: "SFTP write" },
+  );
+  return { ok: true, path: params.path };
+}
+
+async function handleSftpDownload(params) {
+  if (!params?.remotePath || !params?.localPath) {
+    throw new Error("remotePath and localPath are required");
+  }
+  const result = await withSessionBackedSftp(
+    params,
+    (payload) => sftpBridge.downloadSftpToLocal(null, payload),
+    { timeoutMs: commandTimeoutMs, operationName: "SFTP download" },
+  );
+  return { ok: true, ...result };
+}
+
+async function handleSftpUpload(params) {
+  if (!params?.remotePath || !params?.localPath) {
+    throw new Error("remotePath and localPath are required");
+  }
+  const result = await withSessionBackedSftp(
+    params,
+    (payload) => sftpBridge.uploadLocalToSftp(null, payload),
+    { timeoutMs: commandTimeoutMs, operationName: "SFTP upload" },
+  );
+  return { ok: true, ...result };
+}
+
+async function handleSftpMkdir(params) {
+  if (!params?.path) throw new Error("path is required");
+  await withSessionBackedSftp(params, (payload) => sftpBridge.mkdirSftp(null, payload));
+  return { ok: true, path: params.path };
+}
+
+async function handleSftpDelete(params) {
+  if (!params?.path) throw new Error("path is required");
+  await withSessionBackedSftp(params, (payload) => sftpBridge.deleteSftp(null, payload));
+  return { ok: true, path: params.path };
+}
+
+async function handleSftpRename(params) {
+  if (!params?.oldPath || !params?.newPath) {
+    throw new Error("oldPath and newPath are required");
+  }
+  await withSessionBackedSftp(params, (payload) => sftpBridge.renameSftp(null, payload));
+  return { ok: true, oldPath: params.oldPath, newPath: params.newPath };
+}
+
+async function handleSftpStat(params) {
+  if (!params?.path) throw new Error("path is required");
+  const stat = await withSessionBackedSftp(params, (payload) => sftpBridge.statSftp(null, payload));
+  return { ok: true, stat };
+}
+
+async function handleSftpChmod(params) {
+  if (!params?.path || !params?.mode) throw new Error("path and mode are required");
+  await withSessionBackedSftp(params, (payload) => sftpBridge.chmodSftp(null, payload));
+  return { ok: true, path: params.path, mode: params.mode };
+}
+
+async function handleSftpHome(params) {
+  const result = await withSessionBackedSftp(params, (payload) => sftpBridge.getSftpHomeDir(null, payload));
+  if (!result?.success) {
+    throw new Error(result?.error || "Could not determine home directory");
+  }
+  return { ok: true, homeDir: result.homeDir };
+}
+
 // ── Handler: exec ──
 
 function handleExec(params) {