@remcp/runtime 0.2.22 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "First-party ReMCP local device runtime: file, search, terminal and process tools over MCP for computers paired with ReMCP.",
   "type": "module",
   "license": "MIT",

package/src/invoke.mjs

@@ -1,4 +1,5 @@
 import { toolHandlers } from './catalog.mjs';
+import { describeFilesystemFailure } from './permissions.mjs';
 import { recordEvent } from './telemetry.mjs';
 import { ToolError, text } from './util.mjs';
 
@@ -29,6 +30,7 @@ export async function invokeTool(name, args = {}, extra = {}) {
   } catch (error) {
     recordEvent('tool_call', { tool: definition.name, durationMs: performance.now() - started, success: false, errorKind: errorKind(error) });
     if (error instanceof ToolError) return text(error.message, true);
-    return text(`Tool ${name} failed: ${error instanceof Error ? error.message : String(error)}`, true);
+    // A filesystem error arrives with a bare errno; the explanation is what the person can act on.
+    return text(`Tool ${name} failed: ${describeFilesystemFailure(error, { path: error?.path })}`, true);
   }
 }

package/src/permissions.mjs

@@ -0,0 +1,69 @@
+import os from 'node:os';
+import path from 'node:path';
+
+// macOS protects Desktop, Documents, Downloads, iCloud Drive and external volumes behind TCC (the
+// privacy layer that used to be callable "Full Disk Access"). A process without the grant gets a bare
+// `EACCES: permission denied, mkdir '/Users/ada/Desktop/notes'` from the kernel, which tells the person
+// nothing they can act on. ReMCP usually runs as a background service, and a background service cannot
+// show the prompt macOS shows an app, so the grant has to be made by hand:
+//     System Settings → Privacy & Security → Full Disk Access → + → the binary that runs the tools
+// These helpers turn those errnos into that instruction. They never widen access — they explain it.
+const MACOS_HOME_FOLDERS = Object.freeze(['Desktop', 'Documents', 'Downloads']);
+const PERMISSION_CODES = new Set(['EACCES', 'EPERM']);
+
+// The protected location a path belongs to ("~/Desktop", "iCloud Drive", "an external volume"), or
+// null when macOS does not treat that path as protected. Pure and injectable so it can be tested on
+// any platform.
+export function macosProtectedLocation(target, { platform = process.platform, home = os.homedir() } = {}) {
+  if (platform !== 'darwin') return null;
+  const value = typeof target === 'string' ? target.trim() : '';
+  if (!value) return null;
+  const resolved = path.resolve(value);
+  if (resolved === '/Volumes' || resolved.startsWith(`/Volumes${path.sep}`)) return 'an external or network volume';
+  // The kernel reports the absolute path, so a folder can be recognised even when it belongs to
+  // another account: every /Users/<name>/Desktop is somebody's Desktop, and it is protected for the
+  // process that is asking, whatever this runtime's own home directory is.
+  const segments = resolved.split(path.sep);
+  const relative = home ? path.relative(path.resolve(home), resolved) : '';
+  const insideHome = relative && !relative.startsWith('..') && !path.isAbsolute(relative);
+  const candidate = insideHome ? relative.split(path.sep) : segments[0] === '' && segments[1] === 'Users' ? segments.slice(3) : null;
+  if (!candidate?.length) return null;
+  const [first, second] = candidate;
+  if (MACOS_HOME_FOLDERS.includes(first)) return `~/${first}`;
+  if (first === 'Library' && second === 'Mobile Documents') return 'iCloud Drive';
+  return null;
+}
+
+// What the person should do about this failure, or null when the error is not a filesystem permission
+// problem this module has better words for.
+export function filesystemErrorExplanation(error, options = {}) {
+  const {
+    // Node puts the failing path on the error itself, so a caller that forgets to pass one still gets
+    // the right sentence; an explicit path wins because some callers catch a re-thrown error.
+    path: target = error?.path,
+    platform = process.platform,
+    home = os.homedir(),
+    execPath = process.execPath,
+  } = options;
+  const code = typeof error?.code === 'string' ? error.code : '';
+  const where = typeof target === 'string' && target.trim() ? target.trim() : 'that path';
+  if (code === 'ENOSPC') return 'The disk is full (ENOSPC). Free some space or write to another volume.';
+  if (code === 'EROFS') return `${where} is on a read-only file system (EROFS). Write somewhere else, or remount it read-write.`;
+  if (!PERMISSION_CODES.has(code)) return null;
+  const protectedLocation = macosProtectedLocation(target, { platform, home });
+  if (protectedLocation) {
+    return `macOS protects ${protectedLocation} (${code}), and ReMCP runs as a background service, which cannot show the permission prompt. Grant it by hand: System Settings → Privacy & Security → Full Disk Access → + → ${execPath}, then restart the agent with \`remcp start\`. A folder outside Desktop, Documents, Downloads and iCloud Drive needs no new permission.`;
+  }
+  if (platform === 'darwin') {
+    return `macOS denied access to ${where} (${code}). Check the ownership and permissions of that folder, or add ${execPath} to System Settings → Privacy & Security → Full Disk Access and restart the agent with \`remcp start\`.`;
+  }
+  return `The operating system denied access to ${where} (${code}). Check that this user owns the folder and its parents, or choose another path.`;
+}
+
+// One line for the tool result: the original errno first (so a log or an engineer still sees exactly
+// what the kernel said), then what to do about it.
+export function describeFilesystemFailure(error, options = {}) {
+  const message = error instanceof Error ? error.message : String(error);
+  const explanation = filesystemErrorExplanation(error, options);
+  return explanation ? `${message} ${explanation}` : message;
+}

