@kortix/agent-tunnel 0.1.4 → 0.12.8

package/dist/server/index.d.ts

@@ -1,89 +0,0 @@
-import { EventEmitter } from 'events';
-import { n as TunnelRelayConfig, o as TunnelRelayEvents, A as AgentInfo, R as RelayRpcOptions, H as HeartbeatConfig, a as AuthResult, q as TunnelServerConfig } from '../types-Dpwrd8Ai.js';
-import { Hono } from 'hono';
-
-declare class TunnelRelay extends EventEmitter {
-    private agents;
-    private pendingRPCs;
-    private config;
-    onAuthorizeRPC?: (tunnelId: string, method: string, params: Record<string, unknown>) => Promise<boolean>;
-    constructor(config?: TunnelRelayConfig);
-    emitEvent<K extends keyof TunnelRelayEvents>(event: K, data: TunnelRelayEvents[K]): boolean;
-    registerAgent(tunnelId: string, ws: WebSocket, signingKey: string, metadata?: Record<string, unknown>): void;
-    unregisterAgent(tunnelId: string): void;
-    isConnected(tunnelId: string): boolean;
-    getConnectedCount(): number;
-    getConnectedAgents(): Map<string, AgentInfo>;
-    getAgentMetadata(tunnelId: string): Record<string, unknown> | undefined;
-    handleAgentMessage(tunnelId: string, raw: string | Buffer): void;
-    relayRPC(tunnelId: string, method: string, params: Record<string, unknown>, options?: RelayRpcOptions): Promise<unknown>;
-    sendNotification(tunnelId: string, method: string, params?: Record<string, unknown>): boolean;
-    shutdown(): void;
-}
-declare class TunnelRelayError extends Error {
-    readonly code: number;
-    readonly data?: unknown | undefined;
-    constructor(code: number, message: string, data?: unknown | undefined);
-}
-
-declare class HeartbeatManager {
-    private states;
-    private intervalHandle;
-    private relay;
-    private intervalMs;
-    private maxMissed;
-    constructor(relay: TunnelRelay, config?: HeartbeatConfig);
-    start(): void;
-    stop(): void;
-    register(tunnelId: string): void;
-    unregister(tunnelId: string): void;
-    recordPong(tunnelId: string): void;
-    private tick;
-}
-
-interface WsHandlerOptions {
-    heartbeat?: HeartbeatManager;
-    maxMessageSize?: number;
-    onAuthenticate?: (tunnelId: string, token: string) => Promise<AuthResult | null>;
-    authTimeoutMs?: number;
-}
-interface WsHandlers {
-    onOpen(tunnelId: string, ws: WebSocket): void;
-    onMessage(tunnelId: string, message: string | Buffer): void;
-    onClose(tunnelId: string): void;
-}
-declare function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): WsHandlers;
-
-declare function createTunnelRouter(relay: TunnelRelay, onAuthorizeHTTP?: (req: Request) => Promise<boolean>): Hono;
-
-/**
- * Standalone tunnel server — one function call to get a working relay.
- *
- * Usage:
- *   import { startTunnelServer } from 'agent-tunnel';
- *   const server = startTunnelServer({ port: 8080, onAuthenticate: ... });
- *
- * Agents connect via: ws://localhost:8080/ws?tunnelId=yyy
- * Then send { type: "auth", token: "tnl_xxx" } as the first message.
- * Your app calls relay.relayRPC(tunnelId, method, params) to reach the agent.
- */
-
-interface TunnelServer {
-    app: Hono;
-    relay: TunnelRelay;
-    heartbeat: HeartbeatManager;
-    wsHandlers: ReturnType<typeof createWsHandlers>;
-    stop: () => void;
-}
-/**
- * Start a tunnel relay server. Handles everything:
- * - HTTP routes for connections list + RPC
- * - WebSocket upgrades on /ws for agent connections
- * - Heartbeat ping/pong
- * - HMAC signing key derivation via onAuthenticate hook
- *
- * Requires Bun runtime for WebSocket server support.
- */
-declare function startTunnelServer(config?: TunnelServerConfig): TunnelServer;
-
-export { HeartbeatManager, TunnelRelay, TunnelRelayError, type TunnelServer, type WsHandlerOptions, type WsHandlers, createTunnelRouter, createWsHandlers, startTunnelServer };

package/dist/server/index.js

