@kortix/agent-tunnel 0.14.2 → 0.14.4

package/README.md

@@ -69,7 +69,10 @@ It starts at login, and the supervisor restarts it after every exit (launchd
 `KeepAlive` with a 10 s throttle, systemd `Restart=always`, a 5 s Windows loop).
 On Linux, install enables `loginctl enable-linger` so the user service keeps
 running after logout and starts at boot; when that is not allowed, install
-prints a warning. The Windows task runs hidden, on battery, with no time limit.
+prints a warning. The Windows task runs PowerShell under `conhost --headless`
+(no console window, also where Windows Terminal is the default terminal), on
+battery, with no time limit. Every process the agent starts on Windows sets
+`windowsHide`, so no console window opens.
 The agent itself never stops on its own:
 
 - It reconnects with exponential backoff from 1 s to 30 s, ±20 % jitter, forever.
@@ -184,9 +187,10 @@ change to the agent as `tunnel.access.set`:
 A pairing made from the Kortix desktop app starts in `ask`: the app shows the
 prompt. A pairing made with this CLI alone starts in `always`, because nothing
 on the machine could answer a prompt. This is a deliberate deviation from
-"new pairings default to ask". Every new pairing resets `access.json`, so a
-grant or `always` from an earlier pairing never carries over, and `logout`
-deletes it. The agent home (`config.json`, `access.json`, `desktop-app.json`)
+"new pairings default to ask". The mode and keep awake are the owner's
+machine settings: pairing again (`--reauth`, a rejected or stale credential)
+keeps them, and only a grant or a denial from the earlier pairing is dropped.
+`logout` deletes `access.json`, so the next pairing starts from the default. The agent home (`config.json`, `access.json`, `desktop-app.json`)
 is always a blocked path: no file or shell call can change these files.
 
 The agent reports its state to Kortix as the signed notification
@@ -237,9 +241,16 @@ you trust with this computer.
 
 ## Computer Use driver
 
-Agent Tunnel never downloads or executes a desktop driver. Install `cua-driver`
-locally before enabling Computer Use. The tunnel uses an existing binary from
-`CUA_DRIVER_BIN`, `~/.local/bin`, `/usr/local/bin`, or `/opt/homebrew/bin`.
+Agent Tunnel never downloads or executes a desktop driver. The Kortix desktop
+app bundles `cua-driver` on macOS and Windows (x64), and the agent it runs uses
+that copy. A CLI install uses an existing binary from `CUA_DRIVER_BIN`,
+`~/.local/bin`, `/usr/local/bin`, or `/opt/homebrew/bin`.
+
+An approved `desktop` registers whenever the driver is present. Missing macOS
+grants do not unregister it: the agent reports `desktopPermissions` and the
+setup asks for them. When the driver is missing or rejected (wrong owner,
+group-writable), `desktop` does not register and the reason is reported as
+`unavailableCapabilities.desktop` in `status --json` and in `machineInfo`.
 Treat that binary as trusted local code. Agent Tunnel does not verify or update
 it.
 

package/dist/agent-cli.js