package/src/tools/files.mjs

@@ -8,6 +8,7 @@ import { pipeline } from 'node:stream/promises';
 import { liveConfig, runtimeConfig } from '../config.mjs';
 import { documentKind, readDocxText, readPdfText } from '../documents.mjs';
 import { diffStats, unifiedDiff } from '../diff.mjs';
+import { describeFilesystemFailure } from '../permissions.mjs';
 import { applyHunks, parseUnifiedDiff } from '../patch.mjs';
 import { countEvent, recordEvent } from '../telemetry.mjs';
 import { clampInteger, decodeText, displayPath, fail, globToRegExp, image, looksBinary, multi, pageLines, resolveSafePath, splitLines, text } from '../util.mjs';
@@ -135,7 +136,7 @@ export async function readMultipleFilesTool(args) {
     try {
       absolute = await resolveSafePath(entry, 'paths[]');
     } catch (error) {
-      sections.push(`${String(entry)}: error - ${error instanceof Error ? error.message : String(error)}`);
+      sections.push(`${String(entry)}: error - ${describeFilesystemFailure(error, { path: error?.path })}`);
       continue;
     }
     try {
@@ -146,7 +147,7 @@ export async function readMultipleFilesTool(args) {
       const suffix = lines.length > limit ? `\n… ${lines.length - limit} more lines truncated` : '';
       sections.push(`${displayPath(absolute)}:\n${slice.join('\n')}${suffix}`);
     } catch (error) {
-      sections.push(`${displayPath(absolute)}: error - ${error instanceof Error ? error.message : String(error)}`);
+      sections.push(`${displayPath(absolute)}: error - ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   return text(sections.join('\n\n'));
@@ -555,7 +556,7 @@ export async function readFilesTool(args) {
       sections.push(`===== ${displayPath(file)} (${lines.length} lines${encoding === 'utf8' ? '' : `, ${encoding}`}) =====\n${slice.join('\n')}${suffix}`);
     } catch (error) {
       skipped += 1;
-      sections.push(`===== ${displayPath(file)} =====\n(skipped: ${error instanceof Error ? error.message : String(error)})`);
+      sections.push(`===== ${displayPath(file)} =====\n(skipped: ${describeFilesystemFailure(error, { path: error?.path })})`);
     }
   }
   const notes = [];
@@ -588,7 +589,7 @@ export async function writeFilesTool(args) {
       await writeFile(absolute, content, entry.mode === 'append' ? { encoding: 'utf8', flag: 'a' } : 'utf8');
       results.push(`${entry.mode === 'append' ? 'appended' : 'wrote'} ${displayPath(absolute)} (${bytes} bytes)`);
     } catch (error) {
-      results.push(`failed ${target}: ${error instanceof Error ? error.message : String(error)}`);
+      results.push(`failed ${target}: ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   countEvent('bytesWritten', totalBytes);
@@ -631,7 +632,7 @@ export async function deletePathsTool(args) {
       deleted += 1;
       results.push(`deleted ${displayPath(absolute)}`);
     } catch (error) {
-      results.push(`failed ${entry}: ${error instanceof Error ? error.message : String(error)}`);
+      results.push(`failed ${entry}: ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   return text(`${deleted}/${paths.length} path(s) deleted\n${results.join('\n')}`, deleted !== paths.length);
@@ -660,7 +661,7 @@ export async function copyPathsTool(args) {
       copied += 1;
       results.push(`copied ${displayPath(source)} → ${displayPath(destination)}`);
     } catch (error) {
-      results.push(`failed ${entry?.source ?? '?'}: ${error instanceof Error ? error.message : String(error)}`);
+      results.push(`failed ${entry?.source ?? '?'}: ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   return text(`${copied}/${pairs.length} path(s) copied\n${results.join('\n')}`, copied !== pairs.length);
@@ -693,7 +694,7 @@ export async function movePathsTool(args) {
       moved += 1;
       results.push(`moved ${displayPath(source)} → ${displayPath(destination)}`);
     } catch (error) {
-      results.push(`failed ${entry?.source ?? '?'}: ${error instanceof Error ? error.message : String(error)}`);
+      results.push(`failed ${entry?.source ?? '?'}: ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   return text(`${moved}/${pairs.length} path(s) moved\n${results.join('\n')}`, moved !== pairs.length);
@@ -732,7 +733,7 @@ export async function applyPatchTool(args) {
       results.push(`${dryRun ? 'would patch' : 'patched'} ${displayPath(absolute)} · ${applied.length}/${file.hunks.length} hunk(s), +${stats.added}/-${stats.removed} lines${fuzzy ? `, ${fuzzy} with fuzz` : ''}${failed.length ? `, ${failed.length} hunk(s) did not match` : ''}`);
       if (dryRun) results.push(unifiedDiff(original, updated, { oldLabel: displayPath(absolute), newLabel: 'after' }));
     } catch (error) {
-      results.push(`failed ${target}: ${error instanceof Error ? error.message : String(error)}`);
+      results.push(`failed ${target}: ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   const failedCount = results.filter(line => line.startsWith('failed')).length;
@@ -773,7 +774,7 @@ export async function setPermissionsTool(args) {
       changed += 1;
     } catch (error) {
       // One protected file must not abort a recursive change; the caller gets the full picture.
-      failures.push(`${displayPath(target)}: ${error instanceof Error ? error.message : String(error)}`);
+      failures.push(`${displayPath(target)}: ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   const summary = `Set mode ${raw}${uid !== null || gid !== null ? ` (uid ${uid ?? '-'} gid ${gid ?? '-'})` : ''} on ${changed} path(s) starting at ${displayPath(absolute)}.`;
@@ -793,7 +794,7 @@ export async function createDirectoryTool(args) {
       await mkdir(absolute, { recursive: true });
       created.push(displayPath(absolute));
     } catch (error) {
-      failed.push(`${entry}: ${error instanceof Error ? error.message : String(error)}`);
+      failed.push(`${entry}: ${describeFilesystemFailure(error, { path: error?.path })}`);
     }
   }
   const header = `${created.length} director${created.length === 1 ? 'y' : 'ies'} ready`;