@kortix/agent-tunnel 0.1.3 → 0.12.7

package/src/client/index.ts

@@ -1,5 +1,5 @@
 export { TunnelClient, TunnelClientError } from './tunnel-client';
-export type { TunnelClientConfig, AXElement } from './tunnel-client';
+export type { TunnelClientConfig } from './tunnel-client';
 export { createTunnelTools } from './tools';
 export type { TunnelToolDefinition, TunnelToolParameter } from './tools';
 // CLI entrypoint: src/client/cli.ts (run via `bun run cli.ts <command> [json]`)

package/src/client/tools.ts

@@ -1,8 +1,4 @@
-import { writeFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-import { randomBytes } from 'crypto';
-import type { TunnelClient, AXElement } from './tunnel-client';
+import type { TunnelClient } from './tunnel-client';
 
 export interface TunnelToolParameter {
   type: string;
@@ -19,52 +15,28 @@ export interface TunnelToolDefinition {
   execute: (args: Record<string, unknown>) => Promise<string>;
 }
 
-function saveImage(base64: string, format: string): string {
-  const ext = format === 'jpeg' || format === 'jpg' ? 'jpg' : 'png';
-  const dir = join(tmpdir(), 'tunnel-screenshots');
-  mkdirSync(dir, { recursive: true });
-  const path = join(dir, `screenshot-${randomBytes(4).toString('hex')}.${ext}`);
-  writeFileSync(path, Buffer.from(base64, 'base64'));
-  return path;
-}
-
-function formatAXTree(el: AXElement, indent: number = 0): string {
-  const pad = '  '.repeat(indent);
-  const parts: string[] = [];
-
-  const label = el.title || el.value || el.description || '(unnamed)';
-  const flags: string[] = [];
-  if (!el.enabled) flags.push('disabled');
-  if (el.focused) flags.push('focused');
-  if (el.actions.length > 0) flags.push(`actions: ${el.actions.join(',')}`);
-  const flagStr = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
-
-  parts.push(`${pad}[${el.role}] ${label} (id: ${el.id})${flagStr}`);
-
-  for (const child of el.children) {
-    parts.push(formatAXTree(child, indent + 1));
-  }
-
-  return parts.join('\n');
-}
-
 const tunnelIdParam: TunnelToolParameter = {
   type: 'string',
   description: 'Tunnel connection ID (auto-discovered if omitted)',
   required: false,
 };
 
+function stringifyResult(result: unknown): string {
+  if (typeof result === 'string') return result;
+  return JSON.stringify(result, null, 2);
+}
+
 export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[] {
   return [
     {
       name: 'tunnel_status',
-      description: `Check the status of all Agent Tunnel connections to the user's local machine. Lists every registered tunnel with its live/offline status, capabilities, and machine info.`,
+      description: `Check the status of all Agent Tunnel connections to local computers. Lists every registered machine with live/offline status, capabilities, and machine info.`,
       parameters: {},
       async execute() {
         const connections = (await client.getConnections()) as Array<Record<string, unknown>>;
 
         if (connections.length === 0) {
-          return 'No tunnel connections found. The user needs to set up Agent Tunnel first:\n1. Create a tunnel connection\n2. Run `npx @kortix/agent-tunnel connect` on their local machine';
+          return 'No tunnel connections found. Connect this computer from the Kortix desktop app or run the tunnel connect command on another computer.';
         }
 
         const sections: string[] = [];
@@ -77,7 +49,7 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
           const machineInfo = (data.machineInfo as Record<string, unknown>) || {};
 
           const lines = [
-            `=== Tunnel: ${data.name || 'Unnamed'} — ${status} ===`,
+            `=== Computer: ${data.name || 'Unnamed'} — ${status} ===`,
             `ID: ${data.tunnelId}`,
             `Capabilities: ${capabilities.length > 0 ? capabilities.join(', ') : '(none registered)'}`,
           ];
@@ -90,7 +62,7 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
         }
 
         if (!hasOnline) {
-          sections.push('\nNo tunnel is currently online. Ask the user to run `npx @kortix/agent-tunnel connect` on their local machine.');
+          sections.push('\nNo tunnel is currently online. Connect this computer from the Kortix desktop app or run the tunnel connect command on the target computer.');
         }
 
         return sections.join('\n\n');
@@ -98,10 +70,10 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
     },
     {
       name: 'tunnel_fs_read',
-      description: `Read a file from the user's local machine via Agent Tunnel. Requires filesystem permission.`,
+      description: `Read a file from a connected computer via Agent Tunnel. Requires filesystem permission.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        path: { type: 'string', description: 'Absolute path to the file on the user\'s local machine', required: true },
+        path: { type: 'string', description: 'Absolute path to the file on the connected computer', required: true },
         encoding: { type: 'string', description: 'File encoding (default: utf-8)', required: false },
       },
       async execute(args) {
@@ -116,10 +88,10 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
     },
     {
       name: 'tunnel_fs_write',
-      description: `Write a file to the user's local machine via Agent Tunnel. Creates parent directories if needed. Requires filesystem write permission.`,
+      description: `Write a file to a connected computer via Agent Tunnel. Creates parent directories if needed. Requires filesystem write permission.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        path: { type: 'string', description: 'Absolute path for the file on the user\'s local machine', required: true },
+        path: { type: 'string', description: 'Absolute path for the file on the connected computer', required: true },
         content: { type: 'string', description: 'File content to write', required: true },
         encoding: { type: 'string', description: 'File encoding (default: utf-8)', required: false },
       },
@@ -136,10 +108,10 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
     },
     {
       name: 'tunnel_fs_list',
-      description: `List directory contents on the user's local machine via Agent Tunnel. Requires filesystem permission.`,
+      description: `List directory contents on a connected computer via Agent Tunnel. Requires filesystem permission.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        path: { type: 'string', description: 'Absolute path to the directory on the user\'s local machine', required: true },
+        path: { type: 'string', description: 'Absolute path to the directory on the connected computer', required: true },
         recursive: { type: 'boolean', description: 'Include subdirectory contents (default: false)', required: false },
       },
       async execute(args) {
@@ -162,10 +134,10 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
     },
     {
       name: 'tunnel_shell_exec',
-      description: `Execute a command on the user's local machine via Agent Tunnel. Commands are executed without shell interpolation (array args) for security. Requires shell permission.`,
+      description: `Execute a command on a connected computer via Agent Tunnel. Commands are executed without shell interpolation (array args) for security. Requires shell permission.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        command: { type: 'string', description: "Command executable name (e.g., 'ls', 'git', 'python')", required: true },
+        command: { type: 'string', description: "Command executable name (e.g. 'ls', 'git', 'python')", required: true },
         args: { type: 'array', description: 'Command arguments as separate strings (no shell interpolation)', required: false, items: { type: 'string' } },
         cwd: { type: 'string', description: 'Working directory for the command', required: false },
         timeout: { type: 'number', description: 'Timeout in milliseconds (default: 30000, max: 120000)', required: false },
@@ -202,401 +174,168 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
       },
     },
     {
-      name: 'tunnel_screenshot',
-      description: `Take a screenshot of the user's screen via Agent Tunnel. Saves the image to a temp file and returns the path.`,
-      parameters: {
-        tunnel_id: tunnelIdParam,
-        x: { type: 'number', description: 'Region X coordinate', required: false },
-        y: { type: 'number', description: 'Region Y coordinate', required: false },
-        width: { type: 'number', description: 'Region width', required: false },
-        height: { type: 'number', description: 'Region height', required: false },
-        windowId: { type: 'number', description: 'Capture a specific window by ID', required: false },
-      },
-      async execute(args) {
-        const params: Record<string, unknown> = {};
-        if (args.x !== undefined && args.y !== undefined && args.width !== undefined && args.height !== undefined) {
-          params.region = { x: args.x, y: args.y, width: args.width, height: args.height };
-        }
-        if (args.windowId !== undefined) params.windowId = args.windowId;
-
-        const result = await client.rpcWithPermissionFlow('desktop.screenshot', params);
-        if (typeof result === 'string') return result;
-
-        const data = result as { image: string; width: number; height: number; format?: string };
-        const format = data.format || 'png';
-        const sizeKB = Math.round(data.image.length * 0.75 / 1024);
-        const path = saveImage(data.image, format);
-        return `Screenshot saved: ${path}\nDimensions: ${data.width}x${data.height} ${format.toUpperCase()} (${sizeKB}KB)\n\nUse the Read tool to view this image.`;
-      },
-    },
-    {
-      name: 'tunnel_click',
-      description: `Click at a specific screen coordinate on the user's machine via Agent Tunnel.`,
-      parameters: {
-        tunnel_id: tunnelIdParam,
-        x: { type: 'number', description: 'X coordinate to click', required: true },
-        y: { type: 'number', description: 'Y coordinate to click', required: true },
-        button: { type: 'string', description: 'Mouse button (default: left)', required: false, enum: ['left', 'right', 'middle'] },
-        clicks: { type: 'number', description: 'Number of clicks (default: 1, use 2 for double-click)', required: false },
-        modifiers: { type: 'array', description: 'Modifier keys held during click: cmd, shift, alt, ctrl', required: false, items: { type: 'string' } },
-      },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.mouse.click', {
-          x: args.x, y: args.y, button: args.button, clicks: args.clicks, modifiers: args.modifiers,
-        });
-        if (typeof result === 'string') return result;
-        return `Clicked at (${args.x}, ${args.y}) [${args.button || 'left'}]${args.clicks && (args.clicks as number) > 1 ? ` x${args.clicks}` : ''}`;
-      },
-    },
-    {
-      name: 'tunnel_mouse_move',
-      description: `Move the mouse cursor to a specific position on the user's screen via Agent Tunnel.`,
-      parameters: {
-        tunnel_id: tunnelIdParam,
-        x: { type: 'number', description: 'Target X coordinate', required: true },
-        y: { type: 'number', description: 'Target Y coordinate', required: true },
-      },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.mouse.move', { x: args.x, y: args.y });
-        if (typeof result === 'string') return result;
-        return `Mouse moved to (${args.x}, ${args.y})`;
-      },
-    },
-    {
-      name: 'tunnel_mouse_drag',
-      description: `Drag from one point to another on the user's screen via Agent Tunnel.`,
-      parameters: {
-        tunnel_id: tunnelIdParam,
-        fromX: { type: 'number', description: 'Start X coordinate', required: true },
-        fromY: { type: 'number', description: 'Start Y coordinate', required: true },
-        toX: { type: 'number', description: 'End X coordinate', required: true },
-        toY: { type: 'number', description: 'End Y coordinate', required: true },
-        button: { type: 'string', description: 'Mouse button (default: left)', required: false, enum: ['left', 'right'] },
-      },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.mouse.drag', {
-          fromX: args.fromX, fromY: args.fromY, toX: args.toX, toY: args.toY, button: args.button,
-        });
-        if (typeof result === 'string') return result;
-        return `Dragged from (${args.fromX}, ${args.fromY}) to (${args.toX}, ${args.toY})`;
-      },
-    },
-    {
-      name: 'tunnel_mouse_scroll',
-      description: `Scroll the mouse wheel at a specific position on the user's screen via Agent Tunnel.`,
-      parameters: {
-        tunnel_id: tunnelIdParam,
-        x: { type: 'number', description: 'X coordinate to scroll at', required: true },
-        y: { type: 'number', description: 'Y coordinate to scroll at', required: true },
-        deltaX: { type: 'number', description: 'Horizontal scroll amount (positive=right)', required: false },
-        deltaY: { type: 'number', description: 'Vertical scroll amount (positive=down)', required: false },
-      },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.mouse.scroll', {
-          x: args.x, y: args.y, deltaX: args.deltaX, deltaY: args.deltaY,
-        });
-        if (typeof result === 'string') return result;
-        return `Scrolled at (${args.x}, ${args.y}) [dx=${args.deltaX || 0}, dy=${args.deltaY || 0}]`;
-      },
-    },
-
-    {
-      name: 'tunnel_type',
-      description: `Type text into the currently focused application on the user's machine via Agent Tunnel.`,
-      parameters: {
-        tunnel_id: tunnelIdParam,
-        text: { type: 'string', description: 'Text to type', required: true },
-        delay: { type: 'number', description: 'Delay between characters in ms', required: false },
-      },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.keyboard.type', {
-          text: args.text, delay: args.delay,
-        });
-        if (typeof result === 'string') return result;
-        return `Typed ${(args.text as string).length} characters`;
-      },
-    },
-    {
-      name: 'tunnel_key',
-      description: `Press a key combination on the user's machine via Agent Tunnel. Use for keyboard shortcuts like cmd+s, ctrl+c, enter, tab, etc.`,
+      name: 'tunnel_cua_ensure',
+      description: `Ensure CUA Driver is installed on the connected computer and return its local binary path/version. Requires desktop computer_use permission.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        keys: { type: 'array', description: "Keys to press simultaneously. Examples: ['cmd', 's'] for save, ['enter'] for enter", required: true, items: { type: 'string' } },
       },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.keyboard.key', { keys: args.keys });
-        if (typeof result === 'string') return result;
-        return `Pressed: ${(args.keys as string[]).join('+')}`;
+      async execute() {
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.ensure', {}));
       },
     },
-
     {
-      name: 'tunnel_window_list',
-      description: `List all visible windows on the user's machine via Agent Tunnel. Returns window IDs, app names, titles, positions, and sizes.`,
+      name: 'tunnel_cua_start_daemon',
+      description: `Start the CUA Driver daemon/background service on the connected computer so CUA sessions and element indices remain stable.`,
       parameters: {
         tunnel_id: tunnelIdParam,
       },
       async execute() {
-        const result = await client.rpcWithPermissionFlow('desktop.window.list', {});
-        if (typeof result === 'string') return result;
-
-        const data = result as { windows: Array<{ id: number; app: string; title: string; bounds: { x: number; y: number; width: number; height: number }; minimized: boolean }> };
-        if (data.windows.length === 0) return 'No windows found';
-
-        const lines = [`=== Windows (${data.windows.length}) ===`];
-        for (const w of data.windows) {
-          const min = w.minimized ? ' [minimized]' : '';
-          lines.push(`  #${w.id} | ${w.app} — "${w.title}" | ${w.bounds.x},${w.bounds.y} ${w.bounds.width}x${w.bounds.height}${min}`);
-        }
-        return lines.join('\n');
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.start_daemon', {}));
       },
     },
     {
-      name: 'tunnel_window_focus',
-      description: `Bring a window to the front on the user's machine via Agent Tunnel.`,
+      name: 'tunnel_cua_status',
+      description: `Read CUA Driver daemon status from the connected computer.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        windowId: { type: 'number', description: 'Window ID from tunnel_window_list', required: true },
       },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.window.focus', { windowId: args.windowId });
-        if (typeof result === 'string') return result;
-        return `Window #${args.windowId} focused`;
-      },
-    },
-
-    {
-      name: 'tunnel_app_launch',
-      description: `Launch an application on the user's machine via Agent Tunnel.`,
-      parameters: {
-        tunnel_id: tunnelIdParam,
-        app: { type: 'string', description: 'Application name to launch', required: true },
-      },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.app.launch', { app: args.app });
-        if (typeof result === 'string') return result;
-        return `Launched: ${args.app}`;
+      async execute() {
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.status', {}));
       },
     },
     {
-      name: 'tunnel_app_quit',
-      description: `Quit an application on the user's machine via Agent Tunnel.`,
+      name: 'tunnel_cua_version',
+      description: `Read the installed CUA Driver version on the connected computer.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        app: { type: 'string', description: 'Application name to quit', required: true },
       },
-      async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.app.quit', { app: args.app });
-        if (typeof result === 'string') return result;
-        return `Quit: ${args.app}`;
+      async execute() {
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.version', {}));
       },
     },
-
     {
-      name: 'tunnel_clipboard_read',
-      description: `Read the clipboard contents from the user's machine via Agent Tunnel.`,
+      name: 'tunnel_cua_list_tools',
+      description: `List every CUA Driver tool exposed by the connected computer's installed driver.`,
       parameters: {
         tunnel_id: tunnelIdParam,
       },
       async execute() {
-        const result = await client.rpcWithPermissionFlow('desktop.clipboard.read', {});
-        if (typeof result === 'string') return result;
-        const data = result as { text: string };
-        if (!data.text) return '(clipboard is empty)';
-        return `=== Clipboard ===\n${data.text}`;
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.list_tools', {}));
       },
     },
     {
-      name: 'tunnel_clipboard_write',
-      description: `Write text to the clipboard on the user's machine via Agent Tunnel.`,
+      name: 'tunnel_cua_describe',
+      description: `Describe one CUA Driver tool before calling it.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        text: { type: 'string', description: 'Text to write to clipboard', required: true },
+        tool: { type: 'string', description: 'CUA Driver tool name', required: true },
       },
       async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.clipboard.write', { text: args.text });
-        if (typeof result === 'string') return result;
-        return `Clipboard updated (${(args.text as string).length} chars)`;
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.describe', {
+          tool: args.tool,
+        }));
       },
     },
-
     {
-      name: 'tunnel_screen_info',
-      description: `Get screen resolution and scale factor from the user's machine via Agent Tunnel.`,
+      name: 'tunnel_cua_list_apps',
+      description: `List installed and running desktop apps through CUA Driver, including bundle IDs and PIDs.`,
       parameters: {
         tunnel_id: tunnelIdParam,
       },
       async execute() {
-        const result = await client.rpcWithPermissionFlow('desktop.screen.info', {});
-        if (typeof result === 'string') return result;
-        const data = result as { width: number; height: number; scaleFactor: number };
-        return `Screen: ${data.width}x${data.height} @ ${data.scaleFactor}x scale`;
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.list_apps', {}));
       },
     },
