@jian-ai/remote-control 0.8.2 → 0.8.3

package/README.md

@@ -29,6 +29,16 @@ npx @jian-ai/remote-control@latest update
 Reads `~/.config/jian-remote` (no token, machine id, or gateway flags), installs a compatible
 build, and restarts the worker service.
 
+## Version and service control
+
+```sh
+jian-remote version          # also --version / -V
+jian-remote stop | start | restart
+```
+
+`start` / `restart` stop any previous worker before launching one process (LaunchAgent,
+systemd --user, or Task Scheduler).
+
 ## Configure
 
 Change the stored gateway URL and/or worker token without a full reinstall (restarts the
@@ -41,7 +51,9 @@ jian-remote configure --gateway https://gateway.example --token WORKER_TOKEN
 
 ## Compatibility
 
-Worker and gateway must share the same major.minor. See [docs/remote.md](../../docs/remote.md).
+Connected workers self-update to the gateway’s release (gateway `/update` script, npm
+fallback) including major.minor skew, then restart the OS service. Manual `install` /
+`update` still gate on `/health`. See [docs/remote.md](../../docs/remote.md).
 
 Requires Node.js 24+. Computer Use works on macOS, Linux (X11 + `xdotool`/`ffmpeg`), and
 Windows. Published builds include a prebuilt macOS `computer-helper` (no Xcode on the worker
@@ -49,6 +61,6 @@ Mac) plus Linux/Windows helper scripts. From source on a Mac, run `macos/build-h
 let the worker compile with `swiftc` when Command Line Tools are installed.
 
 On macOS the LaunchAgent uses `ProcessType=Interactive` and an idle `caffeinate` so the worker
-keeps polling while the screen is locked (App Nap must not freeze timers). Computer Use still
-needs an unlocked session; a locked Mac stays **online** with `uiState: locked`. See
-[docs/remote.md](../../docs/remote.md).
+keeps polling while the screen is locked (App Nap must not freeze timers). A locked Mac stays
+**online** (`uiState: locked` is advisory): the worker wakes the display and attempts
+Computer Use; it does not soft-refuse. See [docs/remote.md](../../docs/remote.md).

package/bin/computer-macos.mjs

@@ -20,8 +20,11 @@ const HELPER_NAME = 'computer-helper';
 const UI_STATE_CACHE_MS = 5_000;
 export const MAC_UI_STATES = Object.freeze(['unlocked', 'locked', 'display_asleep', 'unknown']);
 
-const LOCKED_COMPUTER_MESSAGE =
-  'Mac is locked — unlock the screen to use Computer Use. Shell and file tools may still work while the worker is online.';
+const LOCKED_SCREENSHOT_NOTE =
+  'Note: Mac session reports locked — image may be the lock screen (or black if the display stayed asleep). Desktop apps behind loginwindow are often not visible.';
+
+const LOCKED_ACTION_HINT =
+  ' Mac session reports locked; if this failed, unlock or keep the display awake (post-login lock ≠ FileVault loginwindow).';
 
 let cachedUiState = { at: 0, state: 'unknown' };
 let workerIdleCaffeinate = null;
@@ -386,39 +389,48 @@ export class MacComputerSession {
       };
     }
 
-    const uiBlocked = assertComputerUiAllowed();
-    if (uiBlocked) {
-      return {
-        exitCode: 1,
-        stdout: '',
-        stderr: uiBlocked,
-        timedOut: false,
-        computer: { ok: false, error: uiBlocked },
-      };
-    }
+    // Wake display when locked/asleep, then always attempt — never soft-block on uiState.
+    const uiPrep = prepareComputerUi();
 
     if (action === 'screenshot') {
-      await this.ensure();
-      const shot = capturePrimaryScreenshotBase64();
-      if (!this.geometry) throw new Error('Display geometry unavailable.');
-      this.shotGeometry = {
-        ...this.geometry,
-        widthPx: shot.widthPx,
-        heightPx: shot.heightPx,
-      };
-      this.bumpIdle();
-      return {
-        exitCode: 0,
-        stdout: shot.base64,
-        stderr: '',
-        timedOut: false,
-        computer: {
-          ok: true,
+      try {
+        await this.ensure();
+        const shot = capturePrimaryScreenshotBase64();
+        if (!this.geometry) throw new Error('Display geometry unavailable.');
+        this.shotGeometry = {
+          ...this.geometry,
           widthPx: shot.widthPx,
           heightPx: shot.heightPx,
-          scale: scaleFromGeometry(this.shotGeometry),
-        },
-      };
+        };
+        this.bumpIdle();
+        const stderr = uiPrep.sessionLocked ? LOCKED_SCREENSHOT_NOTE : '';
+        return {
+          exitCode: 0,
+          stdout: shot.base64,
+          stderr,
+          timedOut: false,
+          computer: {
+            ok: true,
+            widthPx: shot.widthPx,
+            heightPx: shot.heightPx,
+            scale: scaleFromGeometry(this.shotGeometry),
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const hint = uiPrep.sessionLocked ? LOCKED_ACTION_HINT : '';
+        const tcc = /accessib|not permitted|not authorized|Screen Recording/i.test(message)
+          ? ' Jian Remote needs Screen Recording (and Accessibility for input) in System Settings.'
+          : '';
+        const full = `${message}${tcc}${hint}`.trim();
+        return {
+          exitCode: 1,
+          stdout: '',
+          stderr: full,
+          timedOut: false,
+          computer: { ok: false, error: full },
+        };
+      }
     }
 
     await this.ensure();
@@ -479,12 +491,14 @@ export class MacComputerSession {
       const tcc = /accessib|not permitted|not authorized/i.test(message)
         ? ' Jian Remote needs Accessibility (and Screen Recording for screenshots) in System Settings.'
         : '';
+      const hint = uiPrep.sessionLocked ? LOCKED_ACTION_HINT : '';
+      const full = `${message}${tcc}${hint}`.trim();
       return {
         exitCode: 1,
         stdout: '',
-        stderr: `${message}${tcc}`,
+        stderr: full,
         timedOut: false,
-        computer: { ok: false, error: `${message}${tcc}`.trim() },
+        computer: { ok: false, error: full },
       };
     }
 
@@ -661,15 +675,14 @@ export function wakeMacDisplay(seconds = 3) {
 }
 
 /**
- * Before GUI actions: wake a sleeping display; refuse clearly when the session is locked.
- * Returns null when Computer Use may proceed, or an English error string.
+ * Wake the display when locked or asleep (lock often coincides with display sleep).
+ * Never soft-blocks: callers always attempt the OS API next.
  */
-export function assertComputerUiAllowed() {
+export function prepareComputerUi() {
   let state = probeMacUiState({ force: true });
-  if (state === 'display_asleep' || state === 'unknown') {
+  if (state === 'display_asleep' || state === 'locked' || state === 'unknown') {
     wakeMacDisplay(3);
     state = probeMacUiState({ force: true });
   }
-  if (state === 'locked') return LOCKED_COMPUTER_MESSAGE;
-  return null;
+  return { sessionLocked: state === 'locked', state };
 }