@kortix/agent-tunnel 0.13.52 → 0.13.54

package/src/agent/cli-help.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { spawnSync } from "child_process";
-import { mkdtempSync, rmSync } from "fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join, resolve } from "path";
 
@@ -20,6 +20,8 @@ const DOCUMENTED_SURFACE = [
   "status",
   "logs",
   "logout",
+  "access",
+  "keep-awake",
   "--daemon",
   "--foreground",
 ] as const;
@@ -84,6 +86,55 @@ describe("agent tunnel service UX", () => {
     );
 
     expect(result.status).toBe(2);
-    expect(result.stderr).toContain("--keep-awake is not supported");
+    expect(result.stderr).toContain("--keep-awake is not a flag. Run: agent-tunnel keep-awake on");
+  });
+});
+
+describe("access and keep-awake: the one way to change them on this computer", () => {
+  const run = (home: string, ...args: string[]) =>
+    spawnSync("bun", ["run", CLI_PATH, ...args], {
+      encoding: "utf8",
+      env: { ...process.env, AGENT_TUNNEL_HOME: home },
+    });
+
+  test("changes access and keep awake, prints the state, and writes access.json", () => {
+    const home = mkdtempSync(join(tmpdir(), "agent-tunnel-cli-access-"));
+    try {
+      const shown = JSON.parse(run(home, "access", "--json").stdout);
+      expect(shown).toMatchObject({ mode: "always", keepAwake: false, pendingRequest: null });
+
+      const ask = run(home, "access", "ask", "--json");
+      expect(ask.status).toBe(0);
+      expect(JSON.parse(ask.stdout).mode).toBe("ask");
+
+      const granted = JSON.parse(run(home, "access", "--allow-for", "60", "--json").stdout);
+      expect(Date.parse(granted.grantedUntil) - Date.now()).toBeGreaterThan(59 * 60_000);
+
+      expect(JSON.parse(run(home, "access", "--revoke", "--json").stdout).grantedUntil).toBeNull();
+      expect(JSON.parse(run(home, "keep-awake", "on", "--json").stdout).keepAwake).toBe(true);
+      expect(JSON.parse(readFileSync(join(home, "access.json"), "utf8"))).toMatchObject({ mode: "ask", keepAwake: true });
+
+      const status = JSON.parse(run(home, "status", "--json").stdout);
+      expect(status.access).toMatchObject({ mode: "ask", keepAwake: true, keepAwakeSupported: process.platform !== "win32" });
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("refuses a wrong mode or duration with exit 1 and changes nothing", () => {
+    const home = mkdtempSync(join(tmpdir(), "agent-tunnel-cli-access-"));
+    try {
+      const mode = run(home, "access", "sometimes");
+      expect(mode.status).toBe(1);
+      expect(mode.stderr).toContain("Access is one of: ask, always, off");
+      const minutes = run(home, "access", "--allow-for", "soon");
+      expect(minutes.status).toBe(1);
+      expect(minutes.stderr).toContain("--allow-for takes minutes");
+      const awake = run(home, "keep-awake", "maybe");
+      expect(awake.status).toBe(1);
+      expect(existsSync(join(home, "access.json"))).toBe(false);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
   });
 });

package/src/agent/cli.ts

@@ -4,7 +4,17 @@ import { hostname } from 'os';
 import { join } from 'path';
 
 import { PAIR_AGAIN_COMMAND, TunnelAgent } from './agent';
-import { accessFilePath, accessRequestPath, desktopAppPath, readAccess, writeAccess } from './access';
+import {
+  accessFilePath,
+  accessRequestPath,
+  accessView,
+  applyAccess,
+  desktopAppPath,
+  readAccess,
+  writeAccess,
+  type AccessChange,
+  type AccessView,
+} from './access';
 import { printStartupBanner } from './banner';
 import { createEnabledCapabilityRegistry } from './capabilities/enabled-registry';
 import { loadConfig, type TunnelConfig } from './config';
@@ -18,12 +28,12 @@ import {
   requestDeviceAuthorization,
 } from './device-auth';
 import { collapseRepeatedLines, isShellStartupNoise } from './log-format';
-import { anyFlag, isInteractiveTerminal, isTruthyFlag, promptYesNo } from './prompts';
+import { anyFlag, isInteractiveTerminal, isTruthyFlag } from './prompts';
 import {
-  DEFAULT_INSTALL_BACKGROUND_SERVICE,
   agentTunnelHome,
   getServicePaths,
   getServiceStatus,
+  installedAppRunner,
   rotateServiceLogs,
   serviceLogFiles,
 } from './service';
@@ -34,6 +44,7 @@ import {
   describeService,
   renderServiceAction,
 } from './service-control';
+import { watchForRestart } from './self-restart';
 import { readAgentState, writeAgentState } from './state-file';
 import { blankLine, c, clearScreen, field, glyph, stripAnsi } from './terminal';
 import { agentTunnelVersion } from './version';
@@ -43,16 +54,22 @@ const BACKGROUND_FLAGS = ['daemon', 'service', 'background', 'always-online'] as
 const FOREGROUND_FLAGS = ['foreground', 'no-daemon', 'no-service', 'no-background'] as const;
 const DEFAULT_LOG_LINES = 60;
 
+/** `_` holds the words after the command (`access always` → `_: 'always'`). */
 type Flags = Record<string, string>;
 
 function parseArgs(argv: string[]): { command: string; flags: Flags } {
   const flags: Flags = {};
+  const words: string[] = [];
   for (let i = 3; i < argv.length; i++) {
     const arg = argv[i];
-    if (!arg.startsWith('--')) continue;
+    if (!arg.startsWith('--')) {
+      words.push(arg);
+      continue;
+    }
     const next = argv[i + 1];
     flags[arg.slice(2)] = next && !next.startsWith('--') ? argv[++i] : 'true';
   }
+  if (words.length > 0) flags._ = words.join(' ');
   return { command: argv[2] || 'help', flags };
 }
 
@@ -90,7 +107,17 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
     process.stdout.write = process.stderr.write.bind(process.stderr) as typeof process.stdout.write;
     options = { ...options, service: true };
   }
-  const registry = createEnabledCapabilityRegistry(config);
+  let agent: TunnelAgent | null = null;
+  const restart = options.service
+    ? watchForRestart((reason) => {
+        process.stdout.write(`[agent-tunnel] restarting: ${reason}\n`);
+        agent?.disconnect();
+        process.exit(0);
+      })
+    : null;
+  const registry = createEnabledCapabilityRegistry(config, undefined, {
+    onPermissionMissing: restart?.permissionMissing,
+  });
   if (config.enabledCapabilities?.includes('desktop') && !registry.has('desktop')) {
     console.error(
       '[agent-tunnel] Computer Use is approved but unavailable: install the trusted cua-driver locally, then restart Agent Tunnel.',
@@ -111,7 +138,7 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
 
   // A service never stops on its own (R2): a refused credential waits in
   // `rejected` and re-reads config.json, so pairing again heals it.
-  const agent = new TunnelAgent(
+  agent = new TunnelAgent(
     config,
     registry,
     // The agent passes the credential it uses NOW: a re-pair picked up by a
@@ -126,7 +153,7 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
 
   const shutdown = () => {
     if (!options.service) console.log(`\n${c.dim}  Shutting down…${c.reset}`);
-    agent.disconnect();
+    agent?.disconnect();
     process.exit(0);
   };
   process.on('SIGTERM', shutdown);
@@ -135,26 +162,38 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
 
 // ── pairing ──────────────────────────────────────────────────────────────────
 
-async function chooseBackgroundMode(flags: Flags): Promise<boolean> {
+/**
+ * A person at a terminal gets what the desktop app gives: a background
+ * connection, no question asked, and the exact commands that pause, resume,
+ * and remove it. `--foreground` keeps it in this terminal only. A script
+ * (no TTY) or `--json` keeps the foreground default it always had.
+ */
+function chooseBackgroundMode(flags: Flags): boolean {
   if (anyFlag(flags, BACKGROUND_FLAGS)) return true;
   if (anyFlag(flags, FOREGROUND_FLAGS)) return false;
-  if (jsonMode || !isInteractiveTerminal()) return false;
+  return !jsonMode && isInteractiveTerminal();
+}
 
+function printServiceControls(): void {
+  const npx = 'npx @kortix/agent-tunnel@latest';
+  console.log(`  ${c.dim}Runs in the background: starts at login, restarts after failures, keeps running after this terminal closes.${c.reset}`);
+  if (installedAppRunner()) {
+    console.log(`  ${c.dim}It runs on the Kortix app on this Mac: same connection, same macOS permissions. Control it from Your computer in the app.${c.reset}`);
+  }
   blankLine();
-  console.log(`  ${glyph.warn} ${c.bold}Security note${c.reset}`);
-  console.log(`  ${c.dim}Background mode starts at login, continues after this terminal closes, and restarts after failures.${c.reset}`);
-  console.log(`  ${c.dim}The computer must remain powered on, awake, and connected to the internet.${c.reset}`);
+  field('Pause', `${c.white}${npx} stop${c.reset}`);
+  field('Resume', `${c.white}${npx} start${c.reset}`);
+  field('Disconnect', `${c.white}${npx} logout${c.reset}`);
   blankLine();
-
-  return promptYesNo('  Install the background service now?', DEFAULT_INSTALL_BACKGROUND_SERVICE);
 }
 
 /** Starts the agent the way the caller asked for, and returns. */
 async function launch(config: TunnelConfig, flags: Flags, lease?: { serviceWasActive: boolean }): Promise<void> {
-  if (await chooseBackgroundMode(flags)) {
+  if (chooseBackgroundMode(flags)) {
     saveCredentials(config.tunnelId, config.token, config.apiUrl);
     if (!jsonMode) {
       renderServiceAction('install', SERVICE_ACTIONS.install.run());
+      printServiceControls();
       return;
     }
     // Return instead of process.exit(): an exit can cut off a piped stdout.
@@ -408,7 +447,7 @@ function commandStatus(flags: Flags): void {
       serviceLabel: getServicePaths().label,
       service,
       state: readAgentState(),
-      access: readAccess(),
+      access: accessView(),
       lastActivity: lastServiceActivity(),
     }, null, 2));
     return;
@@ -566,6 +605,69 @@ function commandServiceAction(action: ServiceAction, flags: Flags): void {
   renderServiceAction(action, SERVICE_ACTIONS[action].run());
 }
 
+/** "Ask each time · allowed until 14:05", for a person at a terminal. */
+function describeAccess(view: AccessView): string {
+  const clock = (iso: string) => new Date(iso).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  if (view.mode === 'always') return `${c.white}Always allowed${c.reset}`;
+  if (view.mode === 'off') return `${c.white}Off${c.reset} ${c.dim}(every agent call is refused)${c.reset}`;
+  const now = view.grantedUntil
+    ? `allowed until ${clock(view.grantedUntil)}`
+    : view.deniedUntil
+      ? `denied until ${clock(view.deniedUntil)}`
+      : 'asks before the next call';
+  return `${c.white}Ask each time${c.reset} ${c.dim}· ${now}${c.reset}`;
+}
+
+function printAccess(view: AccessView, flags: Flags): void {
+  if (isTruthyFlag(flags.json)) {
+    console.log(JSON.stringify(view, null, 2));
+    return;
+  }
+  const npx = 'npx @kortix/agent-tunnel@latest';
+  blankLine();
+  field('access', describeAccess(view));
+  field('keep awake', view.keepAwakeSupported ? (view.keepAwake ? `${c.white}on${c.reset}` : `${c.white}off${c.reset}`) : `${c.dim}not available on this system${c.reset}`);
+  if (view.pendingRequest) {
+    field('waiting', `${c.white}${view.pendingRequest.change ? 'a change asked for through Kortix' : `an agent call (${view.pendingRequest.capability})`}${c.reset}`);
+    field('', `${c.dim}${npx} access --allow-for 60   or   --deny${c.reset}`);
+  }
+  blankLine();
+  console.log(`  ${c.dim}Change it:${c.reset} ${c.white}${npx} access ask|always|off${c.reset}${c.dim}, --allow-for <minutes>, --revoke, --deny${c.reset}`);
+  blankLine();
+}
+
+/**
+ * `access [ask|always|off] [--allow-for <minutes>] [--revoke] [--deny]`: when
+ * Kortix may use this computer. The person at this machine is its owner, so
+ * this widens access too; the desktop app runs this command after its own
+ * confirmation. No change prints the current state.
+ */
+function commandAccess(flags: Flags): void {
+  const change: AccessChange = {};
+  if (flags._) change.mode = flags._ as AccessChange['mode'];
+  if (flags['allow-for'] !== undefined) {
+    change.grantMinutes = Number(flags['allow-for']);
+    if (!(change.grantMinutes > 0)) fail('--allow-for takes minutes, at most 1440. Example: agent-tunnel access --allow-for 60');
+  }
+  if (isTruthyFlag(flags.revoke)) change.revoke = true;
+  if (isTruthyFlag(flags.deny)) change.deny = true;
+  if (Object.keys(change).length === 0) return printAccess(accessView(), flags);
+  if (change.mode !== undefined && !['ask', 'always', 'off'].includes(change.mode)) {
+    fail('Access is one of: ask, always, off. Example: agent-tunnel access ask');
+  }
+  // A grant applies in "Ask each time"; from another mode it means "ask, allowed for now".
+  if (change.grantMinutes !== undefined && change.mode === undefined && readAccess().mode !== 'ask') change.mode = 'ask';
+  printAccess(applyAccess(change), flags);
+}
+
+/** `keep-awake [on|off]`: hold off system sleep while the agent runs (macOS, Linux). */
+function commandKeepAwake(flags: Flags): void {
+  if (flags._ === undefined) return printAccess(accessView(), flags);
+  if (flags._ !== 'on' && flags._ !== 'off') fail('Keep awake is on or off. Example: agent-tunnel keep-awake on');
+  if (!accessView().keepAwakeSupported) fail('Keep awake is not available on this system yet.');
+  printAccess(applyAccess({ keepAwake: flags._ === 'on' }), flags);
+}
+
 // ── dispatch ─────────────────────────────────────────────────────────────────
 
 interface Command {
@@ -581,6 +683,11 @@ const COMMANDS: Record<string, Command> = {
     run: commandConnect,
   },
   status: { summary: 'Show pairing, capabilities, and service state (--json)', run: commandStatus },
+  access: {
+    summary: 'When Kortix may use this computer: ask, always, off (--allow-for <min>, --revoke, --deny, --json)',
+    run: commandAccess,
+  },
+  'keep-awake': { summary: 'Keep this computer awake while connected: on, off (--json)', run: commandKeepAwake },
   logs: { summary: 'Show recent service logs (--lines <n>, --all, --clear)', run: commandLogs },
   start: {
     summary: 'Start the background service (resumes a paused one)',
@@ -620,7 +727,7 @@ const OPTIONS: ReadonlyArray<readonly [string, string]> = [
   ['--reauth', 'With connect: discard the saved credential and pair again'],
   ['--daemon / --foreground', 'With connect: skip the prompt and choose the mode'],
   ['--project-id <uuid>', 'With connect: offer "Also share with <project>" on the approval page; the computer is yours in every project either way'],
-  ['--json', 'With connect: NDJSON events, no prompts. With status and logout: machine-readable output'],
+  ['--json', 'With connect: NDJSON events, no prompts. With status, access, keep-awake, and logout: machine-readable output'],
   ['--keep-service', 'With logout: keep the background service installed'],
 ];
 
@@ -658,7 +765,7 @@ const { command, flags } = parseArgs(process.argv);
 jsonMode = command === 'connect' && isTruthyFlag(flags.json);
 
 if (Object.prototype.hasOwnProperty.call(flags, 'keep-awake')) {
-  console.error(`  ${glyph.bad} --keep-awake is not supported. Configure sleep behavior in the operating system.`);
+  console.error(`  ${glyph.bad} --keep-awake is not a flag. Run: agent-tunnel keep-awake on`);
   process.exit(2);
 }
 
@@ -669,7 +776,8 @@ const resolved =
 if (!resolved) {
   showHelp();
 } else {
-  void Promise.resolve(resolved.run(flags)).catch((error: unknown) => {
+  // `.then`: a command that throws synchronously reports like one that rejects.
+  void Promise.resolve().then(() => resolved.run(flags)).catch((error: unknown) => {
     fail(error instanceof Error ? error.message : String(error));
   });
 }

package/src/agent/self-restart.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from 'bun:test';
+import { mkdtempSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { runtimeFingerprint } from './self-restart';
+
+test('an update that swaps a runtime file in place changes the fingerprint', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'self-restart-'));
+  try {
+    const binary = join(dir, 'Kortix');
+    writeFileSync(binary, 'v1');
+    const started = runtimeFingerprint([binary]);
+    expect(runtimeFingerprint([binary])).toBe(started);
+    // An app updater writes the new bundle beside the old one and renames it over.
+    writeFileSync(join(dir, 'next'), 'v1');
+    renameSync(join(dir, 'next'), binary);
+    expect(runtimeFingerprint([binary])).not.toBe(started);
+    rmSync(binary);
+    expect(runtimeFingerprint([binary])).toBe('missing');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/agent/self-restart.ts

@@ -0,0 +1,47 @@
+import { statSync } from 'fs';
+
+/** Identity of the files this process runs; a replaced file changes it. */
+export function runtimeFingerprint(files: readonly string[]): string {
+  return files
+    .map((file) => {
+      try {
+        const stat = statSync(file);
+        return `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+      } catch {
+        return 'missing';
+      }
+    })
+    .join('|');
+}
+
+/** A macOS grant refused this long after start is not a grant this process missed. */
+const PERMISSION_RESTART_MIN_UPTIME_S = 5 * 60;
+
+/**
+ * A background service must not outlive its own code or its macOS grants:
+ *
+ * - An app update replaces the binary under the running agent. macOS then
+ *   cannot validate the old process's signature and refuses it Accessibility
+ *   and Screen Recording, while the updated app itself shows them allowed.
+ * - A grant made in System Settings applies to processes started after it.
+ *
+ * Both are healed by exiting: the supervisor (launchd KeepAlive, systemd
+ * Restart=always, the Windows loop) starts the service again on the current
+ * code with the current grants.
+ */
+export function watchForRestart(exit: (reason: string) => void, intervalMs = 60_000): {
+  permissionMissing: () => void;
+} {
+  const files = [process.execPath, process.argv[1]].filter((file): file is string => Boolean(file));
+  const started = runtimeFingerprint(files);
+  setInterval(() => {
+    if (runtimeFingerprint(files) !== started) exit('its code was updated');
+  }, intervalMs).unref();
+  return {
+    permissionMissing: () => {
+      if (process.uptime() < PERMISSION_RESTART_MIN_UPTIME_S) return;
+      // After the refusal is sent: the caller gets the actionable error first.
+      setTimeout(() => exit('macOS refused a desktop permission'), 1_000).unref();
+    },
+  };
+}

package/src/agent/service.test.ts

@@ -10,6 +10,7 @@ import {
   agentTunnelHome,
   buildServiceShellCommand,
   getServicePaths,
+  installedAppRunner,
   runnerPartsFor,
   serviceLabelFor,
   isEphemeralRunnerPath,
@@ -28,7 +29,32 @@ describe('agent tunnel service definitions', () => {
     const command = buildServiceShellCommand();
     expect(command).toContain("'run'");
     expect(command).toContain("'--service'");
-    expect(command).toStartWith('exec ');
+    // `export …;` first when it runs on the installed Kortix app (ELECTRON_RUN_AS_NODE).
+    expect(command).toMatch(/^(export [^;]+; )?exec /);
+  });
+
+  test('a CLI install on a Mac with the Kortix app runs on the app runtime', () => {
+    const root = mkdtempSync(join(tmpdir(), 'kortix-app-'));
+    try {
+      const app = join(root, 'Kortix.app');
+      expect(installedAppRunner([app], 'darwin')).toBeNull();
+      mkdirSync(join(app, 'Contents', 'MacOS'), { recursive: true });
+      mkdirSync(join(app, 'Contents', 'Resources', 'agent-tunnel'), { recursive: true });
+      writeFileSync(join(app, 'Contents', 'MacOS', 'Kortix'), '');
+      writeFileSync(join(app, 'Contents', 'Resources', 'agent-tunnel', 'agent-cli.js'), '');
+      const runner = installedAppRunner([join(root, 'Missing.app'), app], 'darwin')!;
+      expect(runner).toEqual({
+        execPath: join(app, 'Contents', 'MacOS', 'Kortix'),
+        script: join(app, 'Contents', 'Resources', 'agent-tunnel', 'agent-cli.js'),
+      });
+      expect(installedAppRunner([app], 'linux')).toBeNull();
+      const parts = runnerPartsFor(runner.script, { execPath: runner.execPath, electron: 'installed-app' });
+      expect(parts.command).toBe(runner.execPath);
+      expect(parts.args).toEqual([runner.script, 'run', '--service']);
+      expect(parts.env?.ELECTRON_RUN_AS_NODE).toBe('1');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
   });
 
   test('launchd plist restarts and runs at login', () => {

package/src/agent/service.ts

@@ -1,5 +1,5 @@
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'fs';
-import { platform } from 'os';
+import { homedir, platform } from 'os';
 import { join } from 'path';
 
 import {
@@ -128,6 +128,25 @@ export function runnerPartsFor(
   return { command: runtime.execPath, args: [vendor(script, paths), 'run', '--service'], env };
 }
 
+/**
+ * The Kortix desktop app's own agent runtime, when the app is installed on
+ * this Mac. A CLI install runs on it, so the connection is the same agent
+ * build with the same bundled driver, and macOS grants Accessibility and
+ * Screen Recording to Kortix once for both, never to node or a terminal.
+ */
+export function installedAppRunner(
+  apps: readonly string[] = ['/Applications/Kortix.app', join(homedir(), 'Applications', 'Kortix.app')],
+  os: string = process.platform,
+): { execPath: string; script: string } | null {
+  if (os !== 'darwin') return null;
+  for (const app of apps) {
+    const execPath = join(app, 'Contents', 'MacOS', 'Kortix');
+    const script = join(app, 'Contents', 'Resources', 'agent-tunnel', 'agent-cli.js');
+    if (existsSync(execPath) && existsSync(script)) return { execPath, script };
+  }
+  return null;
+}
+
 /** Where vendorRunner WOULD put the bundle, without copying anything. */
 const plannedRunner = (script: string, paths: ServicePaths) =>
   isEphemeralRunnerPath(script) ? paths.vendoredRunner : script;
@@ -135,6 +154,8 @@ const plannedRunner = (script: string, paths: ServicePaths) =>
 function currentRunnerParts(
   vendor: (script: string, paths: ServicePaths) => string = vendorRunner,
 ): RunnerParts {
+  const app = process.versions.electron ? null : installedAppRunner();
+  if (app) return runnerPartsFor(app.script, { execPath: app.execPath, electron: 'installed-app' }, getServicePaths(), vendor);
   const script = process.argv[1];
   if (script && existsSync(script)) return runnerPartsFor(script, undefined, getServicePaths(), vendor);
   throw new Error(

package/src/agent/state-file.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -29,4 +29,14 @@ describe('agent state file', () => {
       rmSync(join(home, '..'), { recursive: true, force: true });
     }
   });
+
+  test('a writer that died without writing offline reads as offline', () => {
+    const home = mkdtempSync(join(tmpdir(), 'agent-tunnel-state-'));
+    try {
+      writeFileSync(stateFilePath(home), JSON.stringify({ tunnelId: 't', apiUrl: 'u', status: 'online', since: '', agentVersion: '0', pid: 2 ** 22 + 7 }));
+      expect(readAgentState(home)?.status).toBe('offline');
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
 });

package/src/agent/state-file.ts

@@ -48,10 +48,22 @@ export function writeAgentState(
   }
 }
 
+function isAlive(pid: unknown): boolean {
+  if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** The last status the agent wrote. A writer that died without writing `offline` reads as offline. */
 export function readAgentState(home: string = agentTunnelHome()): AgentStateFile | null {
   try {
     const parsed = JSON.parse(readFileSync(stateFilePath(home), 'utf8')) as AgentStateFile;
-    return parsed && typeof parsed === 'object' && typeof parsed.status === 'string' ? parsed : null;
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.status !== 'string') return null;
+    return parsed.status !== 'offline' && !isAlive(parsed.pid) ? { ...parsed, status: 'offline' } : parsed;
   } catch {
     return null;
   }

package/src/index.ts

@@ -9,7 +9,7 @@ export {
   TunnelErrorCode,
   TunnelMethods,
   capabilityForMethod,
-  desktopFeatureForMethod,
+  normalizeDesktopCall,
   isTunnelCapability,
   operationForMethod,
   validateTunnelPermissionScope,

package/src/shared/index.ts

@@ -35,7 +35,7 @@ export type {
 export { TunnelErrorCode, TunnelMethods } from './types';
 export {
   capabilityForMethod,
-  desktopFeatureForMethod,
+  normalizeDesktopCall,
   isTunnelCapability,
   operationForMethod,
   validateTunnelPermissionScope,

package/src/shared/permissions.ts

@@ -19,54 +19,35 @@ export interface PermissionScopeValidationResult {
   sanitized?: Record<string, unknown>;
 }
 
-const DESKTOP_METHOD_FEATURES: Readonly<Record<string, string>> = {
-  'desktop.cua.ensure': 'computer_use',
-  'desktop.cua.start_daemon': 'computer_use',
-  'desktop.cua.status': 'computer_use',
-  'desktop.cua.version': 'computer_use',
-  'desktop.cua.list_tools': 'computer_use',
-  'desktop.cua.describe': 'computer_use',
-  'desktop.cua.bring_to_front': 'windows',
-  'desktop.cua.check_for_update': 'computer_use',
-  'desktop.cua.check_permissions': 'computer_use',
-  'desktop.cua.click': 'mouse',
-  'desktop.cua.double_click': 'mouse',
-  'desktop.cua.drag': 'mouse',
-  'desktop.cua.end_session': 'computer_use',
-  'desktop.cua.get_accessibility_tree': 'accessibility',
-  'desktop.cua.get_agent_cursor_state': 'mouse',
-  'desktop.cua.get_config': 'computer_use',
-  'desktop.cua.get_cursor_position': 'mouse',
-  'desktop.cua.get_recording_state': 'computer_use',
-  'desktop.cua.get_screen_size': 'screenshot',
-  'desktop.cua.get_window_state': 'accessibility',
-  'desktop.cua.hotkey': 'keyboard',
-  'desktop.cua.kill_app': 'apps',
-  'desktop.cua.launch_app': 'apps',
-  'desktop.cua.list_apps': 'apps',
-  'desktop.cua.list_windows': 'windows',
-  'desktop.cua.move_cursor': 'mouse',
-  'desktop.cua.page': 'accessibility',
-  'desktop.cua.press_key': 'keyboard',
-  'desktop.cua.replay_trajectory': 'computer_use',
-  'desktop.cua.right_click': 'mouse',
-  'desktop.cua.scroll': 'keyboard',
-  'desktop.cua.set_agent_cursor_enabled': 'mouse',
-  'desktop.cua.set_agent_cursor_motion': 'mouse',
-  'desktop.cua.set_agent_cursor_style': 'mouse',
-  'desktop.cua.set_config': 'computer_use',
-  'desktop.cua.set_value': 'accessibility',
-  'desktop.cua.start_recording': 'screenshot',
-  'desktop.cua.install_ffmpeg': 'computer_use',
-  'desktop.cua.start_session': 'computer_use',
-  'desktop.cua.stop_recording': 'screenshot',
-  'desktop.cua.type_text': 'keyboard',
-  'desktop.cua.zoom': 'screenshot',
-};
+const CUA_PREFIX = 'desktop.cua.';
 
+/** Every `desktop.cua.<tool>` is the desktop capability: the driver owns the tool list. */
 export function capabilityForMethod(method: string): TunnelCapability | null {
   const capability = (TunnelMethods as Readonly<Record<string, TunnelCapability | null>>)[method];
-  return capability ?? null;
+  if (capability !== undefined) return capability;
+  return method.startsWith(CUA_PREFIX) && method.length > CUA_PREFIX.length ? 'desktop' : null;
+}
+
+/**
+ * `desktop.cua.<tool>` → `desktop.cua.call { tool, args }`. Every agent since
+ * 0.1.0 serves `desktop.cua.call` for any driver tool, so one wire method
+ * reaches every tool the installed driver has, with no per-tool list to keep
+ * in sync. Management methods (`ensure`, `status`, `describe`, …) pass through.
+ */
+export function normalizeDesktopCall(
+  method: string,
+  params: Record<string, unknown>,
+): { method: string; params: Record<string, unknown> } {
+  if (!method.startsWith(CUA_PREFIX) || method in TunnelMethods) return { method, params };
+  const { permissionId, ...args } = params;
+  return {
+    method: 'desktop.cua.call',
+    params: {
+      tool: method.slice(CUA_PREFIX.length),
+      args,
+      ...(permissionId === undefined ? {} : { permissionId }),
+    },
+  };
 }
 
 export function isTunnelCapability(value: string): value is TunnelCapability {
@@ -277,16 +258,3 @@ export function operationForMethod(method: string): string {
   const separator = method.indexOf('.');
   return separator === -1 ? method : method.slice(separator + 1);
 }
-
-export function desktopFeatureForMethod(
-  method: string,
-  args: Record<string, unknown> = {},
-): string | undefined {
-  if (method === 'desktop.cua.call') {
-    const tool = args.tool;
-    if (typeof tool !== 'string' || tool.length === 0) return undefined;
-    const toolMethod = tool.startsWith('desktop.cua.') ? tool : `desktop.cua.${tool}`;
-    return DESKTOP_METHOD_FEATURES[toolMethod];
-  }
-  return DESKTOP_METHOD_FEATURES[method];
-}