@kortix/agent-tunnel 0.13.52 → 0.13.54

package/src/agent/agent.ts

@@ -3,17 +3,25 @@ import { hostname, platform, arch, release } from 'os';
 import { buildTunnelWsUrl, trustedCredential, type TunnelConfig } from './config';
 import {
   ACCESS_HOLD_MS,
+  accessCommand,
+  accessView,
+  accessWidens,
+  applyAccess,
   clearAccessRequest,
   decideAccess,
   keepAwakeCommand,
+  nextAccess,
+  parseAccessChange,
   readAccess,
   readAccessRequest,
   wakeDesktopApp,
   writeAccessRequest,
+  type AccessChange,
+  type AccessView,
 } from './access';
 import { agentTunnelHome } from './service-paths';
 import { machineDisplayName, machineId } from './device-auth';
-import { capabilityForMethod } from '../shared/permissions';
+import { capabilityForMethod, normalizeDesktopCall } from '../shared/permissions';
 import { TunnelErrorCode } from '../shared/types';
 import { agentTunnelVersion } from './version';
 import { c } from './terminal';
@@ -100,6 +108,8 @@ export interface TunnelAgentOptions {
 /** The relay pings every 30 s; 75 s of silence means the socket is dead (R1). */
 const LIVENESS_TIMEOUT_MS = 75_000;
 const WATCHDOG_INTERVAL_MS = 5_000;
+/** The macOS permission check runs every 12 watchdog ticks (60 s). */
+const DESKTOP_PROBE_EVERY_TICKS = 12;
 /** A tick that arrives this much later than scheduled means the machine slept. */
 const CLOCK_JUMP_MS = 30_000;
 const REJECTED_RETRY_MS = 5 * 60_000;
@@ -173,6 +183,9 @@ export class TunnelAgent {
   private standbyAttempts = 0;
   private lastRejectedLogAt = 0;
   private sentAccessKey: string | null = null;
+  private desktopPermissions: { accessibility: boolean; screenRecording: boolean } | null = null;
+  private probingDesktop = false;
+  private watchdogTicks = 0;
   private keepAwake: ChildProcess | null = null;
   private keepAwakeFailed = false;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
@@ -282,6 +295,8 @@ export class TunnelAgent {
         capabilities: this.registry.getCapabilityNames(),
         agentVersion: AGENT_VERSION,
         reportsAccess: true,
+        // Serves `tunnel.access.set`: Kortix may change access through this agent.
+        controlsAccess: true,
       });
     });
 