@@ -1,14 +0,0 @@
-import { TunnelRelay, TunnelRelayError } from "./relay";
-import { HeartbeatManager } from "./heartbeat";
-import { createWsHandlers } from "./ws-handler";
-import { createTunnelRouter } from "./routes";
-import { startTunnelServer } from "./server";
-export {
-  HeartbeatManager,
-  TunnelRelay,
-  TunnelRelayError,
-  createTunnelRouter,
-  createWsHandlers,
-  startTunnelServer
-};
-//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/server/index.ts"],"sourcesContent":["export { TunnelRelay, TunnelRelayError } from './relay';\nexport { HeartbeatManager } from './heartbeat';\nexport { createWsHandlers } from './ws-handler';\nexport type { WsHandlers, WsHandlerOptions } from './ws-handler';\nexport { createTunnelRouter } from './routes';\nexport { startTunnelServer } from './server';\nexport type { TunnelServer } from './server';\n"],"mappings":"AAAA,SAAS,aAAa,wBAAwB;AAC9C,SAAS,wBAAwB;AACjC,SAAS,wBAAwB;AAEjC,SAAS,0BAA0B;AACnC,SAAS,yBAAyB;","names":[]}

package/dist/shared/index.d.ts

@@ -1,10 +0,0 @@
-export { A as AgentInfo, a as AuthResult, H as HeartbeatConfig, J as JsonRpcError, b as JsonRpcErrorResponse, c as JsonRpcMessage, d as JsonRpcNotification, e as JsonRpcRequest, f as JsonRpcResponse, g as JsonRpcSuccessResponse, P as PendingRPC, R as RelayRpcOptions, S as SignedJsonRpcNotification, h as SignedJsonRpcRequest, T as TunnelAuthMessage, i as TunnelCapability, j as TunnelErrorCode, k as TunnelErrorCodeValue, l as TunnelMethod, m as TunnelMethods, n as TunnelRelayConfig, o as TunnelRelayEvents, p as TunnelRpcParams, q as TunnelServerConfig } from '../types-Dpwrd8Ai.js';
-
-declare function deriveSigningKey(token: string, secret: string): string;
-declare function signMessage(signingKey: string, payload: string, nonce: number): string;
-declare function verifyMessageSignature(signingKey: string, payload: string, nonce: number, signature: string): boolean;
-declare function generateToken(prefix?: string): string;
-declare function hashToken(token: string, secret: string): string;
-declare function timingSafeStringEqual(a: string, b: string): boolean;
-
-export { deriveSigningKey, generateToken, hashToken, signMessage, timingSafeStringEqual, verifyMessageSignature };

package/dist/shared/index.js

@@ -1,20 +0,0 @@
-import {
-  deriveSigningKey,
-  signMessage,
-  verifyMessageSignature,
-  generateToken,
-  hashToken,
-  timingSafeStringEqual
-} from "./crypto";
-import { TunnelErrorCode, TunnelMethods } from "./types";
-export {
-  TunnelErrorCode,
-  TunnelMethods,
-  deriveSigningKey,
-  generateToken,
-  hashToken,
-  signMessage,
-  timingSafeStringEqual,
-  verifyMessageSignature
-};
-//# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/shared/index.ts"],"sourcesContent":["export {\n  deriveSigningKey,\n  signMessage,\n  verifyMessageSignature,\n  generateToken,\n  hashToken,\n  timingSafeStringEqual,\n} from './crypto';\n\nexport type {\n  JsonRpcRequest,\n  JsonRpcSuccessResponse,\n  JsonRpcErrorResponse,\n  JsonRpcError,\n  JsonRpcResponse,\n  JsonRpcNotification,\n  JsonRpcMessage,\n  SignedJsonRpcRequest,\n  SignedJsonRpcNotification,\n  PendingRPC,\n  TunnelRpcParams,\n  RelayRpcOptions,\n  AgentInfo,\n  TunnelRelayEvents,\n  TunnelRelayConfig,\n  HeartbeatConfig,\n  TunnelServerConfig,\n  TunnelAuthMessage,\n  AuthResult,\n  TunnelCapability,\n  TunnelMethod,\n  TunnelErrorCodeValue,\n} from './types';\n\nexport { TunnelErrorCode, TunnelMethods } from './types';\n"],"mappings":"AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA2BP,SAAS,iBAAiB,qBAAqB;","names":[]}

package/dist/types-Dpwrd8Ai.d.ts

