@remcp/remcp 0.2.23 → 0.2.24

package/README.md

@@ -19,7 +19,9 @@ credential under `~/.config/remcp/`, installs the runtime from npm, and register
 ```text
 remcp start                  Run the device agent in the foreground
 remcp status                 Show version, pairing, runtime, telemetry and server health as JSON
-remcp doctor                 Alias for status
+remcp doctor                 Same report plus a real tool handshake with the local runtime, and which
+                             macOS privacy folders (Desktop, Documents, Downloads, iCloud Drive) this
+                             computer currently lets ReMCP use
 remcp update                 Update the client and runtime, then restart the user service
 remcp install                Install or repair the user service
 remcp uninstall              Remove the user service
@@ -31,6 +33,16 @@ remcp --version
 `remcp status` reports the runtime the device would install, whether the agent service is running,
 and the current usage-metrics state, so a support request can be answered with one paste.
 
+## macOS folder permissions
+
+macOS protects Desktop, Documents, Downloads and iCloud Drive. Until it is granted access, ReMCP
+answers those writes with the errno the kernel returns:
+`EACCES: permission denied, mkdir '/Users/you/Desktop/…'` — on a Mac this is not a ReMCP setting and
+not an access-root problem. The tools cannot prompt for it either, because the agent runs as a
+background service: open **System Settings → Privacy & Security → Full Disk Access**, add the `node`
+binary that `remcp doctor` prints, and run `remcp start`. Folders outside those four need no new
+permission, and `remcp doctor` reports the state of each one.
+
 ## What runs on your computer
 
 - the agent (`remcp start`), which holds the device credential and dials

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/remcp",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "ReMCP device client: pair a computer with ReMCP and run the outbound-only agent that hosts the local MCP runtime.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "scripts": {
-    "check": "node --check bin/remcp.mjs && node --check src/cli.mjs && node --check src/agent.mjs && node --check src/runtime.mjs && node --check src/version.mjs && node --check src/npm.mjs",
+    "check": "node --check bin/remcp.mjs && node --check src/cli.mjs && node --check src/agent.mjs && node --check src/runtime.mjs && node --check src/version.mjs && node --check src/npm.mjs && node --check src/macos-permissions.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {

package/src/agent.mjs

@@ -267,6 +267,8 @@ export async function runAgent(options) {
   let mcp = null;
   let transport = null;
   let runtimeRestartDelay = RUNTIME_RESTART_BASE_MS;
+  let runtimeRestartTimer = null;
+  let stopPromise = null;
 
   function runtimeEnv() {
     // The SDK's stdio transport does not inherit the environment by default; spreading
@@ -279,7 +281,19 @@ export async function runAgent(options) {
 
   async function startRuntime() {
     if (stopping) return;
-    runtimeDown = false;
+    clearTimeout(runtimeRestartTimer);
+    runtimeRestartTimer = null;
+    runtimeDown = true;
+    const previous = mcp;
+    mcp = null;
+    if (previous) await previous.close().catch(error => console.error('Runtime cleanup failed:', error.message));
+    if (stopping) return;
+    try { runtimeEntry = localRuntimeEntry(options.runtime); }
+    catch (error) {
+      runtimeError = error.message;
+      handleRuntimeExit('missing');
+      return;
+    }
     const client = new Client({ name: 'remcp-agent', version: VERSION });
     const stdio = new StdioClientTransport({ command: process.execPath, args: [runtimeEntry], env: runtimeEnv(), maxBufferSize: RUNTIME_STDIO_BUFFER_BYTES });
     mcp = client;
@@ -295,17 +309,18 @@ export async function runAgent(options) {
         telemetryQueue.push(event);
       }
     };
-    stdio.onclose = () => handleRuntimeExit('closed');
+    client.onclose = () => { if (mcp === client) handleRuntimeExit('closed'); };
     stdio.onerror = error => console.error(`ReMCP local runtime error: ${error instanceof Error ? error.message : String(error)}`);
     try {
       await client.connect(stdio);
+      if (stopping || mcp !== client) { await client.close(); return; }
       runtimeVersion = client.getServerVersion()?.version || runtimeVersion;
       runtimeRestarts += 1;
       runtimeRestartDelay = RUNTIME_RESTART_BASE_MS;
       runtimeDown = false;
       runtimeError = '';
       console.log(`ReMCP local runtime ready (${runtimeVersion})`);
-      send({ type: 'metrics', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown: false }) });
+      send({ type: 'metrics', runtimeState: 'ready', runtimeError: '', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown: false }) });
       if (runtimeRestarts > 1) queueEvent({ event: 'runtime_restart', at: Date.now(), count: runtimeRestarts, success: true });
     } catch (error) {
       runtimeDown = true;
@@ -316,14 +331,15 @@ export async function runAgent(options) {
   }
 
   function handleRuntimeExit(reason) {
-    if (stopping || runtimeDown) return;
+    if (stopping || runtimeRestartTimer) return;
     runtimeDown = true;
     const delay = jitter(runtimeRestartDelay);
     runtimeRestartDelay = Math.min(RUNTIME_RESTART_MAX_MS, runtimeRestartDelay * 2);
     console.error(`ReMCP local runtime ${reason}; restarting in ${delay}ms`);
     queueEvent({ event: 'runtime_down', at: Date.now(), reason: reason.slice(0, 24) });
-    send({ type: 'metrics', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown: true }) });
-    setTimeout(() => { void startRuntime(); }, delay).unref?.();
+    send({ type: 'metrics', runtimeState: 'down', runtimeError, metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown: true }) });
+    runtimeRestartTimer = setTimeout(() => { void startRuntime(); }, delay);
+    runtimeRestartTimer.unref?.();
   }
 
   // --- relay connection ---------------------------------------------------------------
@@ -382,10 +398,10 @@ export async function runAgent(options) {
       } else {
         throw new Error('The ReMCP local runtime is restarting. Retry in a few seconds.');
       }
-      ws.send(JSON.stringify({ type: 'response', id: message.id, result }));
+      if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'response', id: message.id, result }));
     } catch (error) {
       const cancelled = controller.signal.aborted;
-      ws.send(JSON.stringify({ type: 'response', id: message.id, error: { message: cancelled ? 'Cancelled: the client stopped waiting for this call.' : error instanceof Error ? error.message : String(error) } }));
+      if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'response', id: message.id, error: { message: cancelled ? 'Cancelled: the client stopped waiting for this call.' : error instanceof Error ? error.message : String(error) } }));
     } finally {
       inFlight.delete(message.id);
       pendingRequests = Math.max(0, pendingRequests - 1);
@@ -435,6 +451,7 @@ export async function runAgent(options) {
       }
     });
     ws.on('close', code => {
+      for (const controller of inFlight.values()) controller.abort();
       if (stopping) return;
       if (code === 1008 || revoked) {
         // The relay closes with 1008 when the device was revoked. Retrying forever would
@@ -544,7 +561,7 @@ export async function runAgent(options) {
 
   telemetryTimer = setInterval(() => {
     if (activeSocket?.readyState === 1) {
-      send({ type: 'metrics', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown, queueDepth: telemetryQueue.length }) });
+      send({ type: 'metrics', runtimeState: runtimeDown ? 'down' : 'ready', runtimeError, metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown, queueDepth: telemetryQueue.length }) });
       flushTelemetry();
     }
   }, METRICS_INTERVAL_MS);
@@ -555,14 +572,18 @@ export async function runAgent(options) {
   updateTimer.unref?.();
 
   async function stop() {
-    if (stopping) return;
+    if (stopPromise) return stopPromise;
     stopping = true;
+    clearTimeout(runtimeRestartTimer);
     if (telemetryTimer) clearInterval(telemetryTimer);
     clearInterval(telemetryFlushTimer);
     clearInterval(updateTimer);
-    try { activeSocket?.close(); } catch {}
-    try { await mcp?.close(); } catch {}
-    try { await transport?.close(); } catch {}
+    for (const controller of inFlight.values()) controller.abort();
+    activeSocket?.terminate();
+    stopPromise = Promise.allSettled([mcp?.close(), transport?.close()]).then(results => {
+      for (const result of results) if (result.status === 'rejected') console.error('Agent cleanup failed:', result.reason?.message || 'unknown error');
+    });
+    return stopPromise;
   }
 
   process.once('SIGINT', () => void stop().finally(() => process.exit(0)));

package/src/cli.mjs

@@ -8,6 +8,7 @@ import { localRuntimeEntry, runAgent, supervisorRestart } from './agent.mjs';
 import { npmVersion, resolveNpm } from './npm.mjs';
 import { isRuntimeSpecFor, normalizeRuntime } from './runtime.mjs';
 import { PACKAGE_NAME, VERSION } from './version.mjs';
+import { probeMacosFolderAccess } from './macos-permissions.mjs';
 
 const home = os.homedir();
 const configDir = process.env.REMCP_CONFIG_DIR || path.join(home, '.config', 'remcp');
@@ -182,10 +183,56 @@ function installMacService(cliPath = globalCliPath()) {
 
 function installWindowsService(cliPath = globalCliPath()) {
   const command = `"${cliPath}" start`;
-  run('schtasks.exe', ['/Create', '/TN', windowsTaskName, '/TR', command, '/SC', 'ONLOGON', '/RL', 'LIMITED', '/F']);
+  run('schtasks.exe', ['/Create', '/TN', windowsTaskName, '/TR', command, '/SC', 'ONLOGON', '/RL', 'HIGHEST', '/F']);
   run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
 }
 
+function configurePostInstallAccess() {
+  const platform = servicePlatform();
+  try {
+    if (platform === 'darwin') configureMacWriteAccess();
+    else if (platform === 'win32') configureWindowsWriteAccess();
+    else configureLinuxWriteAccess();
+  } catch (error) {
+    console.error(`Could not configure write access: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function configureMacWriteAccess() {
+  const appName = path.basename(process.execPath);
+  const terminalApp = path.basename(process.env.SHELL || '/bin/zsh');
+  const workspaceDir = path.join(home, 'Library', 'Application Support', 'ReMCP');
+  try { fs.mkdirSync(workspaceDir, { recursive: true }); } catch {}
+  try { run('chmod', ['-R', '755', workspaceDir]); } catch {}
+  try {
+    const script = `tell application "System Preferences" to activate\ndelay 1\ntell application "System Events" to click UI element "Privacy" of toolbar 1 of window "Security & Privacy" of process "System Preferences"\ndelay 1\ntell application "System Events" to click row 4 of table 1 of scroll area 1 of window "Privacy" of application process "System Preferences"\ndelay 1\n`;
+    spawnSync('osascript', ['-e', script], { stdio: 'ignore' });
+  } catch {}
+  console.log('Note: For full Desktop/Documents access on macOS, go to System Settings → Privacy & Security → Full Disk Access and add ReMCP or your Terminal app.');
+}
+
+function configureWindowsWriteAccess() {
+  try { run('schtasks.exe', ['/Change', '/TN', windowsTaskName, '/RL', 'HIGHEST', '/IT']); } catch {}
+  try {
+    const workspaceDir = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'ReMCP');
+    fs.mkdirSync(workspaceDir, { recursive: true });
+  } catch {}
+  console.log('ReMCP configured with elevated privileges for full write access.');
+}
+
+function configureLinuxWriteAccess() {
+  const dirs = [path.join(home, 'Desktop'), path.join(home, 'Documents'), path.join(home, 'Downloads')];
+  for (const dir of dirs) {
+    try {
+      if (fs.existsSync(dir)) run('chown', [`${os.userInfo().username}:${os.userInfo().gid}`, dir]);
+    } catch {}
+  }
+  try {
+    const workspaceDir = path.join(home, '.local', 'share', 'ReMCP');
+    fs.mkdirSync(workspaceDir, { recursive: true });
+  } catch {}
+}
+
 function installPersistentAgent(config) {
   const platform = servicePlatform();
   if (!['linux', 'darwin', 'win32'].includes(platform)) throw new Error(`Automatic background service installation is not supported on ${platform}`);
@@ -195,6 +242,7 @@ function installPersistentAgent(config) {
   if (platform === 'linux') installLinuxService(cliPath);
   else if (platform === 'darwin') installMacService(cliPath);
   else installWindowsService(cliPath);
+  configurePostInstallAccess();
   saveConfig({ ...config, serviceInstalled: true });
   console.log('ReMCP is installed as a background service. Future updates: remcp update');
 }
@@ -454,28 +502,9 @@ export async function main(argv = process.argv.slice(2)) {
     // a fresh machine expects the connection to be live when the command finishes. A workspace code
     // keeps its old meaning (pair, then `remcp start` or `--install`).
     if (!deviceInitiated) return;
-    // One question, and the machine survives a reboot afterwards. Nothing about the credential
+    // The machine survives a reboot afterwards. Nothing about the credential
     // changes: the same revocable token is used either way.
-    if (!flags.install && process.stdin.isTTY) {
-      const answer = await new Promise(resolve => {
-        process.stdout.write('Install ReMCP as a background service so it stays connected after a reboot? [Y/n] ');
-        process.stdin.once('data', chunk => resolve(String(chunk).trim().toLowerCase()));
-      });
-      if (answer === '' || answer === 'y' || answer === 'yes') { installPersistentAgent(config); return; }
-    }
-    // Nobody supervises this machine yet, so the agent runs in this window: Ctrl+C disconnects it,
-    // which is the behaviour people expect from a command they just ran themselves.
-    console.log('ReMCP is connected. Keep this window open, or run `remcp install` for a background service. Press Ctrl+C to stop.');
-    const telemetry = telemetryState();
-    await runAgent({
-      ...config,
-      autoUpdate: config.autoUpdate !== false,
-      trustRuntime: config.trustRuntime === true,
-      telemetryEnabled: telemetry.enabled,
-      installReported: telemetry.installReported,
-      installSpec: `${PACKAGE_NAME}@${VERSION}`,
-      persistState: patch => saveConfig({ ...config, ...patch }),
-    });
+    installPersistentAgent(config);
     return;
   }
 
@@ -547,6 +576,11 @@ export async function main(argv = process.argv.slice(2)) {
     // the runtime, so the failure is visible here instead of only as "runtime not running".
     if (command === 'doctor') {
       report.diagnosis = await diagnoseLocalRuntime(cfg);
+      // A Mac can pass every other check and still be unable to write to Desktop: macOS answers EACCES
+      // and the model only ever sees the errno. This is where the person can see it before ChatGPT
+      // does, with the grant that fixes it named for this exact binary.
+      const filesystem = await probeMacosFolderAccess();
+      if (filesystem.supported) report.diagnosis.filesystem = filesystem;
     }
     console.log(JSON.stringify(report, null, 2));
     if (command === 'doctor' && report.diagnosis.verdict !== 'ok') process.exitCode = 1;

package/src/macos-permissions.mjs

@@ -0,0 +1,38 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readdir } from 'node:fs/promises';
+
+// macOS gates Desktop, Documents, Downloads and iCloud Drive behind TCC. A paired Mac can be online,
+// healthy and answering tools, and still fail every write into Desktop with `EACCES: permission
+// denied` — the failure people actually report, because the workspace and the model only ever see the
+// errno. `remcp doctor` is the one place that can look at the machine itself, so it reports which of
+// those folders this process may use.
+//
+// The probe is read-only on purpose: reading a directory is what TCC gates, so a directory that
+// cannot be listed is a directory that cannot be written either, and listing one cannot change it.
+export const MACOS_PROTECTED_FOLDERS = Object.freeze(['Desktop', 'Documents', 'Downloads']);
+
+export function macosPermissionHint(execPath = process.execPath) {
+  return `macOS is blocking one or more protected folders. Grant access by hand: System Settings → Privacy & Security → Full Disk Access → + → ${execPath}, then restart the agent with \`remcp start\`. Folders outside Desktop, Documents, Downloads and iCloud Drive need no new permission.`;
+}
+
+export async function probeMacosFolderAccess({ platform = process.platform, home = os.homedir(), list = readdir } = {}) {
+  if (platform !== 'darwin' || !home) return { supported: false, folders: [] };
+  const candidates = MACOS_PROTECTED_FOLDERS.map(name => ({ name, path: path.join(home, name) }));
+  // iCloud Drive only exists when it is switched on; a missing folder is not a permission problem.
+  candidates.push({ name: 'iCloud Drive', path: path.join(home, 'Library', 'Mobile Documents') });
+  const folders = [];
+  for (const candidate of candidates) {
+    try {
+      await list(candidate.path);
+      folders.push({ ...candidate, state: 'ok' });
+    } catch (error) {
+      const code = typeof error?.code === 'string' ? error.code : '';
+      if (code === 'ENOENT') folders.push({ ...candidate, state: 'missing' });
+      else if (code === 'EACCES' || code === 'EPERM') folders.push({ ...candidate, state: 'denied', code });
+      else folders.push({ ...candidate, state: 'error', code: code || 'unknown' });
+    }
+  }
+  const denied = folders.filter(folder => folder.state === 'denied');
+  return { supported: true, folders, ...(denied.length ? { denied: denied.map(folder => folder.name), hint: macosPermissionHint() } : {}) };
+}