@@ -395,6 +410,7 @@ export class TunnelAgent {
       this.standbyAttempts = 0;
       this.setStatus('online');
       this.reportAccess();
+      void this.probeDesktopPermissions();
       if (this.stableConnectionTimer) clearTimeout(this.stableConnectionTimer);
       this.stableConnectionTimer = setTimeout(() => {
         this.reconnectAttempts = 0;
@@ -456,6 +472,14 @@ export class TunnelAgent {
       return;
     }
 
+    // ── The owner's access change, relayed by Kortix ────────────────
+    // Before the permission guard and the access gate: it must work while
+    // access is off, and it is the owner's own action, not an agent call.
+    if ('id' in msg && msg.id && msg.method === 'tunnel.access.set') {
+      await this.handleAccessChange(msg as JsonRpcRequest);
+      return;
+    }
+
     // ── RPC request dispatch ────────────────────────────────────────
     if ('id' in msg && msg.id) {
       await this.handleRpcRequest(msg as JsonRpcRequest);
@@ -493,7 +517,9 @@ export class TunnelAgent {
   }
 
   private async handleRpcRequest(request: JsonRpcRequest): Promise<void> {
-    const { id, method, params = {} } = request;
+    // An older API may still send `desktop.cua.<tool>`: serve it as `desktop.cua.call`.
+    const { method, params } = normalizeDesktopCall(request.method, request.params ?? {});
+    const { id } = request;
 
     const permissionId = params.permissionId as string | undefined;
     const permission = this.permissionGuard.getPermissionForMethod(permissionId, method);
@@ -522,7 +548,9 @@ export class TunnelAgent {
       this.sendSignedResult(id, result);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      this.sendSignedError(id, -32003, message);
+      const code = (err as { code?: unknown } | null)?.code;
+      // Only a JSON-RPC server code is binding; an exit status or errno is not.
+      this.sendSignedError(id, typeof code === 'number' && code <= -32000 && code >= -32099 ? code : -32003, message);
     }
   }
 
@@ -621,10 +649,12 @@ export class TunnelAgent {
       // Concurrent calls share one pending request: one prompt, one app launch.
       const pending = readAccessRequest(this.home);
       if (pending && Date.now() - Date.parse(pending.requestedAt) < hold) {
-        requestId = pending.id;
+        // A relayed change waiting for the owner stays: if it is allowed, this call runs too.
+        requestId = pending.change ? null : pending.id;
       } else {
         requestId = writeAccessRequest({ capability: capabilityForMethod(method) ?? method, method }, this.home).id;
         wakeDesktopApp(this.home);
+        this.reportAccess();
       }
     } catch {
       // Without a request file nobody can answer; the hold simply runs out.
@@ -641,16 +671,104 @@ export class TunnelAgent {
     return ACCESS_ERRORS.pending;
   }
 
-  /** X2: optional signed notification; relays that do not know it ignore it. */
+  /**
+   * `tunnel.access.set`: Kortix relays the owner's change. A narrowing applies
+   * at once. A widening (`always`, a longer grant) needs the owner on this
+   * machine: it becomes a request the desktop app shows as a native prompt,
+   * and the call waits for the answer. Without the app, the owner runs the
+   * command in a terminal.
+   */
+  private async handleAccessChange(request: JsonRpcRequest): Promise<void> {
+    let change: AccessChange;
+    try {
+      change = parseAccessChange(request.params);
+    } catch (err) {
+      this.sendSignedError(request.id, TunnelErrorCode.LOCAL_ERROR, err instanceof Error ? err.message : String(err));
+      return;
+    }
+    try {
+      const view = await this.changeAccess(change);
+      this.reportAccess();
+      this.sendSignedResult(request.id, view);
+    } catch (err) {
+      this.reportAccess();
+      this.sendSignedError(request.id, TunnelErrorCode.ACCESS_UNCONFIRMED, err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  private async changeAccess(change: AccessChange): Promise<AccessView> {
+    const current = readAccess(this.home);
+    const target = nextAccess(current, change, this.now());
+    if (!accessWidens(current, target, this.now())) return applyAccess(change, this.home, this.now());
+
+    const unconfirmed = (why: string) => new Error(`computer_access_unconfirmed: ${why}`);
+    const asked = writeAccessRequest({ capability: 'access', method: 'tunnel.access.set', change }, this.home);
+    this.reportAccess();
+    if (wakeDesktopApp(this.home) === 'no-app') {
+      clearAccessRequest(asked.id, this.home);
+      throw unconfirmed(`Only the owner can allow more access, on the computer itself. Run ${accessCommand(change)} there.`);
+    }
+    const hold = this.options.accessHoldMs ?? ACCESS_HOLD_MS;
+    const deadline = Date.now() + hold;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, Math.min(100, hold / 4)));
+      // Reached: the owner allowed it (the app ran the command).
+      if (!accessWidens(readAccess(this.home), target, this.now())) {
+        clearAccessRequest(asked.id, this.home);
+        return accessView(this.home, platform(), this.now());
+      }
+      if (readAccessRequest(this.home)?.id !== asked.id) throw unconfirmed('The owner declined on the computer.');
+    }
+    clearAccessRequest(asked.id, this.home);
+    throw unconfirmed(`Nobody confirmed on the computer within ${Math.round(hold / 1000)} seconds.`);
+  }
+
+  /**
+   * X2: the machine's own state, signed, whenever it changes: access, keep
+   * awake, the request waiting for the owner, and the macOS permissions as
+   * this process holds them. Kortix shows exactly this; relays that do not
+   * know a field ignore it.
+   */
   private reportAccess(): void {
-    const access = readAccess(this.home);
-    const { mode } = access;
-    // A lapsed grant is no grant: the watchdog reports again when it expires.
-    const grantedUntil = access.grantedUntil && Date.parse(access.grantedUntil) > this.now() ? access.grantedUntil : null;
-    const key = `${mode}|${grantedUntil}`;
-    if (key === this.sentAccessKey || this.status !== 'online') return;
+    if (this.status !== 'online') return;
+    const view = accessView(this.home, platform(), this.now());
+    const params = {
+      mode: view.mode,
+      grantedUntil: view.grantedUntil,
+      deniedUntil: view.deniedUntil,
+      keepAwake: view.keepAwake,
+      keepAwakeSupported: view.keepAwakeSupported,
+      pendingRequest: view.pendingRequest
+        ? { capability: view.pendingRequest.capability, requestedAt: view.pendingRequest.requestedAt, ...(view.pendingRequest.change ? { change: view.pendingRequest.change } : {}) }
+        : null,
+      desktopPermissions: this.desktopPermissions,
+    };
+    const key = JSON.stringify(params);
+    if (key === this.sentAccessKey) return;
     this.sentAccessKey = key;
-    this.sendSigned({ jsonrpc: '2.0', method: 'tunnel.access.state', params: { mode, grantedUntil } });
+    this.sendSigned({ jsonrpc: '2.0', method: 'tunnel.access.state', params });
+  }
+
+  /**
+   * Asks the desktop driver whether macOS lets THIS process see and drive the
+   * screen. The answer for another process (the app window) can differ.
+   */
+  private async probeDesktopPermissions(): Promise<void> {
+    const call = this.registry.getHandler('desktop.cua.call');
+    if (!call || this.probingDesktop) return;
+    this.probingDesktop = true;
+    try {
+      const report = (await call({ tool: 'check_permissions', args: {}, __permission: { capability: 'desktop' } })) as Record<string, unknown> | null;
+      this.desktopPermissions = {
+        accessibility: report?.accessibility === true,
+        screenRecording: report?.screen_recording === true,
+      };
+    } catch {
+      // A failed probe says nothing about the grants; keep the last answer.
+    } finally {
+      this.probingDesktop = false;
+    }
+    this.reportAccess();
   }
 
   /** R6: hold a sleep blocker while access.json asks for it. */
@@ -709,6 +827,8 @@ export class TunnelAgent {
         this.syncKeepAwake(access.keepAwake);
         this.reportAccess();
       } catch {}
+      // Grants change in System Settings while the agent runs: re-check every minute.
+      if (++this.watchdogTicks % DESKTOP_PROBE_EVERY_TICKS === 0 && this.status === 'online') void this.probeDesktopPermissions();
     }, interval);
     this.watchdog.unref?.();
   }

package/src/agent/capabilities/desktop/cua-driver.test.ts

@@ -26,7 +26,14 @@ function fakeDriver(dir: string): { binary: string; log: string } {
 echo "$* | embedded=$CUA_DRIVER_EMBEDDED telemetry=$CUA_DRIVER_RS_TELEMETRY_ENABLED host=$CUA_DRIVER_HOST_BUNDLE_ID" >> "${log}"
 case "$1" in
   serve)
-    while [ "$#" -gt 0 ]; do [ "$1" = "--socket" ] && touch "$2"; shift; done
+    # Like the real driver (0.31.0): refuses to start over an existing endpoint.
+    while [ "$#" -gt 0 ]; do
+      if [ "$1" = "--socket" ]; then
+        if [ -e "$2" ]; then echo "embedded daemon endpoint already exists at $2" >&2; exit 1; fi
+        touch "$2"
+      fi
+      shift
+    done
     sleep 30 ;;
   status)
     # Like the real driver: running only while a daemon listens on the socket.
@@ -78,6 +85,41 @@ describe('embedded driver', () => {
     }
   });
 