@@ -1,194 +0,0 @@
-interface JsonRpcRequest {
-    jsonrpc: '2.0';
-    id: string;
-    method: string;
-    params?: Record<string, unknown>;
-}
-interface JsonRpcSuccessResponse {
-    jsonrpc: '2.0';
-    id: string;
-    result: unknown;
-}
-interface JsonRpcErrorResponse {
-    jsonrpc: '2.0';
-    id: string;
-    error: JsonRpcError;
-}
-interface JsonRpcError {
-    code: number;
-    message: string;
-    data?: unknown;
-}
-type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
-interface JsonRpcNotification {
-    jsonrpc: '2.0';
-    method: string;
-    params?: Record<string, unknown>;
-}
-type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
-declare const TunnelErrorCode: {
-    readonly PERMISSION_DENIED: -32000;
-    readonly CAPABILITY_NOT_REGISTERED: -32001;
-    readonly TIMEOUT: -32002;
-    readonly LOCAL_ERROR: -32003;
-    readonly NOT_CONNECTED: -32004;
-    readonly EXPIRED: -32005;
-    readonly RATE_LIMITED: -32006;
-    readonly AUTH_FAILED: -32007;
-};
-type TunnelErrorCodeValue = (typeof TunnelErrorCode)[keyof typeof TunnelErrorCode];
-type TunnelCapability = 'filesystem' | 'shell' | 'network' | 'apps' | 'hardware' | 'desktop' | 'gpu';
-declare const TunnelMethods: {
-    readonly 'fs.read': "filesystem";
-    readonly 'fs.write': "filesystem";
-    readonly 'fs.list': "filesystem";
-    readonly 'fs.stat': "filesystem";
-    readonly 'fs.delete': "filesystem";
-    readonly 'shell.exec': "shell";
-    readonly 'desktop.screenshot': "desktop";
-    readonly 'desktop.mouse.click': "desktop";
-    readonly 'desktop.mouse.move': "desktop";
-    readonly 'desktop.mouse.drag': "desktop";
-    readonly 'desktop.mouse.scroll': "desktop";
-    readonly 'desktop.mouse.position': "desktop";
-    readonly 'desktop.keyboard.type': "desktop";
-    readonly 'desktop.keyboard.key': "desktop";
-    readonly 'desktop.window.list': "desktop";
-    readonly 'desktop.window.focus': "desktop";
-    readonly 'desktop.window.resize': "desktop";
-    readonly 'desktop.window.close': "desktop";
-    readonly 'desktop.window.minimize': "desktop";
-    readonly 'desktop.app.launch': "desktop";
-    readonly 'desktop.app.quit': "desktop";
-    readonly 'desktop.app.list': "desktop";
-    readonly 'desktop.clipboard.read': "desktop";
-    readonly 'desktop.clipboard.write': "desktop";
-    readonly 'desktop.screen.info': "desktop";
-    readonly 'desktop.cursor.image': "desktop";
-    readonly 'desktop.ax.tree': "desktop";
-    readonly 'desktop.ax.action': "desktop";
-    readonly 'desktop.ax.set_value': "desktop";
-    readonly 'desktop.ax.focus': "desktop";
-    readonly 'desktop.ax.search': "desktop";
-    readonly 'net.request': "network";
-    readonly 'net.port_forward.start': "network";
-    readonly 'net.port_forward.stop': "network";
-    readonly 'tunnel.ping': null;
-    readonly 'tunnel.pong': null;
-    readonly 'tunnel.permission.revoked': null;
-    readonly 'tunnel.permissions.sync': null;
-    readonly 'tunnel.token.rotated': null;
-};
-type TunnelMethod = keyof typeof TunnelMethods;
-interface PendingRPC {
-    resolve: (value: unknown) => void;
-    reject: (error: Error) => void;
-    timer: ReturnType<typeof setTimeout>;
-    method: string;
-    tunnelId: string;
-    startedAt: number;
-}
-interface SignedJsonRpcRequest extends JsonRpcRequest {
-    _sig: string;
-    _nonce: number;
-}
-interface SignedJsonRpcNotification extends JsonRpcNotification {
-    _sig: string;
-    _nonce: number;
-}
-interface TunnelRpcParams {
-    capability: TunnelCapability;
-    operation: string;
-    args: Record<string, unknown>;
-    permissionId?: string;
-}
-interface RelayRpcOptions {
-    timeoutMs?: number;
-}
-/** Public agent info — does NOT expose signing key. */
-interface AgentInfo {
-    tunnelId: string;
-    connectedAt: number;
-    metadata?: Record<string, unknown>;
-}
-interface TunnelRelayEvents {
-    'agent:connect': {
-        tunnelId: string;
-        metadata?: Record<string, unknown>;
-    };
-    'agent:disconnect': {
-        tunnelId: string;
-    };
-    'agent:timeout': {
-        tunnelId: string;
-    };
-    'rpc:request': {
-        tunnelId: string;
-        method: string;
-        requestId: string;
-    };
-    'rpc:response': {
-        tunnelId: string;
-        method: string;
-        requestId: string;
-        durationMs: number;
-    };
-    'rpc:error': {
-        tunnelId: string;
-        method: string;
-        requestId: string;
-        error: Error;
-    };
-    'connection:replaced': {
-        tunnelId: string;
-    };
-    'message:pong': {
-        tunnelId: string;
-        params?: Record<string, unknown>;
-    };
-    'message:raw': {
-        tunnelId: string;
-        message: unknown;
-    };
-}
-interface TunnelRelayConfig {
-    rpcTimeoutMs?: number;
-    maxWsMessageSize?: number;
-}
-interface HeartbeatConfig {
-    intervalMs?: number;
-    maxMissed?: number;
-}
-/** Auth handshake message sent by agent as first WS message. */
-interface TunnelAuthMessage {
-    type: 'auth';
-    token: string;
-}
-/** Result returned by onAuthenticate hook on success. */
-interface AuthResult {
-    signingKey: string;
-    metadata?: Record<string, unknown>;
-}
-interface TunnelServerConfig {
-    port?: number;
-    relay?: TunnelRelayConfig;
-    heartbeat?: HeartbeatConfig;
-    /**
-     * Called when an agent sends its auth handshake.
-     * Return { signingKey, metadata } to accept, or null to reject.
-     * If not provided, all connections are rejected.
-     */
-    onAuthenticate?: (tunnelId: string, token: string) => Promise<AuthResult | null>;
-    /**
-     * Called before relaying an RPC to the agent.
-     * Return false to deny. If not provided, all RPCs are allowed.
-     */
-    onAuthorizeRPC?: (tunnelId: string, method: string, params: Record<string, unknown>) => Promise<boolean>;
-    /**
-     * Called before handling HTTP requests to relay routes (/connections, /rpc).
-     * Return false to deny. If not provided, routes are open.
-     */
-    onAuthorizeHTTP?: (req: Request) => Promise<boolean>;
-}
-
-export { type AgentInfo as A, type HeartbeatConfig as H, type JsonRpcError as J, type PendingRPC as P, type RelayRpcOptions as R, type SignedJsonRpcNotification as S, type TunnelAuthMessage as T, type AuthResult as a, type JsonRpcErrorResponse as b, type JsonRpcMessage as c, type JsonRpcNotification as d, type JsonRpcRequest as e, type JsonRpcResponse as f, type JsonRpcSuccessResponse as g, type SignedJsonRpcRequest as h, type TunnelCapability as i, TunnelErrorCode as j, type TunnelErrorCodeValue as k, type TunnelMethod as l, TunnelMethods as m, type TunnelRelayConfig as n, type TunnelRelayEvents as o, type TunnelRpcParams as p, type TunnelServerConfig as q };