@@ -3521,6 +3521,15 @@ function writePrivateJson(file, home, value) {
 function writeAccess(state, home = agentTunnelHome()) {
   writePrivateJson(accessFilePath(home), home, state);
 }
+function accessAfterPairing(home, desktopApp) {
+  const kept = existsSync2(accessFilePath(home)) ? readAccess(home) : null;
+  return {
+    mode: kept?.mode ?? (desktopApp ? "ask" : "always"),
+    grantedUntil: null,
+    deniedUntil: null,
+    keepAwake: kept?.keepAwake ?? false
+  };
+}
 function decideAccess(state, now = Date.now()) {
   if (state.mode === "always")
     return "run";
@@ -3808,7 +3817,7 @@ function machineDisplayName({
   os = platform2(),
   host = hostname(),
   env = process.env,
-  run = (command, args) => execFileSync(command, args, { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"] })
+  run = (command, args) => execFileSync(command, args, { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"], windowsHide: true })
 } = {}) {
   const fallback = host.replace(/\.local$/i, "") || host;
   try {
@@ -3820,7 +3829,7 @@ function machineDisplayName({
 }
 function machineId({
   os = platform2(),
-  run = (command, args) => execFileSync(command, args, { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }),
+  run = (command, args) => execFileSync(command, args, { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"], windowsHide: true }),
   read = (path) => readFileSync4(path, "utf8")
 } = {}) {
   const attempt = (source) => {
@@ -4465,7 +4474,8 @@ class TunnelAgent {
           osVersion: release(),
           agentVersion: AGENT_VERSION,
           homeDir: this.config.workingDir,
-          allowedPaths: this.config.allowedPaths
+          allowedPaths: this.config.allowedPaths,
+          unavailableCapabilities: Object.fromEntries(this.registry.unavailable)
         }
       }
     });
@@ -4590,7 +4600,7 @@ class TunnelAgent {
     const blocker = keepAwakeCommand(platform3(), process.pid);
     if (!blocker)
       return;
-    const child = spawn3(blocker.command, blocker.args, { stdio: "ignore" });
+    const child = spawn3(blocker.command, blocker.args, { stdio: "ignore", windowsHide: true });
     child.on("error", () => {
       this.keepAwakeFailed = true;
       log(`${c.yellow}!${c.reset}`, `Keep awake is unavailable: ${blocker.command} could not start`);
@@ -4758,6 +4768,7 @@ async function printStartupBanner({
 // src/agent/capabilities/index.ts
 class CapabilityRegistry {
   capabilities = new Map;
+  unavailable = new Map;
   register(capability) {
     this.capabilities.set(capability.name, capability);
   }
@@ -4783,7 +4794,7 @@ class CapabilityRegistry {
 // src/agent/capabilities/desktop/cua-driver.ts
 import { spawn as spawn4 } from "child_process";
 import { existsSync as existsSync3, readFileSync as readFileSync6, realpathSync, rmSync as rmSync2, statSync as statSync2 } from "fs";
-import { homedir as homedir3, platform as platform5, tmpdir } from "os";
+import { homedir as homedir3, platform as platform5, tmpdir, userInfo } from "os";
 import { basename as basename2, dirname as dirname3, join as join5 } from "path";
 var MAX_DRIVER_OUTPUT_BYTES = 5 * 1024 * 1024;
 var DRIVER_ENV_KEYS = [
@@ -4798,7 +4809,19 @@ var DRIVER_ENV_KEYS = [
   "WAYLAND_DISPLAY",
   "XDG_RUNTIME_DIR",
   "XAUTHORITY",
-  "DBUS_SESSION_BUS_ADDRESS"
+  "DBUS_SESSION_BUS_ADDRESS",
+  "SystemRoot",
+  "windir",
+  "USERPROFILE",
+  "USERNAME",
+  "USERDOMAIN",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "ProgramData",
+  "TEMP",
+  "TMP",
+  "ComSpec",
+  "PATHEXT"
 ];
 function driverEnvironment(extra = {}) {
   const env = { CUA_DRIVER_RS_TELEMETRY_ENABLED: "0" };
@@ -4861,7 +4884,8 @@ function execFile(cmd, args, timeoutMs = 30000, env = driverEnvironment()) {
   return new Promise((resolve, reject) => {
     const proc = spawn4(cmd, args, {
       stdio: ["ignore", "pipe", "pipe"],
-      env
+      env,
+      windowsHide: true
     });
     let stdout = "";
     let stderr = "";
@@ -4948,9 +4972,8 @@ class CuaDriver {
   constructor(options = {}) {
     this.binary = options.binary ?? null;
     this.embedded = options.embedded;
-    const uid = typeof process.getuid === "function" ? process.getuid() : "user";
     const home = serviceLabelFor(agentTunnelHome()).slice(SERVICE_LABEL.length);
-    this.socketPath = options.socketPath ?? join5(tmpdir(), `kortix-cua-${uid}${home}.sock`);
+    this.socketPath = options.socketPath ?? (process.platform === "win32" ? `\\\\.\\pipe\\kortix-cua-${userInfo().username}${home}` : join5(tmpdir(), `kortix-cua-${typeof process.getuid === "function" ? process.getuid() : "user"}${home}.sock`));
     this.hostBundleId = options.hostBundleId;
   }
   isEmbedded(binary) {
@@ -4959,10 +4982,11 @@ class CuaDriver {
   mode(binary) {
     if (!this.isEmbedded(binary))
       return { env: driverEnvironment(), socket: [] };
+    const bundleId = this.hostBundleId ?? hostBundleId();
     return {
       env: driverEnvironment({
         CUA_DRIVER_EMBEDDED: "1",
-        CUA_DRIVER_HOST_BUNDLE_ID: this.hostBundleId ?? hostBundleId()
+        ...bundleId ? { CUA_DRIVER_HOST_BUNDLE_ID: bundleId } : {}
       }),
       socket: ["--socket", this.socketPath]
     };
@@ -5036,7 +5060,8 @@ class CuaDriver {
       const child = spawn4("open", ["-n", "-g", "-a", "CuaDriver", "--args", "serve"], {
         detached: true,
         stdio: "ignore",
-        env: driverEnvironment()
+        env: driverEnvironment(),
+        windowsHide: true
       });
       child.unref();
       await sleep2(750);
@@ -5044,7 +5069,8 @@ class CuaDriver {
       const child = spawn4(bin, ["serve"], {
         detached: true,
         stdio: "ignore",
-        env: driverEnvironment()
+        env: driverEnvironment(),
+        windowsHide: true
       });
       child.unref();
       await sleep2(750);
@@ -5061,7 +5087,11 @@ class CuaDriver {
     if (this.daemon && this.daemon.exitCode === null)
       return;
     const { env, socket } = this.mode(bin);
-    if (existsSync3(this.socketPath)) {
+    if (process.platform === "win32") {
+      await execFile(bin, ["stop", ...socket], 1e4, env).catch(() => {
+        return;
+      });
+    } else if (existsSync3(this.socketPath)) {
       await execFile(bin, ["stop", ...socket], 1e4, env).catch(() => {
         return;
       });
@@ -5069,7 +5099,8 @@ class CuaDriver {
     }
     const child = spawn4(bin, ["serve", "--embedded", "--no-permissions-gate", ...socket], {
       stdio: "ignore",
-      env
+      env,
+      windowsHide: true
     });
     child.unref();
     child.on("exit", () => {
@@ -5080,16 +5111,23 @@ class CuaDriver {
     });
     this.daemon = child;
     process.once("exit", () => child.kill());
-    for (let waited = 0;waited < 1e4 && !existsSync3(this.socketPath); waited += 50) {
+    const started = Date.now();
+    while (Date.now() - started < 1e4 && !await this.endpointUp(bin)) {
       if (child.exitCode !== null)
         break;
       await sleep2(50);
     }
-    if (!existsSync3(this.socketPath)) {
+    if (!await this.endpointUp(bin)) {
       child.kill();
       throw new Error("cua-driver did not start (no socket after 10 s)");
     }
   }
+  async endpointUp(bin) {
+    if (process.platform !== "win32")
+      return existsSync3(this.socketPath);
+    const { env, socket } = this.mode(bin);
+    return execFile(bin, ["status", ...socket], 5000, env).then(({ stdout }) => !/not\s+running|unhealthy/i.test(stdout), () => false);
+  }
   async permissionOwner() {
     return this.isEmbedded(await this.ensureInstalled()) ? "Kortix" : "CuaDriver";
   }
@@ -5110,7 +5148,7 @@ class CuaDriver {
   async ensureDaemonReady() {
     const bin = await this.ensureInstalled();
     if (this.isEmbedded(bin)) {
-      if (this.daemon?.exitCode === null && existsSync3(this.socketPath))
+      if (this.daemon?.exitCode === null && (process.platform === "win32" ? this.daemonReady : existsSync3(this.socketPath)))
         return;
       this.stop();
       await this.startDaemon();
@@ -5556,7 +5594,8 @@ function createShellCapability(config) {
         cwd,
         shell: false,
         timeout,
-        env: safeEnv
+        env: safeEnv,
+        windowsHide: true
       });
       let stdout = "";
       let stderr = "";
@@ -5612,6 +5651,14 @@ function createShellCapability(config) {
 }
 
 // src/agent/capabilities/enabled-registry.ts
+var DRIVER_NOT_FOUND = "cua-driver was not found. The Kortix desktop app bundles it on macOS and Windows; a CLI install needs it in CUA_DRIVER_BIN, ~/.local/bin, /usr/local/bin or /opt/homebrew/bin.";
+function desktopUnavailableReason(findDesktopDriver = findCuaDriverBinary) {
+  try {
+    return findDesktopDriver() ? null : DRIVER_NOT_FOUND;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
 function createEnabledCapabilityRegistry(config, findDesktopDriver = findCuaDriverBinary, desktop = {}) {
   const registry = new CapabilityRegistry;
   const enabled = new Set(config.enabledCapabilities ?? ["filesystem", "shell", "desktop"]);
@@ -5619,8 +5666,12 @@ function createEnabledCapabilityRegistry(config, findDesktopDriver = findCuaDriv
     registry.register(createFilesystemCapability(config));
   if (enabled.has("shell"))
     registry.register(createShellCapability(config));
-  if (enabled.has("desktop") && findDesktopDriver()) {
-    registry.register(createDesktopCapability(desktop));
+  if (enabled.has("desktop")) {
+    const reason = desktopUnavailableReason(findDesktopDriver);
+    if (reason)
+      registry.unavailable.set("desktop", reason);
+    else
+      registry.register(createDesktopCapability(desktop));
   }
   return registry;
 }
@@ -5769,7 +5820,7 @@ import { join as join10 } from "path";
 // src/agent/service-drivers.ts
 import { spawnSync } from "child_process";
 import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync8, rmSync as rmSync4, writeFileSync as writeFileSync4 } from "fs";
-import { homedir as homedir4, platform as platform6, userInfo } from "os";
+import { homedir as homedir4, platform as platform6, userInfo as userInfo2 } from "os";
 import { dirname as dirname6, join as join9 } from "path";
 
 // src/agent/service-quoting.ts
@@ -5792,7 +5843,7 @@ function posixShellCommand(runner) {
 }
 var supervisor = {
   run(command, args) {
-    const result = spawnSync(command, args, { encoding: "utf8" });
+    const result = spawnSync(command, args, { encoding: "utf8", windowsHide: true });
     return {
       ok: result.status === 0,
       detail: [result.stdout, result.stderr].filter(Boolean).join(`
@@ -5810,7 +5861,7 @@ function joinDetails(...results) {
 `);
 }
 function launchdTarget() {
-  const uid = typeof process.getuid === "function" ? process.getuid() : userInfo().uid;
+  const uid = typeof process.getuid === "function" ? process.getuid() : userInfo2().uid;
   return `gui/${uid}`;
 }
 function logPaths(paths) {
@@ -5883,7 +5934,8 @@ function renderWindowsPowerShellScript(runner) {
   const args = runner.args.map(powershellQuote).join(" ");
   const env = Object.entries(runner.env ?? {}).map(([key, value]) => `$env:${key} = ${powershellQuote(value)}
 `).join("");
-  return `$ErrorActionPreference = 'Continue'
+  return `# Run by the Kortix task under conhost --headless: no console window.
+$ErrorActionPreference = 'Continue'
 ${env}while ($true) {
   # The pipe makes PowerShell wait for a GUI-subsystem binary (the desktop
   # app's Kortix.exe) and set $LASTEXITCODE; a bare call returns at once.
@@ -5943,7 +5995,7 @@ var launchd = {
   },
   status(paths, installed) {
     const disabled = run("launchctl", ["print-disabled", launchdTarget()]);
-    const enabled = !new RegExp(`"${paths.label.replace(/\./g, "\\.")}" => (disabled|true)`).test(disabled.detail);
+    const enabled = ![`"${paths.label}" => disabled`, `"${paths.label}" => true`].some((line) => disabled.detail.includes(line));
     const status = run("launchctl", ["print", `${launchdTarget()}/${paths.label}`]);
     return {
       active: status.ok,
@@ -5998,7 +6050,7 @@ var systemd = {
   }
 };
 function ensureLinger() {
-  const user = userInfo().username;
+  const user = userInfo2().username;
   const linger = run("loginctl", ["show-user", user, "-p", "Linger"]);
   if (/Linger=yes/.test(linger.detail))
     return { ok: true, detail: "" };
@@ -6023,11 +6075,11 @@ function renderWindowsTaskXml(paths, user) {
     <StartWhenAvailable>true</StartWhenAvailable>
     <Enabled>true</Enabled>
   </Settings>
-  <Actions Context="Author"><Exec><Command>powershell.exe</Command><Arguments>${xmlEscape(`-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${paths.windowsScript}"`)}</Arguments></Exec></Actions>
+  <Actions Context="Author"><Exec><Command>conhost.exe</Command><Arguments>${xmlEscape(`--headless powershell.exe -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${paths.windowsScript}"`)}</Arguments></Exec></Actions>
 </Task>
 `;
 }
-var windowsUser = () => process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${userInfo().username}` : userInfo().username;
+var windowsUser = () => process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${userInfo2().username}` : userInfo2().username;
 var windowsTaskXmlPath = (paths) => paths.windowsScript.replace(/\.ps1$/, ".xml");
 var scheduledTask = {
   unitPath: (paths) => paths.windowsScript,
@@ -6391,9 +6443,9 @@ function startAgent(config, options = {}) {
   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.");
-  }
+  const desktopReason = registry.unavailable.get("desktop");
+  if (desktopReason)
+    console.error(`[agent-tunnel] Computer Use is approved but unavailable: ${desktopReason}`);
   if (options.service) {
     process.stdout.write(`[agent-tunnel] service starting: ${config.tunnelId} -> ${config.apiUrl}
 `);
@@ -6530,12 +6582,7 @@ async function pairThisMachine(apiUrl, flags, lease) {
     process.exit(1);
   }
   saveCredentials(outcome.tunnelId, outcome.token, apiUrl, outcome.capabilities);
-  writeAccess({
-    mode: existsSync7(desktopAppPath()) ? "ask" : "always",
-    grantedUntil: null,
-    deniedUntil: null,
-    keepAwake: readAccess().keepAwake
-  });
+  writeAccess(accessAfterPairing(agentTunnelHome(), existsSync7(desktopAppPath())));
   if (jsonMode) {
     emit("approved", { tunnelId: outcome.tunnelId, capabilities: outcome.capabilities });
   } else {
@@ -6642,12 +6689,14 @@ function commandStatus(flags) {
   const service = getServiceStatus();
   const paired = Boolean(config.token && config.tunnelId);
   const approved = new Set(config.enabledCapabilities ?? []);
+  const desktopReason = approved.has("desktop") ? desktopUnavailableReason() : null;
   if (isTruthyFlag(flags.json)) {
     console.log(JSON.stringify({
       paired,
       tunnelId: paired ? config.tunnelId : null,
       apiUrl: config.apiUrl,
       capabilities: [...approved],
+      unavailableCapabilities: desktopReason ? { desktop: desktopReason } : {},
       version: agentTunnelVersion(),
       home: agentTunnelHome(),
       serviceLabel: getServicePaths().label,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kortix-ai/suna.git",
@@ -38,12 +38,6 @@
     "hono": "^4.13.7",
     "ws": "^8.18.0"
   },
-  "devDependencies": {
-    "@types/bun": "^1.3.9",
-    "@types/ws": "^8.5.13",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "typescript": "^5.4.0"
-  },
   "keywords": [
     "tunnel",
     "relay",

package/src/agent/access.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 
 import {
   ACCESS_HOLD_MS,
+  accessAfterPairing,
   accessCommand,
   accessFilePath,
   accessView,
@@ -251,3 +252,23 @@ describe('the access rules (one copy: the CLI, the agent, and the desktop app al
     expect(readAccess(home).deniedUntil).not.toBeNull();
   });
 });
+
+describe('access after pairing', () => {
+  test('a re-pair keeps the owner mode and keep awake, and drops the old grant or denial', () => {
+    const home = tempHome();
+    writeFileSync(
+      accessFilePath(home),
+      JSON.stringify({ mode: 'always', grantedUntil: null, deniedUntil: '2099-01-01T00:00:00.000Z', keepAwake: true }),
+    );
+    expect(accessAfterPairing(home, true)).toEqual({ mode: 'always', grantedUntil: null, deniedUntil: null, keepAwake: true });
+    writeFileSync(accessFilePath(home), JSON.stringify({ mode: 'off', grantedUntil: null, deniedUntil: null, keepAwake: false }));
+    expect(accessAfterPairing(home, false).mode).toBe('off');
+    writeFileSync(accessFilePath(home), JSON.stringify({ mode: 'ask', grantedUntil: '2099-01-01T00:00:00.000Z', deniedUntil: null, keepAwake: false }));
+    expect(accessAfterPairing(home, false)).toEqual({ mode: 'ask', grantedUntil: null, deniedUntil: null, keepAwake: false });
+  });
+
+  test('a first pairing asks when the desktop app can answer, else always', () => {
+    expect(accessAfterPairing(tempHome(), true).mode).toBe('ask');
+    expect(accessAfterPairing(tempHome(), false).mode).toBe('always');
+  });
+});

package/src/agent/access.ts

@@ -110,6 +110,23 @@ export function writeAccess(state: AccessState, home = agentTunnelHome()): void
   writePrivateJson(accessFilePath(home), home, state);
 }
 
+/**
+ * A1: the access a pairing starts with. The owner's mode (and keep awake) is
+ * a machine setting: a re-pair (`--reauth`, a rejected token, a stale
+ * connection) keeps it. A grant or denial belongs to the old pairing and does
+ * not carry over. Only a first pairing (no access.json, e.g. after `logout`)
+ * picks a default: `ask` when the desktop app can answer a prompt, else `always`.
+ */
+export function accessAfterPairing(home: string, desktopApp: boolean): AccessState {
+  const kept = existsSync(accessFilePath(home)) ? readAccess(home) : null;
+  return {
+    mode: kept?.mode ?? (desktopApp ? 'ask' : 'always'),
+    grantedUntil: null,
+    deniedUntil: null,
+    keepAwake: kept?.keepAwake ?? false,
+  };
+}
+
 export type AccessDecision = 'run' | 'off' | 'denied' | 'ask';
 
 export function decideAccess(state: AccessState, now = Date.now()): AccessDecision {

package/src/agent/agent.ts

@@ -638,6 +638,9 @@ export class TunnelAgent {
           // the right place instead of probing paths the local ceiling denies.
           homeDir: this.config.workingDir,
           allowedPaths: this.config.allowedPaths,
+          // Approved capabilities this machine cannot run, and why. Always
+          // sent, so a fixed machine clears the stored reason.
+          unavailableCapabilities: Object.fromEntries(this.registry.unavailable),
         },
       },
     });
@@ -793,7 +796,7 @@ export class TunnelAgent {
     if (this.keepAwake || this.keepAwakeFailed) return;
     const blocker = keepAwakeCommand(platform(), process.pid);
     if (!blocker) return;
-    const child = spawn(blocker.command, blocker.args, { stdio: 'ignore' });
+    const child = spawn(blocker.command, blocker.args, { stdio: 'ignore', windowsHide: true });
     child.on('error', () => {
       this.keepAwakeFailed = true;
       log(`${c.yellow}!${c.reset}`, `Keep awake is unavailable: ${blocker.command} could not start`);

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

@@ -1,6 +1,6 @@
 import { spawn, type ChildProcess } from 'child_process';
 import { existsSync, readFileSync, realpathSync, rmSync, statSync } from 'fs';
-import { homedir, platform, tmpdir } from 'os';
+import { homedir, platform, tmpdir, userInfo } from 'os';
 import { basename, dirname, join } from 'path';
 import { agentTunnelHome, serviceLabelFor, SERVICE_LABEL } from '../../service-paths';
 
@@ -23,6 +23,20 @@ const DRIVER_ENV_KEYS = [
   'XDG_RUNTIME_DIR',
   'XAUTHORITY',
   'DBUS_SESSION_BUS_ADDRESS',
+  // Windows: without these a Rust binary cannot start COM, Winsock, or UI
+  // Automation, and finds no profile or temp directory.
+  'SystemRoot',
+  'windir',
+  'USERPROFILE',
+  'USERNAME',
+  'USERDOMAIN',
+  'APPDATA',
+  'LOCALAPPDATA',
+  'ProgramData',
+  'TEMP',
+  'TMP',
+  'ComSpec',
+  'PATHEXT',
 ] as const;
 
 /** The driver's own product telemetry stays off on a customer's machine. */
@@ -111,6 +125,7 @@ function execFile(
     const proc = spawn(cmd, args, {
       stdio: ['ignore', 'pipe', 'pipe'],
       env,
+      windowsHide: true,
     });
     let stdout = '';
     let stderr = '';
@@ -232,11 +247,15 @@ export class CuaDriver {
   constructor(options: CuaDriverOptions = {}) {
     this.binary = options.binary ?? null;
     this.embedded = options.embedded;
-    const uid = typeof process.getuid === 'function' ? process.getuid() : 'user';
     // 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.
+    // or steal a driver. Under $TMPDIR: a socket path is capped at 104 bytes on
+    // macOS. Windows: the driver listens on a named pipe, one per user.
     const home = serviceLabelFor(agentTunnelHome()).slice(SERVICE_LABEL.length);
-    this.socketPath = options.socketPath ?? join(tmpdir(), `kortix-cua-${uid}${home}.sock`);
+    this.socketPath =
+      options.socketPath ??
+      (process.platform === 'win32'
+        ? `\\\\.\\pipe\\kortix-cua-${userInfo().username}${home}`
+        : join(tmpdir(), `kortix-cua-${typeof process.getuid === 'function' ? process.getuid() : 'user'}${home}.sock`));
     this.hostBundleId = options.hostBundleId;
   }
 
@@ -247,10 +266,12 @@ export class CuaDriver {
   /** Environment and trailing arguments every driver command needs in this mode. */
   private mode(binary: string): { env: NodeJS.ProcessEnv; socket: string[] } {
     if (!this.isEmbedded(binary)) return { env: driverEnvironment(), socket: [] };
+    // macOS only: a Windows or Linux host has no bundle id.
+    const bundleId = this.hostBundleId ?? hostBundleId();
     return {
       env: driverEnvironment({
         CUA_DRIVER_EMBEDDED: '1',
-        CUA_DRIVER_HOST_BUNDLE_ID: this.hostBundleId ?? hostBundleId(),
+        ...(bundleId ? { CUA_DRIVER_HOST_BUNDLE_ID: bundleId } : {}),
       }),
       socket: ['--socket', this.socketPath],
     };
@@ -337,6 +358,7 @@ export class CuaDriver {
         detached: true,
         stdio: 'ignore',
         env: driverEnvironment(),
+        windowsHide: true,
       });
       child.unref();
       await sleep(750);
@@ -345,6 +367,7 @@ export class CuaDriver {
         detached: true,
         stdio: 'ignore',
         env: driverEnvironment(),
+        windowsHide: true,
       });
       child.unref();
       await sleep(750);
@@ -370,13 +393,17 @@ export class CuaDriver {
     // 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)) {
+    // A Windows named pipe is no file: always ask, it goes away with its server.
+    if (process.platform === 'win32') {
+      await execFile(bin, ['stop', ...socket], 10_000, env).catch(() => undefined);
+    } else 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,
+      windowsHide: true,
     });
     child.unref();
     child.on('exit', () => {
@@ -387,16 +414,27 @@ export class CuaDriver {
     });
     this.daemon = child;
     process.once('exit', () => child.kill());
-    for (let waited = 0; waited < 10_000 && !existsSync(this.socketPath); waited += 50) {
+    const started = Date.now();
+    while (Date.now() - started < 10_000 && !(await this.endpointUp(bin))) {
       if (child.exitCode !== null) break;
       await sleep(50);
     }
-    if (!existsSync(this.socketPath)) {
+    if (!(await this.endpointUp(bin))) {
       child.kill();
       throw new Error('cua-driver did not start (no socket after 10 s)');
     }
   }
 
+  /** The daemon endpoint answers: a Unix socket is a file, a Windows named pipe is asked. */
+  private async endpointUp(bin: string): Promise<boolean> {
+    if (process.platform !== 'win32') return existsSync(this.socketPath);
+    const { env, socket } = this.mode(bin);
+    return execFile(bin, ['status', ...socket], 5_000, env).then(
+      ({ stdout }) => !/not\s+running|unhealthy/i.test(stdout),
+      () => false,
+    );
+  }
+
   /**
    * The macOS grants the driver reports missing for its permission owner:
    * Kortix when embedded, CuaDriver otherwise. Empty when nothing is missing
@@ -426,7 +464,7 @@ export class CuaDriver {
     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;
+      if (this.daemon?.exitCode === null && (process.platform === 'win32' ? this.daemonReady : existsSync(this.socketPath))) return;
       this.stop();
       await this.startDaemon();
       return;

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

@@ -5,6 +5,23 @@ import { findCuaDriverBinary } from './desktop/cua-driver';
 import { createFilesystemCapability } from './filesystem';
 import { createShellCapability } from './shell';
 
+const DRIVER_NOT_FOUND =
+  'cua-driver was not found. The Kortix desktop app bundles it on macOS and Windows; a CLI install needs it in CUA_DRIVER_BIN, ~/.local/bin, /usr/local/bin or /opt/homebrew/bin.';
+
+/**
+ * Why Computer Use cannot run here, or null when the trusted local driver is
+ * present. Never throws: a rejected driver is a reason, not an agent crash.
+ * Missing macOS grants are not a reason: the capability registers and the
+ * agent reports `desktopPermissions`, which drive the setup.
+ */
+export function desktopUnavailableReason(findDesktopDriver: () => string | null = findCuaDriverBinary): string | null {
+  try {
+    return findDesktopDriver() ? null : DRIVER_NOT_FOUND;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
 /** Build the local RPC surface from the browser-approved capability ceiling. */
 export function createEnabledCapabilityRegistry(
   config: TunnelConfig,
@@ -15,11 +32,12 @@ export function createEnabledCapabilityRegistry(
   const enabled = new Set(config.enabledCapabilities ?? ['filesystem', 'shell', 'desktop']);
   if (enabled.has('filesystem')) registry.register(createFilesystemCapability(config));
   if (enabled.has('shell')) registry.register(createShellCapability(config));
-  // Do not advertise Computer Use unless this process can execute the trusted
-  // 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(desktop));
+  // Advertise Computer Use only when this process can execute the trusted
+  // local driver; otherwise record why, so Kortix shows the reason.
+  if (enabled.has('desktop')) {
+    const reason = desktopUnavailableReason(findDesktopDriver);
+    if (reason) registry.unavailable.set('desktop', reason);
+    else registry.register(createDesktopCapability(desktop));
   }
   return registry;
 }

package/src/agent/capabilities/index.ts

@@ -15,6 +15,8 @@ export interface Capability {
 
 export class CapabilityRegistry {
   private capabilities = new Map<string, Capability>();
+  /** Approved capabilities this machine cannot run, with the reason. */
+  readonly unavailable = new Map<string, string>();
 
   register(capability: Capability): void {
     this.capabilities.set(capability.name, capability);

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

@@ -64,6 +64,18 @@ describe('local capability permission enforcement', () => {
     );
     expect(registry.getCapabilityNames()).toEqual([]);
     expect(registry.getHandler('desktop.cua.get_screen_size')).toBeNull();
+    expect(registry.unavailable.get('desktop')).toContain('cua-driver was not found');
+  });
+
+  test('a rejected driver is reported as the reason, not thrown', () => {
+    const registry = createEnabledCapabilityRegistry(
+      { ...config(), enabledCapabilities: ['filesystem', 'desktop'] },
+      () => {
+        throw new Error('cua-driver is not owned by the current user or root: /x/cua-driver');
+      },
+    );
+    expect(registry.getCapabilityNames()).toEqual(['filesystem']);
+    expect(registry.unavailable.get('desktop')).toBe('cua-driver is not owned by the current user or root: /x/cua-driver');
   });
 
   test('desktop is advertised when a trusted local driver exists', () => {
@@ -73,7 +85,9 @@ describe('local capability permission enforcement', () => {
     );
     expect(registry.getCapabilityNames()).toEqual(['desktop']);
     expect(registry.getHandler('desktop.cua.call')).not.toBeNull();
+    expect(registry.unavailable.size).toBe(0);
   });
+
   test('a permission scope cannot widen the local filesystem ceiling', async () => {
     const handler = createFilesystemCapability(config()).methods.get('fs.read')!;
     await expect(

package/src/agent/capabilities/shell.ts

@@ -79,6 +79,7 @@ export function createShellCapability(config: TunnelConfig): Capability {
         shell: false,
         timeout,
         env: safeEnv,
+        windowsHide: true,
       });
 
       let stdout = '';

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

@@ -256,7 +256,7 @@ describe('agent tunnel connect re-authorization', () => {
     expect(JSON.parse(await readFile(configPath, 'utf8')).token).toBeUndefined();
   }, 30_000);
 
-  test('a new pairing from the desktop app asks before every use and never inherits the previous grant (A1)', async () => {
+  test('a first pairing from the desktop app asks; a re-pair keeps the owner mode and drops the old grant (A1)', async () => {
     const relay = startRejectingRelay({ serveDeviceAuth: true });
     const apiUrl = `http://127.0.0.1:${relay.server.port}/v1/tunnel`;
     const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-access-default-'));
@@ -279,8 +279,8 @@ describe('agent tunnel connect re-authorization', () => {
         if (!second.out().includes('Authorized')) throw new Error('not yet');
       });
       second.child.kill('SIGTERM');
-      // Keep awake is a machine setting and stays; the answer resets with the pairing.
-      expect(JSON.parse(await readFile(accessPath, 'utf8'))).toEqual({ mode: 'ask', grantedUntil: null, deniedUntil: null, keepAwake: true });
+      // The mode and keep awake are the owner's machine settings and stay; the grant resets with the pairing.
+      expect(JSON.parse(await readFile(accessPath, 'utf8'))).toEqual({ mode: 'always', grantedUntil: null, deniedUntil: null, keepAwake: true });
     } finally {
       relay.server.stop(true);
     }

package/src/agent/cli.ts

@@ -5,6 +5,7 @@ import { join } from 'path';
 
 import { PAIR_AGAIN_COMMAND, TunnelAgent } from './agent';
 import {
+  accessAfterPairing,
   accessFilePath,
   accessRequestPath,
   accessView,
@@ -16,7 +17,7 @@ import {
   type AccessView,
 } from './access';
 import { printStartupBanner } from './banner';
-import { createEnabledCapabilityRegistry } from './capabilities/enabled-registry';
+import { createEnabledCapabilityRegistry, desktopUnavailableReason } from './capabilities/enabled-registry';
 import { loadConfig, type TunnelConfig } from './config';
 import { CONFIG_FILE, clearSavedCredentials, saveCredentials } from './credential-store';
 import { probeCredentials } from './credential-probe';
@@ -118,11 +119,8 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
   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.',
-    );
-  }
+  const desktopReason = registry.unavailable.get('desktop');
+  if (desktopReason) console.error(`[agent-tunnel] Computer Use is approved but unavailable: ${desktopReason}`);
 
   if (options.service) {
     process.stdout.write(`[agent-tunnel] service starting: ${config.tunnelId} -> ${config.apiUrl}\n`);
@@ -288,17 +286,9 @@ async function pairThisMachine(apiUrl: string, flags: Flags, lease?: { serviceWa
   }
 
   saveCredentials(outcome.tunnelId, outcome.token, apiUrl, outcome.capabilities);
-  // A1: a pairing made from the desktop app asks before each use; the app is
-  // what answers. A CLI-only machine has nobody to answer a prompt, so it is
-  // always allowed (a documented deviation from A1). A new pairing never
-  // inherits a grant or an `always` from the previous one; keep awake is a
-  // machine setting and stays.
-  writeAccess({
-    mode: existsSync(desktopAppPath()) ? 'ask' : 'always',
-    grantedUntil: null,
-    deniedUntil: null,
-    keepAwake: readAccess().keepAwake,
-  });
+  // A1: a re-pair keeps the owner's mode; a first pairing asks when the
+  // desktop app can answer, else always (see accessAfterPairing).
+  writeAccess(accessAfterPairing(agentTunnelHome(), existsSync(desktopAppPath())));
   if (jsonMode) {
     emit('approved', { tunnelId: outcome.tunnelId, capabilities: outcome.capabilities });
   } else {
@@ -436,6 +426,7 @@ function commandStatus(flags: Flags): void {
   const service = getServiceStatus();
   const paired = Boolean(config.token && config.tunnelId);
   const approved = new Set(config.enabledCapabilities ?? []);
+  const desktopReason = approved.has('desktop') ? desktopUnavailableReason() : null;
 
   if (isTruthyFlag(flags.json)) {
     console.log(JSON.stringify({
@@ -443,6 +434,7 @@ function commandStatus(flags: Flags): void {
       tunnelId: paired ? config.tunnelId : null,
       apiUrl: config.apiUrl,
       capabilities: [...approved],
+      unavailableCapabilities: desktopReason ? { desktop: desktopReason } : {},
       version: agentTunnelVersion(),
       home: agentTunnelHome(),
       serviceLabel: getServicePaths().label,

package/src/agent/device-auth.ts

@@ -153,7 +153,7 @@ export function machineDisplayName({
   host = hostname(),
   env = process.env,
   run = (command: string, args: string[]) =>
-    execFileSync(command, args, { encoding: 'utf8', timeout: 1_000, stdio: ['ignore', 'pipe', 'ignore'] }),
+    execFileSync(command, args, { encoding: 'utf8', timeout: 1_000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }),
 }: {
   os?: string;
   host?: string;
@@ -180,7 +180,7 @@ export function machineDisplayName({
 export function machineId({
   os = platform(),
   run = (command: string, args: string[]) =>
-    execFileSync(command, args, { encoding: 'utf8', timeout: 2_000, stdio: ['ignore', 'pipe', 'ignore'] }),
+    execFileSync(command, args, { encoding: 'utf8', timeout: 2_000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }),
   read = (path: string) => readFileSync(path, 'utf8'),
 }: {
   os?: string;

package/src/agent/prompts.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from 'bun:test';
+import { anyFlag, isTruthyFlag } from './prompts';
+
+test('flags accept only the existing lowercase truthy values', () => {
+  for (const value of ['true', '1', 'yes']) expect(isTruthyFlag(value)).toBe(true);
+  for (const value of [undefined, '', 'false', '0', 'no', 'TRUE', ' yes ']) {
+    expect(isTruthyFlag(value)).toBe(false);
+  }
+  expect(anyFlag({ yes: 'yes', no: 'false' }, ['missing', 'no', 'yes'])).toBe(true);
+  expect(anyFlag({ yes: 'yes', no: 'false' }, ['missing', 'no'])).toBe(false);
+  expect(anyFlag({ yes: 'yes' }, [])).toBe(false);
+});

package/src/agent/prompts.ts

@@ -1,6 +1,3 @@
-import { createInterface } from 'readline/promises';
-import { c } from './terminal';
-
 export function isInteractiveTerminal(): boolean {
   return process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
@@ -13,25 +10,3 @@ export function isTruthyFlag(value: string | undefined): boolean {
 export function anyFlag(flags: Record<string, string>, names: readonly string[]): boolean {
   return names.some((name) => isTruthyFlag(flags[name]));
 }
-
-export async function promptYesNo(question: string, defaultValue: boolean): Promise<boolean> {
-  const suffix = defaultValue ? ' [Y/n] ' : ' [y/N] ';
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    for (;;) {
-      const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase();
-      if (!answer) return defaultValue;
-      if (['y', 'yes'].includes(answer)) return true;
-      if (['n', 'no'].includes(answer)) return false;
-      console.log(`  ${c.yellow}!${c.reset} Please answer yes or no.`);
-    }
-  } catch (error) {
-    if (error instanceof Error && error.name === 'AbortError') {
-      process.stdout.write('\n');
-      process.exit(130);
-    }
-    throw error;
-  } finally {
-    rl.close();
-  }
-}

package/src/agent/service-drivers.test.ts

@@ -65,6 +65,14 @@ describe('durable pause (R3)', () => {
     expect(uid).toBeGreaterThanOrEqual(0);
   });
 
+  test('launchd: status matches the label literally, regex characters included', () => {
+    const odd = { ...paths, label: 'com.kortix.a+b(1)\\x' };
+    recordCommands({ 'launchctl print-disabled': { ok: true, detail: `"${odd.label}" => true` } });
+    expect(serviceDriverFor('darwin')!.status(odd, false).enabled).toBe(false);
+    recordCommands({ 'launchctl print-disabled': { ok: true, detail: `"comXkortix.a+b(1)\\x" => disabled` } });
+    expect(serviceDriverFor('darwin')!.status(odd, false).enabled).toBe(true);
+  });
+
   test('systemd: pause is disable --now; resume is enable --now', () => {
     const calls = recordCommands();
     serviceDriverFor('linux')!.pause(paths, true);
@@ -148,6 +156,7 @@ describe('install really starts the service', () => {
       expect(xml).toContain('<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>');
       expect(xml).toContain('<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>');
       expect(xml).toContain('<ExecutionTimeLimit>PT0S</ExecutionTimeLimit>');
+      expect(xml).toContain('<Command>conhost.exe</Command><Arguments>--headless powershell.exe ');
       expect(xml).toContain('-WindowStyle Hidden');
       expect(renderWindowsTaskXml(paths, 'DOMAIN\\a&b')).toContain('<UserId>DOMAIN\\a&amp;b</UserId>');
     } finally {

package/src/agent/service-drivers.ts

@@ -73,7 +73,7 @@ interface CommandResult {
 /** The one place a supervisor command runs. Replaced in tests. */
 export const supervisor = {
   run(command: string, args: string[]): CommandResult {
-    const result = spawnSync(command, args, { encoding: 'utf8' });
+    const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true });
     return {
       ok: result.status === 0,
       detail: [result.stdout, result.stderr].filter(Boolean).join('\n').trim(),
@@ -174,7 +174,10 @@ export function renderWindowsPowerShellScript(runner: RunnerParts): string {
   const env = Object.entries(runner.env ?? {})
     .map(([key, value]) => `$env:${key} = ${powershellQuote(value)}\n`)
     .join('');
-  return `$ErrorActionPreference = 'Continue'
+  // The first line also marks a unit from before the headless task: it no
+  // longer matches, so status reports upToDate false and repair reinstalls it.
+  return `# Run by the Kortix task under conhost --headless: no console window.
+$ErrorActionPreference = 'Continue'
 ${env}while ($true) {
   # The pipe makes PowerShell wait for a GUI-subsystem binary (the desktop
   # app's Kortix.exe) and set $LASTEXITCODE; a bare call returns at once.
@@ -252,7 +255,8 @@ const launchd: ServiceDriver = {
 
   status(paths, installed) {
     const disabled = run('launchctl', ['print-disabled', launchdTarget()]);
-    const enabled = !new RegExp(`"${paths.label.replace(/\./g, '\\.')}" => (disabled|true)`).test(disabled.detail);
+    // Plain substring match: the label is data, never a regex.
+    const enabled = ![`"${paths.label}" => disabled`, `"${paths.label}" => true`].some((line) => disabled.detail.includes(line));
     const status = run('launchctl', ['print', `${launchdTarget()}/${paths.label}`]);
     return {
       active: status.ok,
@@ -338,8 +342,10 @@ function ensureLinger(): CommandResult {
 /**
  * Task Scheduler definition. schtasks' own defaults stop the task on battery,
  * refuse to start it on battery, and kill it after 72 h, and a visible console
- * window ends the loop when the user closes it. Written as UTF-16, the
- * encoding schtasks /XML expects.
+ * window ends the loop when the user closes it. `-WindowStyle Hidden` alone
+ * still opens a window where Windows Terminal is the default terminal
+ * (Windows 11), so `conhost --headless` hosts PowerShell with no window at
+ * all. Written as UTF-16, the encoding schtasks /XML expects.
  */
 export function renderWindowsTaskXml(paths: ServicePaths, user: string): string {
   return `<?xml version="1.0" encoding="UTF-16"?>
@@ -355,7 +361,7 @@ export function renderWindowsTaskXml(paths: ServicePaths, user: string): string
     <StartWhenAvailable>true</StartWhenAvailable>
     <Enabled>true</Enabled>
   </Settings>
-  <Actions Context="Author"><Exec><Command>powershell.exe</Command><Arguments>${xmlEscape(`-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${paths.windowsScript}"`)}</Arguments></Exec></Actions>
+  <Actions Context="Author"><Exec><Command>conhost.exe</Command><Arguments>${xmlEscape(`--headless powershell.exe -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${paths.windowsScript}"`)}</Arguments></Exec></Actions>
 </Task>
 `;
 }