+  test('a socket left by a previous agent is stopped and removed, and its own daemon starts', async () => {
+    const dir = tempDir();
+    const { binary, log } = fakeDriver(dir);
+    const socketPath = join(dir, 'cua.sock');
+    writeFileSync(socketPath, '');
+    const driver = new CuaDriver({ binary, embedded: true, socketPath });
+    try {
+      expect(await driver.call('health_report', {})).toEqual({ ok: true });
+      const commands = readFileSync(log, 'utf8').trim().split('\n').map((line) => line.split(' ')[0]);
+      expect(commands).toEqual(['stop', 'serve', 'call']);
+    } finally {
+      driver.stop();
+    }
+  });
+
+  test('a daemon that does not start fails the call, and the next call tries again', async () => {
+    const dir = tempDir();
+    const binary = join(dir, 'cua-driver');
+    const log = join(dir, 'calls.log');
+    writeFileSync(binary, `#!/bin/sh\necho "$1" >> "${log}"\n[ "$1" = serve ] && exit 1\necho '{"ok":true}'\n`);
+    chmodSync(binary, 0o755);
+    const driver = new CuaDriver({ binary, embedded: true, socketPath: join(dir, 'cua.sock') });
+    await expect(driver.call('get_screen_size', {})).rejects.toThrow('cua-driver did not start');
+    await expect(driver.call('get_screen_size', {})).rejects.toThrow('cua-driver did not start');
+    expect(readFileSync(log, 'utf8').trim().split('\n')).toEqual(['serve', 'serve']);
+  });
+
+  test('missingPermissions names the macOS grants the driver reports missing', async () => {
+    const dir = tempDir();
+    const binary = join(dir, 'cua-driver');
+    writeFileSync(binary, `#!/bin/sh\necho '{"accessibility":false,"screen_recording":true}'\n`);
+    chmodSync(binary, 0o755);
+    expect(await new CuaDriver({ binary }).missingPermissions()).toEqual(['Accessibility']);
+  });
+
   test('a separately installed driver keeps its standalone mode, without telemetry', async () => {
     const dir = tempDir();
     const { binary, log } = fakeDriver(dir);

package/src/agent/capabilities/desktop/cua-driver.ts

@@ -1,7 +1,8 @@
 import { spawn, type ChildProcess } from 'child_process';
-import { existsSync, readFileSync, realpathSync, statSync } from 'fs';
+import { existsSync, readFileSync, realpathSync, rmSync, statSync } from 'fs';
 import { homedir, platform, tmpdir } from 'os';
 import { basename, dirname, join } from 'path';
+import { agentTunnelHome, serviceLabelFor, SERVICE_LABEL } from '../../service-paths';
 
 interface ExecResult {
   stdout: string;
@@ -150,7 +151,8 @@ function execFile(
       clearTimeout(timer);
       if (code !== 0) {
         const detail = stderr.trim() || stdout.trim();
-        reject(new Error(`${cmd} failed (${code})${detail ? `: ${detail}` : ''}`));
+        // The driver's name, not its install path: agents read this message.
+        reject(new Error(`${basename(cmd)} failed (${code})${detail ? `: ${detail}` : ''}`));
       } else {
         resolve({ stdout, stderr });
       }
@@ -231,8 +233,10 @@ export class CuaDriver {
     this.binary = options.binary ?? null;
     this.embedded = options.embedded;
     const uid = typeof process.getuid === 'function' ? process.getuid() : 'user';
-    // Under $TMPDIR: a unix socket path is capped at 104 bytes on macOS.
-    this.socketPath = options.socketPath ?? join(tmpdir(), `kortix-cua-${uid}.sock`);
+    // One driver per agent home (the label's suffix), so two homes never share
+    // or steal a driver. Under $TMPDIR: a socket path is capped at 104 bytes on macOS.
+    const home = serviceLabelFor(agentTunnelHome()).slice(SERVICE_LABEL.length);
+    this.socketPath = options.socketPath ?? join(tmpdir(), `kortix-cua-${uid}${home}.sock`);
     this.hostBundleId = options.hostBundleId;
   }
 
@@ -326,6 +330,8 @@ export class CuaDriver {
 
     if (this.isEmbedded(bin)) {
       await this.startEmbeddedDaemon(bin);
+      this.daemonReady = true;
+      return { ok: true };
     } else if (platform() === 'darwin') {
       const child = spawn('open', ['-n', '-g', '-a', 'CuaDriver', '--args', 'serve'], {
         detached: true,
@@ -360,6 +366,14 @@ export class CuaDriver {
   private async startEmbeddedDaemon(bin: string): Promise<void> {
     if (this.daemon && this.daemon.exitCode === null) return;
     const { env, socket } = this.mode(bin);
+    // A socket this agent did not just start is stale: a previous agent left it
+    // when it exited, and the driver refuses to start over an existing endpoint.
+    // Stop whatever may still answer on it (it runs outside this process's
+    // macOS permissions), then remove it.
+    if (existsSync(this.socketPath)) {
+      await execFile(bin, ['stop', ...socket], 10_000, env).catch(() => undefined);
+      rmSync(this.socketPath, { force: true });
+    }
     const child = spawn(bin, ['serve', '--embedded', '--no-permissions-gate', ...socket], {
       stdio: 'ignore',
       env,
@@ -383,6 +397,24 @@ export class CuaDriver {
     }
   }
 
+  /**
+   * The macOS grants the driver reports missing for its permission owner:
+   * Kortix when embedded, CuaDriver otherwise. Empty when nothing is missing
+   * or the platform has no such grants.
+   */
+  /** The app macOS shows in Privacy & Security for this driver's grants. */
+  async permissionOwner(): Promise<string> {
+    return this.isEmbedded(await this.ensureInstalled()) ? 'Kortix' : 'CuaDriver';
+  }
+
+  async missingPermissions(): Promise<string[]> {
+    const report = (await this.call('check_permissions', {})) as Record<string, unknown> | null;
+    const missing: string[] = [];
+    if (report?.accessibility === false) missing.push('Accessibility');
+    if (report?.screen_recording === false) missing.push('Screen Recording');
+    return missing;
+  }
+
   /** Stops an embedded daemon this agent started. Restarting picks up new grants. */
   stop(): void {
     this.daemon?.kill();
@@ -391,6 +423,14 @@ export class CuaDriver {
   }
 
   private async ensureDaemonReady(): Promise<void> {
+    const bin = await this.ensureInstalled();
+    // Embedded: only a driver this agent started runs inside its permissions.
+    if (this.isEmbedded(bin)) {
+      if (this.daemon?.exitCode === null && existsSync(this.socketPath)) return;
+      this.stop();
+      await this.startDaemon();
+      return;
+    }
     if (this.daemonReady) return;
     try {
       const status = await this.status();

package/src/agent/capabilities/desktop.ts

@@ -1,46 +1,7 @@
 import type { Capability, RpcHandler } from './index';
 import { CuaDriver } from './desktop/cua-driver';
-import { desktopFeatureForMethod } from '../../shared/permissions';
 import type { LocalPermission } from '../security/permission-guard';
-
-const CUA_TOOLS = [
-  'bring_to_front',
-  'check_for_update',
-  'check_permissions',
-  'click',
-  'double_click',
-  'drag',
-  'end_session',
-  'get_accessibility_tree',
-  'get_agent_cursor_state',
-  'get_config',
-  'get_cursor_position',
-  'get_recording_state',
-  'get_screen_size',
-  'get_window_state',
-  'hotkey',
-  'kill_app',
-  'launch_app',
-  'list_apps',
-  'list_windows',
-  'move_cursor',
-  'page',
-  'press_key',
-  'replay_trajectory',
-  'right_click',
-  'scroll',
-  'set_agent_cursor_enabled',
-  'set_agent_cursor_motion',
-  'set_agent_cursor_style',
-  'set_config',
-  'set_value',
-  'start_recording',
-  'install_ffmpeg',
-  'start_session',
-  'stop_recording',
-  'type_text',
-  'zoom',
-];
+import { TunnelErrorCode } from '../../shared/types';
 
 const LOCAL_ONLY_CUA_TOOLS = new Set(['check_for_update', 'install_ffmpeg']);
 
@@ -53,75 +14,87 @@ function assertRemotelyCallableTool(tool: unknown): asserts tool is string {
   }
 }
 
-export function createDesktopCapability(): Capability {
+/** An RPC error with a binding code (the API maps it to a refusal kind). */
+export class DesktopPermissionMissingError extends Error {
+  readonly code = TunnelErrorCode.DESKTOP_PERMISSION_MISSING;
+}
+
+/**
+ * A failed call is first asked "does macOS let this process see and drive the
+ * screen?". Without Accessibility or Screen Recording every tool fails with a
+ * driver-specific message; this turns all of them into one actionable error.
+ */
+async function explainFailure(cua: CuaDriver, err: unknown, onMissing: () => void): Promise<never> {
+  const missing = await cua.missingPermissions().catch(() => []);
+  if (missing.length > 0) {
+    onMissing();
+    throw new DesktopPermissionMissingError(
+      `computer_desktop_permission_missing: macOS has not given ${await cua.permissionOwner()} ${missing.join(' and ')} on this computer.`,
+    );
+  }
+  throw err;
+}
+
+/**
+ * Desktop is one grant ("Screen & keyboard"): an approved desktop permission
+ * allows every driver tool. The tool list belongs to the installed driver.
+ */
+export function createDesktopCapability(options: { onPermissionMissing?: () => void } = {}): Capability {
   const cua = new CuaDriver();
   const methods = new Map<string, RpcHandler>();
+  const onMissing = options.onPermissionMissing ?? (() => {});
 
-  const assertDesktopPermission = (params: Record<string, unknown>, method: string): void => {
+  const assertDesktopPermission = (params: Record<string, unknown>): void => {
     const permission = params.__permission as LocalPermission | undefined;
     if (permission?.capability !== 'desktop') {
       throw new Error('Permission denied: desktop permission required');
     }
-    const features = Array.isArray(permission.scope?.features)
-      ? permission.scope.features.filter((value): value is string => typeof value === 'string')
-      : [];
-    if (features.length === 0) return;
-    const feature = desktopFeatureForMethod(method, params);
-    if (!feature || !features.includes(feature)) {
-      throw new Error(
-        `Permission denied: desktop feature "${feature ?? 'unknown'}" is not allowed`,
-      );
-    }
   };
 
   methods.set('desktop.cua.ensure', async (params) => {
-    assertDesktopPermission(params, 'desktop.cua.ensure');
+    assertDesktopPermission(params);
     const binary = await cua.ensureInstalled();
     const version = await cua.version().catch(() => undefined);
     return { ok: true, binary, version };
   });
 
   methods.set('desktop.cua.start_daemon', async (params) => {
-    assertDesktopPermission(params, 'desktop.cua.start_daemon');
+    assertDesktopPermission(params);
     return cua.startDaemon();
   });
 
   methods.set('desktop.cua.status', async (params) => {
-    assertDesktopPermission(params, 'desktop.cua.status');
+    assertDesktopPermission(params);
     return { status: await cua.status() };
   });
 
   methods.set('desktop.cua.version', async (params) => {
-    assertDesktopPermission(params, 'desktop.cua.version');
+    assertDesktopPermission(params);
     return { version: await cua.version() };
   });
 
   methods.set('desktop.cua.list_tools', async (params) => {
-    assertDesktopPermission(params, 'desktop.cua.list_tools');
+    assertDesktopPermission(params);
     return { tools: await cua.listTools() };
   });
 
   methods.set('desktop.cua.describe', async (params) => {
-    assertDesktopPermission(params, 'desktop.cua.describe');
+    assertDesktopPermission(params);
     return { description: await cua.describe(params.tool as string) };
   });
 
   methods.set('desktop.cua.call', async (params) => {
-    assertDesktopPermission(params, 'desktop.cua.call');
+    assertDesktopPermission(params);
     const tool = params.tool;
     assertRemotelyCallableTool(tool);
     const args = (params.args || {}) as Record<string, unknown>;
-    return cua.call(tool, args);
+    try {
+      return await cua.call(tool, args);
+    } catch (err) {
+      return explainFailure(cua, err, onMissing);
+    }
   });
 
-  for (const tool of CUA_TOOLS) {
-    if (LOCAL_ONLY_CUA_TOOLS.has(tool)) continue;
-    methods.set(`desktop.cua.${tool}`, async (params) => {
-      assertDesktopPermission(params, `desktop.cua.${tool}`);
-      return cua.call(tool, params);
-    });
-  }
-
   return {
     name: 'desktop',
     methods,

package/src/agent/capabilities/enabled-registry.ts

@@ -9,6 +9,7 @@ import { createShellCapability } from './shell';
 export function createEnabledCapabilityRegistry(
   config: TunnelConfig,
   findDesktopDriver: () => string | null = findCuaDriverBinary,
+  desktop: { onPermissionMissing?: () => void } = {},
 ): CapabilityRegistry {
   const registry = new CapabilityRegistry();
   const enabled = new Set(config.enabledCapabilities ?? ['filesystem', 'shell', 'desktop']);
@@ -18,7 +19,7 @@ export function createEnabledCapabilityRegistry(
   // local driver. The server must see the real handler surface, not the user's
   // desired capability list.
   if (enabled.has('desktop') && findDesktopDriver()) {
-    registry.register(createDesktopCapability());
+    registry.register(createDesktopCapability(desktop));
   }
   return registry;
 }

package/src/agent/capabilities/security.test.ts

@@ -72,7 +72,7 @@ describe('local capability permission enforcement', () => {
       () => '/trusted/cua-driver',
     );
     expect(registry.getCapabilityNames()).toEqual(['desktop']);
-    expect(registry.getHandler('desktop.cua.get_screen_size')).not.toBeNull();
+    expect(registry.getHandler('desktop.cua.call')).not.toBeNull();
   });
   test('a permission scope cannot widen the local filesystem ceiling', async () => {
     const handler = createFilesystemCapability(config()).methods.get('fs.read')!;
@@ -154,19 +154,59 @@ describe('local capability permission enforcement', () => {
     ).rejects.toThrow('not in the allowed commands list');
   });
 
-  test('desktop feature scopes deny before invoking cua-driver', async () => {
-    const handler = createDesktopCapability().methods.get('desktop.cua.click')!;
-    await expect(
-      handler({
-        x: 10,
-        y: 10,
-        __permission: {
-          permissionId: 'permission-1',
-          capability: 'desktop',
-          scope: { features: ['screenshot'] },
-        },
-      }),
-    ).rejects.toThrow('desktop feature "mouse" is not allowed');
+  test('a desktop grant allows every driver tool, and a legacy feature scope no longer narrows it', async () => {
+    const binary = join(root, 'fake-call-driver');
+    const log = join(root, 'call-args.jsonl');
+    await writeFile(binary, [
+      '#!/usr/bin/env node',
+      `require('node:fs').appendFileSync(${JSON.stringify(log)}, JSON.stringify(process.argv.slice(2, 4)) + '\\n');`,
+      `process.stdout.write('{"ok":true}');`,
+    ].join('\n'));
+    await chmod(binary, 0o700);
+    const previousBinary = process.env.CUA_DRIVER_BIN;
+    process.env.CUA_DRIVER_BIN = binary;
+    try {
+      const call = createDesktopCapability().methods.get('desktop.cua.call')!;
+      const __permission = { permissionId: 'p', capability: 'desktop', scope: { features: ['screenshot'] } };
+      // health_report was never in Kortix's tool list; the driver owns that list.
+      expect(await call({ tool: 'health_report', args: {}, __permission })).toEqual({ ok: true });
+      await expect(call({ tool: 'install_ffmpeg', __permission })).rejects.toThrow('local-only');
+      await expect(call({ tool: 'click', __permission: { ...__permission, capability: 'shell' } }))
+        .rejects.toThrow('desktop permission required');
+      const calls = (await readFile(log, 'utf8')).trim().split('\n').map((line) => JSON.parse(line));
+      expect(calls.at(-1)).toEqual(['call', 'health_report']);
+    } finally {
+      if (previousBinary === undefined) delete process.env.CUA_DRIVER_BIN;
+      else process.env.CUA_DRIVER_BIN = previousBinary;
+    }
+  });
+
+  test('a failed call reports missing macOS grants as computer_desktop_permission_missing (-32013)', async () => {
+    const binary = join(root, 'fake-untrusted-driver');
+    await writeFile(binary, [
+      '#!/usr/bin/env node',
+      'const [command, tool] = process.argv.slice(2);',
+      `if (command === 'call' && tool === 'check_permissions') process.stdout.write('{"accessibility":false,"screen_recording":false}');`,
+      `else if (command === 'call') { process.stderr.write('AX is not trusted'); process.exitCode = 1; }`,
+      `else process.stdout.write('running');`,
+    ].join('\n'));
+    await chmod(binary, 0o700);
+    const previousBinary = process.env.CUA_DRIVER_BIN;
+    process.env.CUA_DRIVER_BIN = binary;
+    let restarts = 0;
+    try {
+      const call = createDesktopCapability({ onPermissionMissing: () => restarts++ }).methods.get('desktop.cua.call')!;
+      const error = await call({ tool: 'click', args: { pid: 1 }, __permission: { permissionId: 'p', capability: 'desktop', scope: {} } })
+        .catch((err: unknown) => err as Error & { code?: number });
+      expect((error as Error).message).toBe(
+        'computer_desktop_permission_missing: macOS has not given CuaDriver Accessibility and Screen Recording on this computer.',
+      );
+      expect((error as { code?: number }).code).toBe(-32013);
+      expect(restarts).toBe(1);
+    } finally {
+      if (previousBinary === undefined) delete process.env.CUA_DRIVER_BIN;
+      else process.env.CUA_DRIVER_BIN = previousBinary;
+    }
   });
 
   test('desktop discovery dispatches to driver metadata commands and preserves unsupported output', async () => {
@@ -195,8 +235,6 @@ describe('local capability permission enforcement', () => {
         scope: { features: ['computer_use'] },
       };
       await expect(list({})).rejects.toThrow('desktop permission required');
-      await expect(list({ __permission: { ...__permission, scope: { features: ['screenshot'] } } }))
-        .rejects.toThrow('not allowed');
       expect(await list({ __permission })).toEqual({ tools: 'double_click' });
       expect(await describeTool({ tool: 'double_click', __permission }))
         .toEqual({ description: 'Double click coordinates' });