package/src/agent/capabilities/desktop/atspi-helper.ts

@@ -1,345 +0,0 @@
-import { spawn } from 'child_process';
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
-
-const HELPER_VERSION = 'v1';
-const BIN_DIR = join(homedir(), '.agent-tunnel', 'bin');
-const HELPER_PATH = join(BIN_DIR, `atspi-helper-${HELPER_VERSION}.py`);
-
-const PYTHON_SOURCE = `#!/usr/bin/env python3
-"""AT-SPI2 accessibility helper for Linux."""
-import json
-import sys
-
-try:
-    import gi
-    gi.require_version('Atspi', '2.0')
-    from gi.repository import Atspi
-except ImportError:
-    print(json.dumps({"ok": False, "error": "python3-gi and gir1.2-atspi-2.0 required. Install: sudo apt install python3-gi gir1.2-atspi-2.0"}))
-    sys.exit(0)
-
-element_count = 0
-
-def get_role_name(accessible):
-    try:
-        return Atspi.Accessible.get_role_name(accessible)
-    except:
-        return ""
-
-def get_name(accessible):
-    try:
-        return Atspi.Accessible.get_name(accessible) or ""
-    except:
-        return ""
-
-def get_description(accessible):
-    try:
-        return Atspi.Accessible.get_description(accessible) or ""
-    except:
-        return ""
-
-def get_bounds(accessible):
-    try:
-        comp = accessible.get_component_iface()
-        if comp:
-            rect = comp.get_extents(Atspi.CoordType.SCREEN)
-            return {"x": rect.x, "y": rect.y, "width": rect.width, "height": rect.height}
-    except:
-        pass
-    return {"x": 0, "y": 0, "width": 0, "height": 0}
-
-def get_value(accessible):
-    try:
-        val = accessible.get_value_iface()
-        if val:
-            return str(val.get_current_value())
-    except:
-        pass
-    return ""
-
-def get_actions(accessible):
-    actions = []
-    try:
-        action_iface = accessible.get_action_iface()
-        if action_iface:
-            for i in range(action_iface.get_n_actions()):
-                name = action_iface.get_action_name(i)
-                if name:
-                    actions.append(name)
-    except:
-        pass
-    return actions
-
-def get_states(accessible):
-    enabled = True
-    focused = False
-    try:
-        state_set = accessible.get_state_set()
-        enabled = state_set.contains(Atspi.StateType.ENABLED) or state_set.contains(Atspi.StateType.SENSITIVE)
-        focused = state_set.contains(Atspi.StateType.FOCUSED)
-    except:
-        pass
-    return enabled, focused
-
-def walk_tree(accessible, depth, max_depth, roles, path_prefix):
-    global element_count
-    if accessible is None or depth > max_depth:
-        return None
-    element_count += 1
-
-    role = get_role_name(accessible)
-    name = get_name(accessible)
-    value = get_value(accessible)
-    desc = get_description(accessible)
-    bounds = get_bounds(accessible)
-    actions = get_actions(accessible)
-    enabled, focused = get_states(accessible)
-
-    children = []
-    if depth < max_depth:
-        try:
-            count = accessible.get_child_count()
-            for i in range(count):
-                child = accessible.get_child_at_index(i)
-                if child:
-                    child_path = f"{path_prefix}.{i}" if path_prefix else str(i)
-                    child_node = walk_tree(child, depth + 1, max_depth, roles, child_path)
-                    if child_node is not None:
-                        if isinstance(child_node, list):
-                            children.extend(child_node)
-                        else:
-                            children.append(child_node)
-        except:
-            pass
-
-    if roles and role.lower() not in [r.lower() for r in roles]:
-        return children if children else None
-
-    return {
-        "id": path_prefix,
-        "role": role,
-        "title": name,
-        "value": value,
-        "description": desc,
-        "bounds": bounds,
-        "children": children,
-        "actions": actions,
-        "enabled": enabled,
-        "focused": focused,
-    }
-
-def find_app_by_pid(pid):
-    desktop = Atspi.get_desktop(0)
-    count = desktop.get_child_count()
-    for i in range(count):
-        app = desktop.get_child_at_index(i)
-        if app:
-            try:
-                if app.get_process_id() == pid:
-                    return app
-            except:
-                pass
-    raise Exception(f"No AT-SPI application found for PID {pid}")
-
-def navigate_to_element(root, element_id):
-    parts = element_id.split(".")
-    current = root
-    for part in parts:
-        idx = int(part)
-        child = current.get_child_at_index(idx)
-        if child is None:
-            raise Exception(f"Element not found at path: {element_id}")
-        current = child
-    return current
-
-def search_tree(accessible, query, role_filter, max_results, results, path_prefix, depth, max_depth):
-    if accessible is None or len(results) >= max_results or depth > max_depth:
-        return
-
-    role = get_role_name(accessible)
-    name = get_name(accessible)
-    value = get_value(accessible)
-    desc = get_description(accessible)
-
-    query_lower = query.lower()
-    match = (query_lower in name.lower() or query_lower in value.lower() or query_lower in desc.lower())
-
-    if role_filter and role.lower() != role_filter.lower():
-        match = False
-
-    if match:
-        bounds = get_bounds(accessible)
-        actions = get_actions(accessible)
-        enabled, focused = get_states(accessible)
-        results.append({
-            "id": path_prefix,
-            "role": role,
-            "title": name,
-            "value": value,
-            "description": desc,
-            "bounds": bounds,
-            "children": [],
-            "actions": actions,
-            "enabled": enabled,
-            "focused": focused,
-        })
-
-    try:
-        count = accessible.get_child_count()
-        for i in range(count):
-            if len(results) >= max_results:
-                break
-            child = accessible.get_child_at_index(i)
-            if child:
-                child_path = f"{path_prefix}.{i}" if path_prefix else str(i)
-                search_tree(child, query, role_filter, max_results, results, child_path, depth + 1, max_depth)
-    except:
-        pass
-
-def main():
-    raw = sys.stdin.read().strip()
-    try:
-        req = json.loads(raw)
-    except:
-        print(json.dumps({"ok": False, "error": "Invalid JSON input"}))
-        return
-
-    action = req.get("action", "")
-
-    try:
-        if action == "ax_tree":
-            pid = req.get("pid", 0)
-            max_depth = req.get("maxDepth", 8)
-            roles = req.get("roles", [])
-
-            root = find_app_by_pid(pid) if pid > 0 else Atspi.get_desktop(0)
-
-            global element_count
-            element_count = 0
-            tree = walk_tree(root, 0, max_depth, roles, "0")
-            print(json.dumps({"ok": True, "root": tree, "elementCount": element_count}))
-
-        elif action == "ax_action":
-            element_id = req.get("elementId", "")
-            action_name = req.get("action_name", "")
-            pid = req.get("pid", 0)
-
-            root = find_app_by_pid(pid) if pid > 0 else Atspi.get_desktop(0)
-            el = navigate_to_element(root, element_id)
-
-            action_iface = el.get_action_iface()
-            if not action_iface:
-                raise Exception("Element does not support actions")
-
-            performed = False
-            for i in range(action_iface.get_n_actions()):
-                if action_iface.get_action_name(i).lower() == action_name.lower():
-                    action_iface.do_action(i)
-                    performed = True
-                    break
-
-            if not performed:
-                raise Exception(f"Action '{action_name}' not found on element")
-
-            print(json.dumps({"ok": True}))
-
-        elif action == "ax_search":
-            query = req.get("query", "")
-            role_filter = req.get("role", None)
-            pid = req.get("pid", 0)
-            max_results = req.get("maxResults", 20)
-
-            root = find_app_by_pid(pid) if pid > 0 else Atspi.get_desktop(0)
-            results = []
-            search_tree(root, query, role_filter, max_results, results, "0", 0, 20)
-            print(json.dumps({"ok": True, "elements": results}))
-
-        else:
-            print(json.dumps({"ok": False, "error": f"Unknown action: {action}"}))
-    except Exception as e:
-        print(json.dumps({"ok": False, "error": str(e)}))
-
-if __name__ == "__main__":
-    main()
-`;
-
-let written = false;
-
-export async function ensureHelper(): Promise<string> {
-  if (written && existsSync(HELPER_PATH)) return HELPER_PATH;
-
-  if (existsSync(HELPER_PATH)) {
-    written = true;
-    return HELPER_PATH;
-  }
-
-  mkdirSync(BIN_DIR, { recursive: true });
-  writeFileSync(HELPER_PATH, PYTHON_SOURCE, { mode: 0o755 });
-  written = true;
-
-  return HELPER_PATH;
-}
-
-export interface AtspiHelperRequest {
-  action: string;
-  pid?: number;
-  maxDepth?: number;
-  roles?: string[];
-  elementId?: string;
-  action_name?: string;
-  query?: string;
-  role?: string;
-  maxResults?: number;
-  value?: string;
-}
-
-export interface AtspiHelperResponse {
-  ok: boolean;
-  error?: string;
-  root?: any;
-  elementCount?: number;
-  elements?: any[];
-}
-
-export async function execAtspiHelper(request: AtspiHelperRequest): Promise<AtspiHelperResponse> {
-  const helperPath = await ensureHelper();
-
-  return new Promise((resolve, reject) => {
-    const proc = spawn('python3', [helperPath], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
-    proc.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
-
-    proc.on('close', (code) => {
-      if (code !== 0) {
-        reject(new Error(`AT-SPI helper failed (exit ${code}): ${stderr}`));
-        return;
-      }
-
-      try {
-        const response = JSON.parse(stdout.trim()) as AtspiHelperResponse;
-        if (!response.ok && response.error) {
-          reject(new Error(response.error));
-          return;
-        }
-        resolve(response);
-      } catch {
-        reject(new Error(`Invalid helper output: ${stdout}`));
-      }
-    });
-
-    proc.on('error', (err) => {
-      reject(new Error(`python3 not found: ${err.message}. Install: sudo apt install python3`));
-    });
-
-    proc.stdin.write(JSON.stringify(request));
-    proc.stdin.end();
-  });
-}