@sensaiorg/adapter-android 0.1.0

package/dist/tools/ui-tree.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * UI Tree Tools - Inspect the Android view hierarchy.
+ *
+ * Provides three tools:
+ * - get_ui_tree: Full UI hierarchy as JSON
+ * - get_screen_text: Extract all visible text in reading order
+ * - get_element_details: Deep inspection of a specific element
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedTree = getCachedTree;
+exports.registerUiTreeTools = registerUiTreeTools;
+const zod_1 = require("zod");
+const ui_tree_parser_js_1 = require("../util/ui-tree-parser.js");
+const text_extractor_js_1 = require("../util/text-extractor.js");
+/**
+ * Dump the UI hierarchy via ADB uiautomator (raw XML).
+ * Uses a unique filename per dump to prevent race conditions on concurrent requests.
+ */
+async function dumpUiTreeRaw(cm) {
+    const dumpPath = `/sdcard/sensai_dump_${Date.now()}.xml`;
+    const dumpOutput = await cm.adb.shell(`uiautomator dump ${dumpPath}`);
+    if (dumpOutput.includes("ERROR") || !dumpOutput.includes("dumped")) {
+        throw new Error(`uiautomator dump failed: ${dumpOutput.trim()}`);
+    }
+    const xml = await cm.adb.shell(`cat ${dumpPath}`);
+    // Clean up the dump file (fire and forget)
+    cm.adb.shell(`rm -f ${dumpPath}`).catch(() => { });
+    if (!xml.includes("<hierarchy")) {
+        throw new Error("UI dump produced invalid XML");
+    }
+    return xml;
+}
+/**
+ * Get the UI tree with caching support. Shared by all tools that need UI data.
+ * Exported so other tool modules can reuse without redundant dumps.
+ */
+async function getCachedTree(cm, options) {
+    // Phase 2: prefer agent for richer data
+    if (cm.agent.isConnected()) {
+        try {
+            const result = await cm.agent.call("getUiTree", options);
+            return result;
+        }
+        catch {
+            // Fall through to ADB
+        }
+    }
+    // Check cache unless force refresh requested
+    if (!options.forceRefresh) {
+        const cached = cm.uiCache.get();
+        if (cached) {
+            // Re-parse with current options from cached XML
+            return (0, ui_tree_parser_js_1.parseUiTree)(cached.xml, options);
+        }
+    }
+    // Phase 1: ADB uiautomator dump
+    const xml = await dumpUiTreeRaw(cm);
+    const tree = (0, ui_tree_parser_js_1.parseUiTree)(xml, options);
+    // Cache the raw XML and default-options tree
+    cm.uiCache.set(tree, xml);
+    return tree;
+}
+function registerUiTreeTools(server, cm) {
+    /**
+     * get_ui_tree - Returns the full UI hierarchy as structured JSON.
+     */
+    server.tool("get_ui_tree", "Get the Android UI view hierarchy as structured JSON. Returns class names, resource IDs, text, bounds, and interactive state for every view element.", {
+        maxDepth: zod_1.z.number().optional().describe("Maximum depth to traverse (0 = unlimited)"),
+        visibleOnly: zod_1.z.boolean().optional().describe("Only include visible nodes"),
+        includeSystemUI: zod_1.z.boolean().optional().describe("Include status bar, nav bar, etc."),
+        interactableOnly: zod_1.z.boolean().optional().describe("Only return nodes that are clickable, focusable, or have text content. Reduces noise significantly."),
+        format: zod_1.z.enum(["full", "compact"]).optional().describe("Output format: 'full' (default) returns UiNode objects, 'compact' returns [text, resourceId, bounds, clickable] tuples for ~60% token savings"),
+    }, async (params) => {
+        try {
+            const tree = await getCachedTree(cm, {
+                maxDepth: params.maxDepth,
+                visibleOnly: params.visibleOnly,
+                includeSystemUI: params.includeSystemUI,
+            });
+            let flat = (0, ui_tree_parser_js_1.flattenTree)(tree);
+            const totalNodes = flat.length;
+            // Filter to interactable nodes only
+            if (params.interactableOnly) {
+                flat = flat.filter((n) => n.clickable || n.focusable || !!n.text);
+            }
+            const summary = {
+                totalNodes,
+                returnedNodes: flat.length,
+                clickableNodes: flat.filter((n) => n.clickable).length,
+                textNodes: flat.filter((n) => n.text).length,
+                filtered: !!params.interactableOnly,
+                format: params.format ?? "full",
+            };
+            let treeData;
+            if (params.format === "compact") {
+                // Compact format: [text, resourceId, boundsStr, clickable] tuples
+                // Saves ~60% tokens vs full UiNode objects
+                treeData = flat.map((n) => [
+                    n.text || n.contentDescription || "",
+                    n.resourceId || "",
+                    n.bounds ? `[${n.bounds.left},${n.bounds.top}][${n.bounds.right},${n.bounds.bottom}]` : "",
+                    n.clickable,
+                ]);
+            }
+            else {
+                // Full format: return tree if not filtered, flat array if filtered
+                treeData = params.interactableOnly ? flat : tree;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ summary, tree: treeData }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error getting UI tree: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * get_screen_text - Extract all visible text from the screen in reading order.
+     */
+    server.tool("get_screen_text", "Extract all visible text from the current screen, ordered top-to-bottom left-to-right (reading order). Useful for understanding what the user sees.", {}, async () => {
+        try {
+            const tree = await getCachedTree(cm, { visibleOnly: true, includeSystemUI: false });
+            const textEntries = (0, text_extractor_js_1.extractText)(tree);
+            const textStrings = (0, text_extractor_js_1.extractTextStrings)(tree);
+            // Deduplicate: trim whitespace, remove empty strings, remove duplicates
+            const deduped = [...new Set(textStrings
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0))];
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            screenText: deduped,
+                            detailed: textEntries,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error extracting screen text: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * get_element_details - Deep inspection of elements matching a search query.
+     */
+    server.tool("get_element_details", "Find and inspect UI elements matching a text query. Returns full details including bounds, class, interactive state, and nearby elements.", {
+        query: zod_1.z.string().describe("Text to search for (case-insensitive substring match)"),
+        includeParent: zod_1.z.boolean().optional().describe("Include parent context for matched elements"),
+    }, async (params) => {
+        try {
+            const tree = await getCachedTree(cm, { visibleOnly: true, includeSystemUI: false });
+            const matches = (0, text_extractor_js_1.findByText)(tree, params.query);
+            if (matches.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                found: 0,
+                                message: `No elements found matching "${params.query}"`,
+                                hint: "Try using get_screen_text to see all visible text first.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const details = matches.map((node) => ({
+                text: node.text,
+                contentDescription: node.contentDescription,
+                className: node.className,
+                resourceId: node.resourceId,
+                bounds: node.bounds,
+                clickable: node.clickable,
+                enabled: node.enabled,
+                focusable: node.focusable,
+                scrollable: node.scrollable,
+                centerX: node.bounds ? Math.round((node.bounds.left + node.bounds.right) / 2) : null,
+                centerY: node.bounds ? Math.round((node.bounds.top + node.bounds.bottom) / 2) : null,
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ found: matches.length, elements: details }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error inspecting elements: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=ui-tree.js.map

package/dist/transport/adb-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb-client.d.ts","sourceRoot":"","sources":["../../src/transport/adb-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3C;;;;;OAKG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB3E;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7E;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAWrC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAuC1C,mDAAmD;IAC7C,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlE,8CAA8C;IACxC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE,kEAAkE;IAClE,IAAI,iBAAiB,IAAI,OAAO,CAE/B;CACF"}

package/dist/transport/adb-client.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * ADB Client - Executes ADB commands against Android devices/emulators.
+ *
+ * Provides a typed interface around the `adb` CLI for shell commands,
+ * device info queries, and general command execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdbClient = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+/** Maximum time (ms) to wait for an ADB command before killing it. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+class AdbClient {
+    adbPath;
+    device;
+    connected = false;
+    constructor(adbPath, device) {
+        this.adbPath = adbPath;
+        this.device = device;
+    }
+    /**
+     * Execute an arbitrary ADB command (not a shell command).
+     * @param args - Arguments passed directly to `adb -s <device> ...args`.
+     * @param timeoutMs - Optional timeout override.
+     * @returns stdout of the command.
+     */
+    async exec(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const fullArgs = ["-s", this.device, ...args];
+        try {
+            const { stdout } = await execFileAsync(this.adbPath, fullArgs, {
+                timeout: timeoutMs,
+                maxBuffer: 10 * 1024 * 1024, // 10 MB
+            });
+            this.connected = true;
+            return stdout;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg.includes("device") && msg.includes("not found")) {
+                this.connected = false;
+            }
+            throw new Error(`ADB command failed [adb ${fullArgs.join(" ")}]: ${msg}`);
+        }
+    }
+    /**
+     * Execute a shell command on the device.
+     * @param command - Shell command string to run via `adb shell`.
+     * @param timeoutMs - Optional timeout override.
+     */
+    async shell(command, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        return this.exec(["shell", command], timeoutMs);
+    }
+    /**
+     * Check whether the device is reachable.
+     */
+    async isConnected() {
+        try {
+            const output = await this.exec(["get-state"], 5_000);
+            this.connected = output.trim() === "device";
+            return this.connected;
+        }
+        catch {
+            this.connected = false;
+            return false;
+        }
+    }
+    /**
+     * Retrieve structured information about the connected device.
+     */
+    async getDeviceInfo() {
+        const prop = async (key) => {
+            try {
+                return (await this.shell(`getprop ${key}`)).trim();
+            }
+            catch {
+                return "unknown";
+            }
+        };
+        const screenSize = await (async () => {
+            try {
+                const raw = await this.shell("wm size");
+                const match = raw.match(/(\d+x\d+)/);
+                return match ? match[1] : "unknown";
+            }
+            catch {
+                return "unknown";
+            }
+        })();
+        const density = await (async () => {
+            try {
+                const raw = await this.shell("wm density");
+                const match = raw.match(/(\d+)/);
+                return match ? match[1] : "unknown";
+            }
+            catch {
+                return "unknown";
+            }
+        })();
+        return {
+            serial: this.device,
+            model: await prop("ro.product.model"),
+            androidVersion: await prop("ro.build.version.release"),
+            sdkVersion: await prop("ro.build.version.sdk"),
+            screenSize,
+            density,
+        };
+    }
+    /** Pull a file from the device to a local path. */
+    async pull(remotePath, localPath) {
+        return this.exec(["pull", remotePath, localPath]);
+    }
+    /** Forward a TCP port from host to device. */
+    async forward(hostPort, devicePort) {
+        await this.exec(["forward", `tcp:${hostPort}`, `tcp:${devicePort}`]);
+    }
+    /** Get the cached connection state (does not ping the device). */
+    get isDeviceConnected() {
+        return this.connected;
+    }
+}
+exports.AdbClient = AdbClient;
+//# sourceMappingURL=adb-client.js.map

package/dist/transport/adb-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb-client.test.d.ts","sourceRoot":"","sources":["../../src/transport/adb-client.test.ts"],"names":[],"mappings":""}

package/dist/transport/adb-client.test.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+// vi.hoisted runs before vi.mock hoisting, so the fn is available in mock factories
+const mockExecFileAsync = vitest_1.vi.hoisted(() => vitest_1.vi.fn());
+vitest_1.vi.mock("node:child_process", () => ({
+    execFile: vitest_1.vi.fn(),
+}));
+vitest_1.vi.mock("node:util", () => ({
+    promisify: () => mockExecFileAsync,
+}));
+const adb_client_js_1 = require("./adb-client.js");
+(0, vitest_1.describe)("AdbClient", () => {
+    let client;
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.clearAllMocks();
+        client = new adb_client_js_1.AdbClient("/usr/bin/adb", "emulator-5554");
+    });
+    (0, vitest_1.describe)("exec()", () => {
+        (0, vitest_1.it)("runs adb with correct device serial and args", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "ok\n" });
+            await client.exec(["shell", "ls"]);
+            (0, vitest_1.expect)(mockExecFileAsync).toHaveBeenCalledWith("/usr/bin/adb", ["-s", "emulator-5554", "shell", "ls"], { timeout: 30_000, maxBuffer: 10 * 1024 * 1024 });
+        });
+        (0, vitest_1.it)("returns stdout from the command", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "file1.txt\nfile2.txt\n" });
+            const result = await client.exec(["shell", "ls"]);
+            (0, vitest_1.expect)(result).toBe("file1.txt\nfile2.txt\n");
+        });
+        (0, vitest_1.it)("throws with descriptive error on failure", async () => {
+            mockExecFileAsync.mockRejectedValue(new Error("command not found"));
+            await (0, vitest_1.expect)(client.exec(["shell", "badcmd"])).rejects.toThrow("ADB command failed [adb -s emulator-5554 shell badcmd]: command not found");
+        });
+        (0, vitest_1.it)("sets connected=true on success", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "ok" });
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(false);
+            await client.exec(["get-state"]);
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(true);
+        });
+        (0, vitest_1.it)('sets connected=false on "device not found" error', async () => {
+            // First succeed to set connected=true
+            mockExecFileAsync.mockResolvedValueOnce({ stdout: "ok" });
+            await client.exec(["get-state"]);
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(true);
+            // Then fail with device not found
+            mockExecFileAsync.mockRejectedValue(new Error("error: device 'emulator-5554' not found"));
+            await (0, vitest_1.expect)(client.exec(["get-state"])).rejects.toThrow();
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(false);
+        });
+        (0, vitest_1.it)("respects custom timeout", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "" });
+            await client.exec(["shell", "slow-cmd"], 5_000);
+            (0, vitest_1.expect)(mockExecFileAsync).toHaveBeenCalledWith("/usr/bin/adb", ["-s", "emulator-5554", "shell", "slow-cmd"], { timeout: 5_000, maxBuffer: 10 * 1024 * 1024 });
+        });
+    });
+    (0, vitest_1.describe)("shell()", () => {
+        (0, vitest_1.it)('delegates to exec with "shell" prefix', async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "result\n" });
+            const result = await client.shell("getprop ro.product.model");
+            (0, vitest_1.expect)(mockExecFileAsync).toHaveBeenCalledWith("/usr/bin/adb", ["-s", "emulator-5554", "shell", "getprop ro.product.model"], vitest_1.expect.objectContaining({ timeout: 30_000 }));
+            (0, vitest_1.expect)(result).toBe("result\n");
+        });
+    });
+    (0, vitest_1.describe)("isConnected()", () => {
+        (0, vitest_1.it)('returns true when device responds "device"', async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "device\n" });
+            const result = await client.isConnected();
+            (0, vitest_1.expect)(result).toBe(true);
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(true);
+        });
+        (0, vitest_1.it)("returns false on timeout/error", async () => {
+            mockExecFileAsync.mockRejectedValue(new Error("timeout"));
+            const result = await client.isConnected();
+            (0, vitest_1.expect)(result).toBe(false);
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(false);
+        });
+        (0, vitest_1.it)("returns false when device state is not 'device'", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "offline\n" });
+            const result = await client.isConnected();
+            (0, vitest_1.expect)(result).toBe(false);
+        });
+        (0, vitest_1.it)("calls get-state with 5s timeout", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "device\n" });
+            await client.isConnected();
+            (0, vitest_1.expect)(mockExecFileAsync).toHaveBeenCalledWith("/usr/bin/adb", ["-s", "emulator-5554", "get-state"], vitest_1.expect.objectContaining({ timeout: 5_000 }));
+        });
+    });
+    (0, vitest_1.describe)("getDeviceInfo()", () => {
+        (0, vitest_1.it)("returns structured device info", async () => {
+            mockExecFileAsync.mockImplementation((_path, args) => {
+                const cmd = args.join(" ");
+                if (cmd.includes("getprop ro.product.model"))
+                    return Promise.resolve({ stdout: "Pixel 7\n" });
+                if (cmd.includes("getprop ro.build.version.release"))
+                    return Promise.resolve({ stdout: "14\n" });
+                if (cmd.includes("getprop ro.build.version.sdk"))
+                    return Promise.resolve({ stdout: "34\n" });
+                if (cmd.includes("wm size"))
+                    return Promise.resolve({ stdout: "Physical size: 1080x2400\n" });
+                if (cmd.includes("wm density"))
+                    return Promise.resolve({ stdout: "Physical density: 420\n" });
+                return Promise.resolve({ stdout: "" });
+            });
+            const info = await client.getDeviceInfo();
+            (0, vitest_1.expect)(info).toEqual({
+                serial: "emulator-5554",
+                model: "Pixel 7",
+                androidVersion: "14",
+                sdkVersion: "34",
+                screenSize: "1080x2400",
+                density: "420",
+            });
+        });
+        (0, vitest_1.it)('returns "unknown" for failed property reads', async () => {
+            mockExecFileAsync.mockRejectedValue(new Error("device offline"));
+            const info = await client.getDeviceInfo();
+            (0, vitest_1.expect)(info).toEqual({
+                serial: "emulator-5554",
+                model: "unknown",
+                androidVersion: "unknown",
+                sdkVersion: "unknown",
+                screenSize: "unknown",
+                density: "unknown",
+            });
+        });
+    });
+    (0, vitest_1.describe)("pull()", () => {
+        (0, vitest_1.it)("delegates to exec with correct args", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "1 file pulled.\n" });
+            const result = await client.pull("/sdcard/screenshot.png", "/tmp/shot.png");
+            (0, vitest_1.expect)(mockExecFileAsync).toHaveBeenCalledWith("/usr/bin/adb", ["-s", "emulator-5554", "pull", "/sdcard/screenshot.png", "/tmp/shot.png"], vitest_1.expect.objectContaining({ timeout: 30_000 }));
+            (0, vitest_1.expect)(result).toBe("1 file pulled.\n");
+        });
+    });
+    (0, vitest_1.describe)("forward()", () => {
+        (0, vitest_1.it)("delegates to exec with tcp format", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "" });
+            await client.forward(8081, 8081);
+            (0, vitest_1.expect)(mockExecFileAsync).toHaveBeenCalledWith("/usr/bin/adb", ["-s", "emulator-5554", "forward", "tcp:8081", "tcp:8081"], vitest_1.expect.objectContaining({ timeout: 30_000 }));
+        });
+    });
+    (0, vitest_1.describe)("isDeviceConnected getter", () => {
+        (0, vitest_1.it)("returns cached state (false initially)", () => {
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(false);
+        });
+        (0, vitest_1.it)("returns true after a successful exec", async () => {
+            mockExecFileAsync.mockResolvedValue({ stdout: "ok" });
+            await client.exec(["version"]);
+            (0, vitest_1.expect)(client.isDeviceConnected).toBe(true);
+        });
+    });
+});
+//# sourceMappingURL=adb-client.test.js.map