-
     {
-      name: 'tunnel_cursor_image',
-      description: `Take a small screenshot around the current cursor position on the user's machine via Agent Tunnel.`,
+      name: 'tunnel_cua_list_windows',
+      description: `List top-level local desktop windows through CUA Driver. Use this before tunnel_cua_get_window_state.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        radius: { type: 'number', description: 'Radius in pixels around cursor (default: 50)', required: false },
+        pid: { type: 'number', description: 'Optional process ID filter', required: false },
+        on_screen_only: { type: 'boolean', description: 'Only include windows on the current Space', required: false },
       },
       async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.cursor.image', { radius: args.radius });
-        if (typeof result === 'string') return result;
-
-        const data = result as { image: string; width: number; height: number; format?: string };
-        const format = data.format || 'png';
-        const sizeKB = Math.round(data.image.length * 0.75 / 1024);
-        const path = saveImage(data.image, format);
-        return `Cursor area saved: ${path}\nDimensions: ${data.width}x${data.height} ${format.toUpperCase()} (${sizeKB}KB)\n\nUse the Read tool to view this image.`;
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.list_windows', {
+          pid: args.pid,
+          on_screen_only: args.on_screen_only,
+        }));
       },
     },
-
     {
-      name: 'tunnel_ax_tree',
-      description: `Get the accessibility tree of an application on the user's machine via Agent Tunnel. Returns a structured tree of UI elements with roles, labels, states, and available actions.`,
+      name: 'tunnel_cua_get_window_state',
+      description: `Get a CUA window snapshot: screenshot plus accessibility tree markdown with element_index values. Call this once per turn before element-indexed actions.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        pid: { type: 'number', description: 'Process ID of the target application (omit for all apps)', required: false },
-        maxDepth: { type: 'number', description: 'Maximum tree depth (default: 8)', required: false },
-        roles: { type: 'array', description: "Filter by element roles (e.g., ['button', 'textfield'])", required: false, items: { type: 'string' } },
+        pid: { type: 'number', description: 'Target process ID', required: true },
+        window_id: { type: 'number', description: 'Target window ID from tunnel_cua_list_windows', required: true },
+        query: { type: 'string', description: 'Optional filter for tree markdown', required: false },
+        capture_mode: { type: 'string', description: 'som, vision, or ax', required: false, enum: ['som', 'vision', 'ax'] },
       },
       async execute(args) {
-        const params: Record<string, unknown> = {};
-        if (args.pid !== undefined) params.pid = args.pid;
-        if (args.maxDepth !== undefined) params.maxDepth = args.maxDepth;
-        if (args.roles !== undefined) params.roles = args.roles;
-
-        const result = await client.rpcWithPermissionFlow('desktop.ax.tree', params);
-        if (typeof result === 'string') return result;
-
-        const data = result as { root: AXElement; elementCount: number };
-        if (!data.root) return 'No accessibility tree available';
-
-        const tree = formatAXTree(data.root);
-        return `=== Accessibility Tree (${data.elementCount} elements) ===\n${tree}`;
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.get_window_state', {
+          pid: args.pid,
+          window_id: args.window_id,
+          query: args.query,
+          capture_mode: args.capture_mode,
+        }));
       },
     },
     {
-      name: 'tunnel_ax_action',
-      description: `Perform an accessibility action on a UI element via Agent Tunnel. Returns before/after state to verify the action worked. Common actions: AXPress, AXConfirm, AXCancel, AXRaise, AXShowMenu.`,
+      name: 'tunnel_cua_click',
+      description: `Click with CUA Driver by element_index from the last window state, or by window-local screenshot coordinates.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        elementId: { type: 'string', description: "Element ID from the accessibility tree (e.g., '0.3.1')", required: true },
-        action: { type: 'string', description: 'Action to perform: AXPress, AXConfirm, AXCancel, AXRaise, AXShowMenu', required: true },
-        pid: { type: 'number', description: 'Process ID of the target application', required: false },
+        pid: { type: 'number', description: 'Target process ID', required: true },
+        window_id: { type: 'number', description: 'Target window ID; required for element_index', required: false },
+        element_index: { type: 'number', description: 'Element index from tunnel_cua_get_window_state', required: false },
+        x: { type: 'number', description: 'Window-local screenshot X coordinate', required: false },
+        y: { type: 'number', description: 'Window-local screenshot Y coordinate', required: false },
+        action: { type: 'string', description: 'AX action: press, show_menu, pick, confirm, cancel, open', required: false },
       },
       async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.ax.action', {
