@sensaiorg/adapter-android 0.1.0

package/dist/util/ui-tree-parser.test.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const ui_tree_parser_js_1 = require("./ui-tree-parser.js");
+const MINIMAL_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<hierarchy rotation="0">
+  <node index="0" text="Hello" resource-id="com.example:id/greeting"
+        class="android.widget.TextView" package="com.example"
+        content-desc="Greeting text" checkable="false" checked="false"
+        clickable="true" enabled="true" focusable="true" focused="false"
+        scrollable="false" long-clickable="false" password="false"
+        selected="false" bounds="[0,0][500,100]">
+  </node>
+</hierarchy>`;
+const NESTED_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<hierarchy rotation="0">
+  <node index="0" text="" resource-id="" class="android.widget.FrameLayout"
+        package="com.example" content-desc="" checkable="false" checked="false"
+        clickable="false" enabled="true" focusable="false" focused="false"
+        scrollable="false" long-clickable="false" password="false"
+        selected="false" bounds="[0,0][1080,1920]">
+    <node index="0" text="Button 1" resource-id="com.example:id/btn1"
+          class="android.widget.Button" package="com.example"
+          content-desc="First button" checkable="false" checked="false"
+          clickable="true" enabled="true" focusable="true" focused="false"
+          scrollable="false" long-clickable="false" password="false"
+          selected="false" bounds="[50,100][300,200]">
+    </node>
+    <node index="1" text="Button 2" resource-id="com.example:id/btn2"
+          class="android.widget.Button" package="com.example"
+          content-desc="" checkable="false" checked="false"
+          clickable="true" enabled="true" focusable="true" focused="false"
+          scrollable="false" long-clickable="false" password="false"
+          selected="false" bounds="[50,250][300,350]">
+    </node>
+  </node>
+</hierarchy>`;
+const SYSTEM_UI_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<hierarchy rotation="0">
+  <node index="0" text="12:00" resource-id="" class="android.widget.TextView"
+        package="com.android.systemui" content-desc="" checkable="false" checked="false"
+        clickable="false" enabled="true" focusable="false" focused="false"
+        scrollable="false" long-clickable="false" password="false"
+        selected="false" bounds="[0,0][100,50]">
+  </node>
+  <node index="1" text="App Content" resource-id="" class="android.widget.TextView"
+        package="com.example" content-desc="" checkable="false" checked="false"
+        clickable="false" enabled="true" focusable="false" focused="false"
+        scrollable="false" long-clickable="false" password="false"
+        selected="false" bounds="[0,50][1080,1920]">
+  </node>
+</hierarchy>`;
+(0, vitest_1.describe)("parseUiTree", () => {
+    (0, vitest_1.it)("parses minimal XML with one node", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(MINIMAL_XML);
+        (0, vitest_1.expect)(nodes).toHaveLength(1);
+        const node = nodes[0];
+        (0, vitest_1.expect)(node.text).toBe("Hello");
+        (0, vitest_1.expect)(node.resourceId).toBe("com.example:id/greeting");
+        (0, vitest_1.expect)(node.className).toBe("android.widget.TextView");
+        (0, vitest_1.expect)(node.contentDescription).toBe("Greeting text");
+        (0, vitest_1.expect)(node.clickable).toBe(true);
+        (0, vitest_1.expect)(node.enabled).toBe(true);
+        (0, vitest_1.expect)(node.focusable).toBe(true);
+        (0, vitest_1.expect)(node.scrollable).toBe(false);
+        (0, vitest_1.expect)(node.checked).toBe(false);
+        (0, vitest_1.expect)(node.selected).toBe(false);
+        (0, vitest_1.expect)(node.packageName).toBe("com.example");
+        (0, vitest_1.expect)(node.depth).toBe(0);
+        (0, vitest_1.expect)(node.bounds).toEqual({ left: 0, top: 0, right: 500, bottom: 100 });
+        (0, vitest_1.expect)(node.children).toHaveLength(0);
+    });
+    (0, vitest_1.it)("parses nested nodes", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(NESTED_XML);
+        (0, vitest_1.expect)(nodes).toHaveLength(1);
+        (0, vitest_1.expect)(nodes[0].children).toHaveLength(2);
+        (0, vitest_1.expect)(nodes[0].children[0].text).toBe("Button 1");
+        (0, vitest_1.expect)(nodes[0].children[1].text).toBe("Button 2");
+        (0, vitest_1.expect)(nodes[0].children[0].depth).toBe(1);
+    });
+    (0, vitest_1.it)("filters system UI by default", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(SYSTEM_UI_XML);
+        (0, vitest_1.expect)(nodes).toHaveLength(1);
+        (0, vitest_1.expect)(nodes[0].text).toBe("App Content");
+    });
+    (0, vitest_1.it)("includes system UI when requested", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(SYSTEM_UI_XML, { includeSystemUI: true });
+        (0, vitest_1.expect)(nodes).toHaveLength(2);
+    });
+    (0, vitest_1.it)("respects maxDepth", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(NESTED_XML, { maxDepth: 1 });
+        (0, vitest_1.expect)(nodes).toHaveLength(1);
+        // maxDepth=1 means depth 0 is included, children at depth 1 are included but not their children
+        (0, vitest_1.expect)(nodes[0].children).toHaveLength(2);
+    });
+    (0, vitest_1.it)("maxDepth=0 means unlimited", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(NESTED_XML, { maxDepth: 0 });
+        (0, vitest_1.expect)(nodes[0].children).toHaveLength(2);
+    });
+    (0, vitest_1.it)("returns empty array for empty hierarchy", () => {
+        const xml = `<?xml version="1.0" encoding="UTF-8"?><hierarchy rotation="0"></hierarchy>`;
+        (0, vitest_1.expect)((0, ui_tree_parser_js_1.parseUiTree)(xml)).toEqual([]);
+    });
+    (0, vitest_1.it)("returns empty array for missing hierarchy", () => {
+        const xml = `<?xml version="1.0" encoding="UTF-8"?><root></root>`;
+        (0, vitest_1.expect)((0, ui_tree_parser_js_1.parseUiTree)(xml)).toEqual([]);
+    });
+    (0, vitest_1.it)("returns empty array for non-XML input", () => {
+        // fast-xml-parser is lenient — doesn't throw on all malformed input
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)("not xml at all");
+        (0, vitest_1.expect)(nodes).toEqual([]);
+    });
+    (0, vitest_1.it)("handles node with no bounds", () => {
+        const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<hierarchy rotation="0">
+  <node index="0" text="NoBounds" resource-id="" class="android.view.View"
+        package="com.example" content-desc="" checkable="false" checked="false"
+        clickable="false" enabled="true" focusable="false" focused="false"
+        scrollable="false" long-clickable="false" password="false"
+        selected="false" bounds="">
+  </node>
+</hierarchy>`;
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(xml);
+        (0, vitest_1.expect)(nodes).toHaveLength(1);
+        (0, vitest_1.expect)(nodes[0].bounds).toBeNull();
+        (0, vitest_1.expect)(nodes[0].visible).toBe(false);
+    });
+    (0, vitest_1.it)("filters invisible nodes with visibleOnly", () => {
+        const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<hierarchy rotation="0">
+  <node index="0" text="Visible" resource-id="" class="android.view.View"
+        package="com.example" content-desc="" checkable="false" checked="false"
+        clickable="false" enabled="true" focusable="false" focused="false"
+        scrollable="false" long-clickable="false" password="false"
+        selected="false" bounds="[0,0][100,100]">
+  </node>
+  <node index="1" text="Invisible" resource-id="" class="android.view.View"
+        package="com.example" content-desc="" checkable="false" checked="false"
+        clickable="false" enabled="true" focusable="false" focused="false"
+        scrollable="false" long-clickable="false" password="false"
+        selected="false" bounds="">
+  </node>
+</hierarchy>`;
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(xml, { visibleOnly: true });
+        (0, vitest_1.expect)(nodes).toHaveLength(1);
+        (0, vitest_1.expect)(nodes[0].text).toBe("Visible");
+    });
+});
+(0, vitest_1.describe)("flattenTree", () => {
+    (0, vitest_1.it)("flattens nested tree to array", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(NESTED_XML);
+        const flat = (0, ui_tree_parser_js_1.flattenTree)(nodes);
+        (0, vitest_1.expect)(flat).toHaveLength(3); // root + 2 children
+        (0, vitest_1.expect)(flat[0].className).toBe("android.widget.FrameLayout");
+        (0, vitest_1.expect)(flat[1].text).toBe("Button 1");
+        (0, vitest_1.expect)(flat[2].text).toBe("Button 2");
+    });
+    (0, vitest_1.it)("handles empty array", () => {
+        (0, vitest_1.expect)((0, ui_tree_parser_js_1.flattenTree)([])).toEqual([]);
+    });
+    (0, vitest_1.it)("handles single node", () => {
+        const nodes = (0, ui_tree_parser_js_1.parseUiTree)(MINIMAL_XML);
+        const flat = (0, ui_tree_parser_js_1.flattenTree)(nodes);
+        (0, vitest_1.expect)(flat).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=ui-tree-parser.test.js.map

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@sensaiorg/adapter-android",
+  "version": "0.1.0",
+  "description": "SensAI Android adapter — debug Android apps via ADB and on-device agent",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist .tsbuildinfo"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@sensaiorg/core": "0.1.0",
+    "fast-xml-parser": "^4.5.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "zod": "^3.24.0"
+  }
+}

package/src/android-adapter.ts

@@ -0,0 +1,124 @@
+/**
+ * AndroidAdapter — implements IPlatformAdapter for Android devices/emulators.
+ *
+ * Phase 1: All tools work via ADB commands (uiautomator, logcat, input, dumpsys)
+ * Phase 2: On-device agent provides faster UI tree, React Native inspection, network capture
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type {
+  IPlatformAdapter,
+  IUiProvider,
+  ILogProvider,
+  IInteractionProvider,
+  INetworkProvider,
+  IPerformanceProvider,
+  IScreenshotProvider,
+  IAppStateProvider,
+  PlatformCapabilities,
+  ConnectionStatus,
+} from "@sensai/core";
+
+import { ConnectionManager } from "./transport/connection-manager.js";
+import { registerAllTools } from "./tools/index.js";
+
+export interface AndroidAdapterConfig {
+  adbDevice?: string;
+  adbPath?: string;
+  agentPort?: number;
+  targetPackage?: string;
+}
+
+export class AndroidAdapter implements IPlatformAdapter {
+  readonly platform = "android" as const;
+  readonly displayName: string;
+  readonly capabilities: PlatformCapabilities = {
+    uiTree: true,
+    logs: true,
+    interaction: true,
+    network: false,      // Phase 2 (agent needed)
+    performance: true,
+    screenshot: true,
+    appState: false,     // Phase 2 (agent needed)
+    hotReload: true,
+    evalCode: false,
+  };
+
+  private readonly connectionManager: ConnectionManager;
+  private readonly config: Required<AndroidAdapterConfig>;
+
+  // Providers — implemented inline for now, will be extracted to separate classes
+  readonly ui: IUiProvider | null = null;        // TODO: Extract from tools/ui-tree.ts
+  readonly logs: ILogProvider | null = null;      // TODO: Extract from tools/logcat.ts
+  readonly interaction: IInteractionProvider | null = null;  // TODO: Extract from tools/interaction.ts
+  readonly network: INetworkProvider | null = null;
+  readonly performance: IPerformanceProvider | null = null;
+  readonly screenshot: IScreenshotProvider | null = null;
+  readonly appState: IAppStateProvider | null = null;
+
+  constructor(config: AndroidAdapterConfig = {}) {
+    this.config = {
+      adbDevice: config.adbDevice ?? process.env.ADB_DEVICE ?? "emulator-5554",
+      adbPath: config.adbPath ?? process.env.ADB_PATH ?? "adb",
+      agentPort: config.agentPort ?? parseInt(process.env.DEBUG_AGENT_PORT ?? "8463", 10),
+      targetPackage: config.targetPackage ?? process.env.TARGET_PACKAGE ?? "com.chronocrew",
+    };
+
+    this.displayName = `Android (${this.config.adbDevice})`;
+
+    this.connectionManager = new ConnectionManager(
+      this.config.adbPath,
+      this.config.adbDevice,
+      this.config.agentPort,
+    );
+  }
+
+  async initialize(): Promise<ConnectionStatus> {
+    const status = await this.connectionManager.initialize();
+
+    // Update capabilities if agent is available
+    if (status.agent) {
+      this.capabilities.network = true;
+      this.capabilities.appState = true;
+    }
+
+    return {
+      platform: "android",
+      device: status.device,
+      connected: status.adb,
+      capabilities: this.capabilities,
+      details: {
+        adb: status.adb,
+        agent: status.agent,
+        targetPackage: this.config.targetPackage,
+      },
+    };
+  }
+
+  shutdown(): void {
+    this.connectionManager.shutdown();
+  }
+
+  isConnected(): boolean {
+    return this.connectionManager.getStatus().adb;
+  }
+
+  /**
+   * Get the ConnectionManager for direct tool access.
+   * Used during the migration period before full provider extraction.
+   */
+  getConnectionManager(): ConnectionManager {
+    return this.connectionManager;
+  }
+
+  /**
+   * Register Android-only MCP tools.
+   * These have no cross-platform equivalent.
+   */
+  registerPlatformTools(server: McpServer): void {
+    const cm = this.connectionManager;
+
+    // Register all 22 Android debugging tools
+    registerAllTools(server, cm);
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @sensai/adapter-android — Android platform adapter for SensAI.
+ *
+ * Provides 22 debugging tools via ADB (Phase 1) and on-device agent (Phase 2).
+ * This adapter wraps the original EmuDebug MCP server tools.
+ */
+
+export { AndroidAdapter } from "./android-adapter.js";

package/src/tools/accessibility.ts

@@ -0,0 +1,94 @@
+/**
+ * Accessibility Tool - Retrieve the Android accessibility tree.
+ *
+ * Uses `adb shell dumpsys accessibility` to get the accessibility service's
+ * view of the screen, which is richer than uiautomator for a11y auditing.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+
+// A11yNode type reserved for Phase 2 structured accessibility tree parsing.
+
+/**
+ * Parse the raw accessibility dump into a structured tree.
+ * The dump format is indentation-based with key: value pairs.
+ */
+function parseAccessibilityDump(raw: string): { services: string[]; windows: string; nodeCount: number } {
+  const lines = raw.split("\n");
+  const services: string[] = [];
+  let nodeCount = 0;
+
+  for (const line of lines) {
+    if (line.includes("Service[")) {
+      const match = line.match(/Service\[(.+?)]/);
+      if (match) services.push(match[1]);
+    }
+    if (line.includes("className:") || line.includes("class:")) {
+      nodeCount++;
+    }
+  }
+
+  return {
+    services,
+    windows: raw,
+    nodeCount,
+  };
+}
+
+export function registerAccessibilityTools(server: McpServer, cm: ConnectionManager): void {
+  server.tool(
+    "get_accessibility",
+    "Get the Android accessibility tree for the current screen. Shows which elements are accessible, their roles, states, and actions. Useful for auditing screen reader compatibility.",
+    {},
+    async () => {
+      try {
+        // Try the agent first for a richer accessibility tree
+        if (cm.agent.isConnected()) {
+          try {
+            const result = await cm.agent.call("getAccessibilityTree");
+            return {
+              content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            };
+          } catch {
+            // Fall through to ADB
+          }
+        }
+
+        // ADB fallback: use accessibility dumpsys
+        const dump = await cm.adb.shell("dumpsys accessibility");
+        const parsed = parseAccessibilityDump(dump);
+
+        // Also get window info for additional context
+        let windowInfo = "";
+        try {
+          windowInfo = await cm.adb.shell("dumpsys window windows | head -50");
+        } catch {
+          // Non-critical
+        }
+
+        const result = {
+          accessibilityServices: parsed.services,
+          estimatedNodeCount: parsed.nodeCount,
+          currentWindow: windowInfo.trim(),
+          rawDump: parsed.windows,
+          note: "For a structured accessibility tree, install the EmuDebug on-device agent (Phase 2).",
+        };
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error getting accessibility tree: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/adb.ts

@@ -0,0 +1,75 @@
+/**
+ * ADB Passthrough Tool - Execute safe ADB commands on the connected device.
+ *
+ * Commands are validated against an allowlist before execution to prevent
+ * destructive operations. See util/safety.ts for the allowlist.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+import { validateAdbCommand, parseCommandString } from "../util/safety.js";
+
+export function registerAdbTools(server: McpServer, cm: ConnectionManager): void {
+  server.tool(
+    "run_adb",
+    "Execute an ADB command on the connected device. Commands are validated against a safety allowlist. Allowed: shell, pull, push, install, uninstall, logcat, bugreport, devices, forward, reverse. Blocked: root, remount, reboot-bootloader, sideload, and destructive shell commands.",
+    {
+      command: z
+        .string()
+        .describe(
+          "ADB command to execute (without the leading 'adb -s <device>' prefix). " +
+          "Example: 'shell ls /sdcard' or 'logcat -d -t 50'",
+        ),
+      timeoutMs: z.number().optional().describe("Timeout in milliseconds (default: 30000, max: 60000)"),
+    },
+    async (params) => {
+      try {
+        const args = parseCommandString(params.command);
+
+        // Validate against safety allowlist
+        const validation = validateAdbCommand(args);
+        if (!validation.allowed) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  success: false,
+                  error: "Command blocked by safety check",
+                  reason: validation.reason,
+                }),
+              },
+            ],
+          };
+        }
+
+        const timeoutMs = Math.min(params.timeoutMs ?? 30_000, 60_000);
+        const output = await cm.adb.exec(args, timeoutMs);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                success: true,
+                command: `adb ${args.join(" ")}`,
+                output: output.trim(),
+              }),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `ADB command error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/app-state.ts

@@ -0,0 +1,193 @@
+/**
+ * App State Tool - Inspect the target application's internal state.
+ *
+ * Retrieves AsyncStorage, React Query cache, navigation state, auth tokens,
+ * theme, feature flags, and offline queue data from the running app.
+ *
+ * Requires the on-device agent for full data. In Phase 1, reads what is
+ * accessible via ADB (SharedPreferences, app data files).
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+
+/** State categories that can be requested. */
+const STATE_CATEGORIES = [
+  "asyncStorage",
+  "queryCache",
+  "navigation",
+  "auth",
+  "theme",
+  "featureFlags",
+  "offlineQueue",
+] as const;
+
+type StateCategory = (typeof STATE_CATEGORIES)[number];
+
+export function registerAppStateTools(server: McpServer, cm: ConnectionManager): void {
+  server.tool(
+    "get_app_state",
+    "Inspect the target app's internal state including AsyncStorage, React Query cache, navigation state, auth info, theme, feature flags, and offline queue. Select specific categories or get all.",
+    {
+      categories: z
+        .array(z.enum(STATE_CATEGORIES))
+        .optional()
+        .describe("Which state categories to retrieve (default: all)"),
+      asyncStorageKeys: z
+        .array(z.string())
+        .optional()
+        .describe("Specific AsyncStorage keys to read (default: all)"),
+      queryCacheFilter: z.string().optional().describe("Filter query cache by key prefix"),
+    },
+    async (params) => {
+      const categories = (params.categories ?? [...STATE_CATEGORIES]) as StateCategory[];
+      const targetPackage = process.env.TARGET_PACKAGE ?? "com.emudebug.target";
+
+      // Phase 2: agent provides full app state
+      if (cm.agent.isConnected()) {
+        try {
+          const result = await cm.agent.call("getAppState", {
+            categories,
+            asyncStorageKeys: params.asyncStorageKeys,
+            queryCacheFilter: params.queryCacheFilter,
+          });
+
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Agent error getting app state: ${err instanceof Error ? err.message : String(err)}. Falling back to ADB.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      // Phase 1: limited state via ADB
+      try {
+        const state: Record<string, unknown> = {
+          _phase1Note:
+            "Limited app state available via ADB. Install the on-device agent for full " +
+            "AsyncStorage, React Query cache, navigation, and auth state inspection.",
+        };
+
+        // AsyncStorage: RN stores in SQLite database (accessible if debuggable or rooted)
+        if (categories.includes("asyncStorage")) {
+          try {
+            const dbPath = `/data/data/${targetPackage}/databases/RKStorage`;
+            const output = await cm.adb.shell(
+              `run-as ${targetPackage} sqlite3 ${dbPath} "SELECT key, value FROM catalystLocalStorage LIMIT 50;"`,
+            );
+            const rows: Record<string, string> = {};
+            for (const line of output.trim().split("\n")) {
+              const sep = line.indexOf("|");
+              if (sep > 0) {
+                rows[line.slice(0, sep)] = line.slice(sep + 1);
+              }
+            }
+            state.asyncStorage = {
+              entries: rows,
+              count: Object.keys(rows).length,
+              note: "Retrieved via run-as + sqlite3 (requires debuggable app).",
+            };
+          } catch {
+            state.asyncStorage = {
+              error: "Cannot read AsyncStorage via ADB. App may not be debuggable.",
+              hint: "Use the on-device agent or ensure the app has android:debuggable=true.",
+            };
+          }
+        }
+
+        // SharedPreferences: accessible via run-as
+        if (categories.includes("featureFlags") || categories.includes("theme")) {
+          try {
+            const prefsDir = `/data/data/${targetPackage}/shared_prefs/`;
+            const files = await cm.adb.shell(`run-as ${targetPackage} ls ${prefsDir}`);
+            const prefsFiles = files.trim().split("\n").filter(Boolean);
+
+            const prefs: Record<string, string> = {};
+            for (const file of prefsFiles.slice(0, 5)) {
+              try {
+                const content = await cm.adb.shell(
+                  `run-as ${targetPackage} cat ${prefsDir}${file}`,
+                );
+                prefs[file] = content.trim();
+              } catch {
+                prefs[file] = "(unreadable)";
+              }
+            }
+
+            if (categories.includes("featureFlags")) {
+              state.featureFlags = { sharedPreferences: prefs };
+            }
+            if (categories.includes("theme")) {
+              state.theme = { sharedPreferences: prefs };
+            }
+          } catch {
+            if (categories.includes("featureFlags")) {
+              state.featureFlags = { error: "Cannot read SharedPreferences via ADB." };
+            }
+            if (categories.includes("theme")) {
+              state.theme = { error: "Cannot read SharedPreferences via ADB." };
+            }
+          }
+        }
+
+        // Navigation: infer from activity stack
+        if (categories.includes("navigation")) {
+          try {
+            const activityDump = await cm.adb.shell(
+              `dumpsys activity activities | grep -A5 "mResumedActivity\\|topResumedActivity"`,
+            );
+            state.navigation = {
+              currentActivity: activityDump.trim(),
+              note: "Full React Navigation state requires the on-device agent.",
+            };
+          } catch {
+            state.navigation = { error: "Cannot determine current activity." };
+          }
+        }
+
+        // Auth: check for token files (surface-level only)
+        if (categories.includes("auth")) {
+          state.auth = {
+            note: "Auth token inspection requires the on-device agent. " +
+              "Check AsyncStorage for token keys or use get_logcat with auth-related tags.",
+          };
+        }
+
+        // Query cache and offline queue require the agent
+        if (categories.includes("queryCache")) {
+          state.queryCache = {
+            note: "React Query cache inspection requires the on-device agent.",
+          };
+        }
+        if (categories.includes("offlineQueue")) {
+          state.offlineQueue = {
+            note: "Offline queue inspection requires the on-device agent.",
+          };
+        }
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(state) }],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error getting app state: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}