package/dist/transport/agent-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client.d.ts","sourceRoot":"","sources":["../../src/transport/agent-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAKtC;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyCxB;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,SAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiCpG;;OAEG;IACH,UAAU,IAAI,IAAI;IAOlB;;OAEG;IACH,WAAW,IAAI,OAAO;IAMtB,+DAA+D;IAC/D,OAAO,CAAC,aAAa;IAgCrB,iEAAiE;IACjE,OAAO,CAAC,gBAAgB;CAUzB"}

package/dist/transport/agent-client.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Agent Client - Communicates with the on-device EmuDebug agent via TCP JSON-RPC.
+ *
+ * The agent runs inside the target app process and provides deep introspection
+ * capabilities (React Native component tree, app state, network interception, etc.)
+ * that are not available through ADB alone.
+ *
+ * Protocol: newline-delimited JSON-RPC 2.0 over a raw TCP socket.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentClient = void 0;
+const node_net_1 = require("node:net");
+/** Default timeout for a single RPC call (ms). */
+const RPC_TIMEOUT_MS = 15_000;
+/** Default TCP connection timeout (ms). */
+const CONNECT_TIMEOUT_MS = 5_000;
+class AgentClient {
+    socket = null;
+    connected = false;
+    nextId = 1;
+    pending = new Map();
+    buffer = "";
+    host;
+    port;
+    constructor(host, port) {
+        this.host = host;
+        this.port = port;
+    }
+    /**
+     * Open a TCP connection to the on-device agent.
+     * Resolves when the connection is established, rejects on timeout or error.
+     */
+    connect() {
+        return new Promise((resolve, reject) => {
+            if (this.connected && this.socket) {
+                resolve();
+                return;
+            }
+            const socket = (0, node_net_1.createConnection)({ host: this.host, port: this.port });
+            const connectTimer = setTimeout(() => {
+                socket.destroy();
+                reject(new Error(`Agent connection timed out after ${CONNECT_TIMEOUT_MS}ms`));
+            }, CONNECT_TIMEOUT_MS);
+            socket.on("connect", () => {
+                clearTimeout(connectTimer);
+                this.socket = socket;
+                this.connected = true;
+                this.buffer = "";
+                resolve();
+            });
+            socket.on("data", (chunk) => {
+                this.buffer += chunk.toString("utf-8");
+                this.processBuffer();
+            });
+            socket.on("close", () => {
+                this.handleDisconnect("Socket closed");
+            });
+            socket.on("error", (err) => {
+                clearTimeout(connectTimer);
+                this.handleDisconnect(err.message);
+                if (!this.connected) {
+                    reject(new Error(`Agent connection failed: ${err.message}`));
+                }
+            });
+        });
+    }
+    /**
+     * Send a JSON-RPC call to the agent and await the response.
+     * @param method - The RPC method name.
+     * @param params - Optional parameters object.
+     * @param timeoutMs - Per-call timeout.
+     */
+    call(method, params, timeoutMs = RPC_TIMEOUT_MS) {
+        return new Promise((resolve, reject) => {
+            if (!this.connected || !this.socket) {
+                reject(new Error("Agent not connected. Call connect() first."));
+                return;
+            }
+            const id = this.nextId++;
+            const request = {
+                jsonrpc: "2.0",
+                id,
+                method,
+                params: params ?? {},
+            };
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`RPC call '${method}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            const payload = JSON.stringify(request) + "\n";
+            this.socket.write(payload, "utf-8", (err) => {
+                if (err) {
+                    clearTimeout(timer);
+                    this.pending.delete(id);
+                    reject(new Error(`Failed to send RPC: ${err.message}`));
+                }
+            });
+        });
+    }
+    /**
+     * Gracefully disconnect from the agent.
+     */
+    disconnect() {
+        if (this.socket) {
+            this.socket.destroy();
+        }
+        this.handleDisconnect("Disconnect requested");
+    }
+    /**
+     * Check whether the agent TCP connection is alive.
+     */
+    isConnected() {
+        return this.connected;
+    }
+    // --- Private helpers ---
+    /** Process newline-delimited JSON messages from the buffer. */
+    processBuffer() {
+        let newlineIdx;
+        while ((newlineIdx = this.buffer.indexOf("\n")) !== -1) {
+            const line = this.buffer.slice(0, newlineIdx).trim();
+            this.buffer = this.buffer.slice(newlineIdx + 1);
+            if (!line)
+                continue;
+            try {
+                const msg = JSON.parse(line);
+                if (msg.id != null && this.pending.has(msg.id)) {
+                    const req = this.pending.get(msg.id);
+                    this.pending.delete(msg.id);
+                    clearTimeout(req.timer);
+                    if (msg.error) {
+                        req.reject(new Error(`RPC error (${msg.error.code}): ${msg.error.message}`));
+                    }
+                    else {
+                        req.resolve(msg.result);
+                    }
+                }
+            }
+            catch {
+                // Ignore unparseable lines
+            }
+        }
+    }
+    /** Clean up connection state and reject all pending requests. */
+    handleDisconnect(reason) {
+        this.connected = false;
+        this.socket = null;
+        for (const [id, req] of this.pending) {
+            clearTimeout(req.timer);
+            req.reject(new Error(`Agent disconnected: ${reason}`));
+            this.pending.delete(id);
+        }
+    }
+}
+exports.AgentClient = AgentClient;
+//# sourceMappingURL=agent-client.js.map

package/dist/transport/agent-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client.test.d.ts","sourceRoot":"","sources":["../../src/transport/agent-client.test.ts"],"names":[],"mappings":""}