-          elementId: args.elementId, action: args.action, pid: args.pid,
-        });
-        if (typeof result === 'string') return result;
-
-        const data = result as {
-          ok: boolean; action: string; elementId: string;
-          before: { focused: boolean; value: string };
-          after: { focused: boolean; value: string };
-          stateChanged: boolean; role: string; title: string;
-        };
-
-        const lines = [`Action "${data.action}" on [${data.role}] "${data.title}" (${data.elementId})`];
-        lines.push(`State changed: ${data.stateChanged ? 'YES' : 'NO'}`);
-        lines.push(`Before: focused=${data.before.focused}, value="${data.before.value}"`);
-        lines.push(`After:  focused=${data.after.focused}, value="${data.after.value}"`);
-        if (!data.stateChanged) {
-          lines.push('WARNING: No state change detected. The action may not have had any effect.');
-        }
-        return lines.join('\n');
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.click', args));
       },
     },
     {
-      name: 'tunnel_ax_set_value',
-      description: `Directly set the value of a UI element (text field, search box, etc.) via the accessibility API. Much more reliable than clicking and typing.`,
+      name: 'tunnel_cua_type_text',
+      description: `Type text with CUA Driver into a target PID, optionally directed to an element_index from the last window state.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        elementId: { type: 'string', description: "Element ID from the accessibility tree (e.g., '0.3.1')", required: true },
-        value: { type: 'string', description: 'The value to set (e.g., text to put in a search field)', required: true },
-        pid: { type: 'number', description: 'Process ID of the target application', required: false },
+        pid: { type: 'number', description: 'Target process ID', required: true },
+        text: { type: 'string', description: 'Text to type', required: true },
+        window_id: { type: 'number', description: 'Target window ID; required for element_index', required: false },
+        element_index: { type: 'number', description: 'Element index from tunnel_cua_get_window_state', required: false },
       },
       async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.ax.set_value', {
-          elementId: args.elementId, value: args.value, pid: args.pid,
-        });
-        if (typeof result === 'string') return result;
-
-        const data = result as {
-          ok: boolean; elementId: string;
-          requestedValue: string; actualValue: string; error?: string;
-        };
-
-        if (data.ok) {
-          return `Value set successfully on ${data.elementId}\nRequested: "${data.requestedValue}"\nVerified:  "${data.actualValue}"`;
-        } else {
-          return `FAILED to set value on ${data.elementId}\nRequested: "${data.requestedValue}"\nActual:    "${data.actualValue}"\nError: ${data.error || 'unknown'}`;
-        }
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.type_text', args));
       },
     },
     {
-      name: 'tunnel_ax_focus',
-      description: `Focus a UI element directly via the accessibility API. More reliable than clicking to focus.`,
+      name: 'tunnel_cua_hotkey',
+      description: `Press a CUA Driver hotkey against a target PID, for example ["cmd","c"].`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        elementId: { type: 'string', description: "Element ID from the accessibility tree (e.g., '0.3.1')", required: true },
-        pid: { type: 'number', description: 'Process ID of the target application', required: false },
+        pid: { type: 'number', description: 'Target process ID', required: true },
+        keys: { type: 'array', description: 'Modifier(s) and one key, e.g. ["cmd","c"]', required: true, items: { type: 'string' } },
+        window_id: { type: 'number', description: 'Optional target window ID for native menu dispatch', required: false },
       },
       async execute(args) {
-        const result = await client.rpcWithPermissionFlow('desktop.ax.focus', {
-          elementId: args.elementId, pid: args.pid,
-        });
-        if (typeof result === 'string') return result;
-
-        const data = result as {
-          ok: boolean; elementId: string; role: string; title: string;
-          before: { focused: boolean }; after: { focused: boolean }; error?: string;
-        };
-
-        if (data.ok) {
-          return `Focused [${data.role}] "${data.title}" (${data.elementId})\nBefore: focused=${data.before.focused}\nAfter:  focused=${data.after.focused}`;
-        } else {
-          return `FAILED to focus [${data.role}] "${data.title}" (${data.elementId})\nError: ${data.error || 'unknown'}\nBefore: focused=${data.before.focused}\nAfter:  focused=${data.after.focused}`;
-        }
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.hotkey', args));
       },
     },
     {
-      name: 'tunnel_ax_search',
-      description: `Search the accessibility tree for UI elements matching a query via Agent Tunnel. Case-insensitive substring match on titles, values, and descriptions.`,
+      name: 'tunnel_cua_call',
+      description: `Call any CUA Driver tool by name with raw JSON args. Prefer the specific tunnel_cua_* tools when available.`,
       parameters: {
         tunnel_id: tunnelIdParam,
-        query: { type: 'string', description: 'Search text (matches against title, value, description)', required: true },
-        role: { type: 'string', description: "Filter by element role (e.g., 'button', 'textfield')", required: false },
-        pid: { type: 'number', description: 'Process ID of the target application', required: false },
-        maxResults: { type: 'number', description: 'Maximum results to return (default: 20)', required: false },
+        tool: { type: 'string', description: 'CUA Driver tool name', required: true },
+        args: { type: 'object', description: 'Raw CUA Driver tool arguments', required: false },
       },
       async execute(args) {
-        const params: Record<string, unknown> = { query: args.query };
-        if (args.role !== undefined) params.role = args.role;
-        if (args.pid !== undefined) params.pid = args.pid;
-        if (args.maxResults !== undefined) params.maxResults = args.maxResults;
-
-        const result = await client.rpcWithPermissionFlow('desktop.ax.search', params);
-        if (typeof result === 'string') return result;
-
-        const data = result as { elements: AXElement[] };
-        if (!data.elements || data.elements.length === 0) return `No elements found matching "${args.query}"`;
-
-        const lines = [`=== AX Search: "${args.query}" (${data.elements.length} results) ===`];
-        for (const el of data.elements) {
-          const label = el.title || el.value || el.description || '(unnamed)';
-          const flags: string[] = [];
-          if (!el.enabled) flags.push('disabled');
-          if (el.focused) flags.push('focused');
-          if (el.actions.length > 0) flags.push(`actions: ${el.actions.join(',')}`);
-          const flagStr = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
-          const b = el.bounds;
-          lines.push(`  [${el.role}] ${label} (id: ${el.id}) @ ${b.x},${b.y} ${b.width}x${b.height}${flagStr}`);
-        }
-        return lines.join('\n');
+        return stringifyResult(await client.rpcWithPermissionFlow('desktop.cua.call', {
+          tool: args.tool,
+          args: args.args || {},
+        }));
       },
     },
   ];