@kortix/agent-tunnel 0.13.53 → 0.13.55

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];
-}

package/src/shared/types.ts

@@ -48,6 +48,10 @@ export const TunnelErrorCode = {
   ACCESS_DENIED: -32011,
   /** The owner turned computer access off on the machine. */
   ACCESS_OFF: -32012,
+  /** macOS has not given the agent Accessibility or Screen Recording. */
+  DESKTOP_PERMISSION_MISSING: -32013,
+  /** A wider access asked for through Kortix that nobody confirmed on the machine. */
+  ACCESS_UNCONFIRMED: -32014,
 } as const;
 
 export type TunnelErrorCodeValue = (typeof TunnelErrorCode)[keyof typeof TunnelErrorCode];
@@ -68,47 +72,13 @@ export const TunnelMethods = {
   'desktop.cua.list_tools': 'desktop',
   'desktop.cua.describe': 'desktop',
   'desktop.cua.call': 'desktop',
-  'desktop.cua.bring_to_front': 'desktop',
-  'desktop.cua.check_for_update': 'desktop',
-  'desktop.cua.check_permissions': 'desktop',
-  'desktop.cua.click': 'desktop',
-  'desktop.cua.double_click': 'desktop',
-  'desktop.cua.drag': 'desktop',
-  'desktop.cua.end_session': 'desktop',
-  'desktop.cua.get_accessibility_tree': 'desktop',
-  'desktop.cua.get_agent_cursor_state': 'desktop',
-  'desktop.cua.get_config': 'desktop',
-  'desktop.cua.get_cursor_position': 'desktop',
-  'desktop.cua.get_recording_state': 'desktop',
-  'desktop.cua.get_screen_size': 'desktop',
-  'desktop.cua.get_window_state': 'desktop',
-  'desktop.cua.hotkey': 'desktop',
-  'desktop.cua.kill_app': 'desktop',
-  'desktop.cua.launch_app': 'desktop',
-  'desktop.cua.list_apps': 'desktop',
-  'desktop.cua.list_windows': 'desktop',
-  'desktop.cua.move_cursor': 'desktop',
-  'desktop.cua.page': 'desktop',
-  'desktop.cua.press_key': 'desktop',
-  'desktop.cua.replay_trajectory': 'desktop',
-  'desktop.cua.right_click': 'desktop',
-  'desktop.cua.scroll': 'desktop',
-  'desktop.cua.set_agent_cursor_enabled': 'desktop',
-  'desktop.cua.set_agent_cursor_motion': 'desktop',
-  'desktop.cua.set_agent_cursor_style': 'desktop',
-  'desktop.cua.set_config': 'desktop',
-  'desktop.cua.set_value': 'desktop',
-  'desktop.cua.start_recording': 'desktop',
-  'desktop.cua.install_ffmpeg': 'desktop',
-  'desktop.cua.start_session': 'desktop',
-  'desktop.cua.stop_recording': 'desktop',
-  'desktop.cua.type_text': 'desktop',
-  'desktop.cua.zoom': 'desktop',
   'tunnel.ping': null,
   'tunnel.pong': null,
   'tunnel.permission.revoked': null,
   'tunnel.permissions.sync': null,
   'tunnel.token.rotated': null,
+  /** The owner's access change, relayed by Kortix (owner-only route). Never a capability. */
+  'tunnel.access.set': null,
 } as const;
 
 export type TunnelMethod = keyof typeof TunnelMethods;
@@ -195,6 +165,8 @@ export interface TunnelAuthMessage {
    * that enforces nothing connects with the same credential.
    */
   reportsAccess?: boolean;
+  /** True from agents that serve `tunnel.access.set` (the owner's change, relayed). */
+  controlsAccess?: boolean;
 }
 
 /** Result returned by onAuthenticate hook on success. */