@sensaiorg/adapter-android 0.1.0

package/src/transport/agent-client.test.ts

@@ -0,0 +1,267 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { AgentClient } from "./agent-client.js";
+
+// --- Mock Socket ---
+class MockSocket extends EventEmitter {
+  write = vi.fn(
+    (_data: string, _enc: string, cb?: (err?: Error) => void) => {
+      cb?.();
+      return true;
+    },
+  );
+  destroy = vi.fn();
+}
+
+let mockSocket: MockSocket;
+
+vi.mock("node:net", () => ({
+  createConnection: () => {
+    mockSocket = new MockSocket();
+    // Schedule the "connect" event by default (tests can override before it fires)
+    return mockSocket;
+  },
+}));
+
+describe("AgentClient", () => {
+  let client: AgentClient;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    client = new AgentClient("127.0.0.1", 9222);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.clearAllMocks();
+  });
+
+  // Helper: connect the client by emitting the connect event
+  async function connectClient(): Promise<void> {
+    const p = client.connect();
+    mockSocket.emit("connect");
+    await p;
+  }
+
+  describe("connect()", () => {
+    it("resolves on successful connection", async () => {
+      const p = client.connect();
+      // Socket emits connect
+      mockSocket.emit("connect");
+      await expect(p).resolves.toBeUndefined();
+      expect(client.isConnected()).toBe(true);
+    });
+
+    it("rejects on timeout", async () => {
+      const p = client.connect();
+      // Advance past the 5s connect timeout
+      vi.advanceTimersByTime(5_001);
+      await expect(p).rejects.toThrow("Agent connection timed out");
+      expect(mockSocket.destroy).toHaveBeenCalled();
+    });
+
+    it("rejects on connection error", async () => {
+      const p = client.connect();
+      mockSocket.emit("error", new Error("ECONNREFUSED"));
+      await expect(p).rejects.toThrow("Agent connection failed: ECONNREFUSED");
+      expect(client.isConnected()).toBe(false);
+    });
+
+    it("reuses existing connection (no-op)", async () => {
+      await connectClient();
+      // Second connect should resolve immediately without creating a new socket
+      await expect(client.connect()).resolves.toBeUndefined();
+    });
+  });
+
+  describe("call()", () => {
+    it("sends JSON-RPC request with incremented id", async () => {
+      await connectClient();
+
+      // Fire first call
+      const p1 = client.call("getTree", { depth: 2 });
+      const payload1 = JSON.parse(mockSocket.write.mock.calls[0][0].trim());
+      expect(payload1).toEqual({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "getTree",
+        params: { depth: 2 },
+      });
+
+      // Respond
+      mockSocket.emit("data", Buffer.from(JSON.stringify({ id: 1, result: "ok" }) + "\n"));
+      await p1;
+
+      // Fire second call
+      const p2 = client.call("getState");
+      const payload2 = JSON.parse(mockSocket.write.mock.calls[1][0].trim());
+      expect(payload2.id).toBe(2);
+
+      mockSocket.emit("data", Buffer.from(JSON.stringify({ id: 2, result: {} }) + "\n"));
+      await p2;
+    });
+
+    it("resolves with result from response", async () => {
+      await connectClient();
+
+      const p = client.call("getVersion");
+      mockSocket.emit(
+        "data",
+        Buffer.from(JSON.stringify({ id: 1, result: { version: "1.0" } }) + "\n"),
+      );
+
+      await expect(p).resolves.toEqual({ version: "1.0" });
+    });
+
+    it("rejects on RPC error response", async () => {
+      await connectClient();
+
+      const p = client.call("badMethod");
+      mockSocket.emit(
+        "data",
+        Buffer.from(
+          JSON.stringify({
+            id: 1,
+            error: { code: -32601, message: "Method not found" },
+          }) + "\n",
+        ),
+      );
+
+      await expect(p).rejects.toThrow("RPC error (-32601): Method not found");
+    });
+
+    it("rejects on timeout", async () => {
+      await connectClient();
+
+      const p = client.call("slowMethod", undefined, 2_000);
+
+      // No response comes; advance past timeout
+      vi.advanceTimersByTime(2_001);
+
+      await expect(p).rejects.toThrow("RPC call 'slowMethod' timed out after 2000ms");
+    });
+
+    it("rejects if not connected", async () => {
+      await expect(client.call("anyMethod")).rejects.toThrow(
+        "Agent not connected. Call connect() first.",
+      );
+    });
+
+    it("sends empty params when none provided", async () => {
+      await connectClient();
+
+      const p = client.call("ping");
+      const payload = JSON.parse(mockSocket.write.mock.calls[0][0].trim());
+      expect(payload.params).toEqual({});
+
+      mockSocket.emit("data", Buffer.from(JSON.stringify({ id: 1, result: "pong" }) + "\n"));
+      await p;
+    });
+
+    it("rejects when socket write fails", async () => {
+      await connectClient();
+
+      mockSocket.write.mockImplementationOnce(
+        (_data: string, _enc: string, cb?: (err?: Error) => void) => {
+          cb?.(new Error("broken pipe"));
+          return false;
+        },
+      );
+
+      await expect(client.call("test")).rejects.toThrow("Failed to send RPC: broken pipe");
+    });
+  });
+
+  describe("disconnect()", () => {
+    it("cleans up socket and pending requests", async () => {
+      await connectClient();
+
+      // Create a pending request
+      const p = client.call("longRunning");
+
+      client.disconnect();
+
+      expect(mockSocket.destroy).toHaveBeenCalled();
+      expect(client.isConnected()).toBe(false);
+      await expect(p).rejects.toThrow("Agent disconnected");
+    });
+  });
+
+  describe("isConnected()", () => {
+    it("returns false before connecting", () => {
+      expect(client.isConnected()).toBe(false);
+    });
+
+    it("returns true after connecting", async () => {
+      await connectClient();
+      expect(client.isConnected()).toBe(true);
+    });
+
+    it("returns false after disconnect", async () => {
+      await connectClient();
+      client.disconnect();
+      expect(client.isConnected()).toBe(false);
+    });
+  });
+
+  describe("buffer processing", () => {
+    it("handles multiple messages in one chunk", async () => {
+      await connectClient();
+
+      const p1 = client.call("method1");
+      const p2 = client.call("method2");
+
+      // Send both responses in a single data chunk
+      const combined =
+        JSON.stringify({ id: 1, result: "r1" }) +
+        "\n" +
+        JSON.stringify({ id: 2, result: "r2" }) +
+        "\n";
+      mockSocket.emit("data", Buffer.from(combined));
+
+      await expect(p1).resolves.toBe("r1");
+      await expect(p2).resolves.toBe("r2");
+    });
+
+    it("handles split messages across chunks", async () => {
+      await connectClient();
+
+      const p = client.call("method1");
+
+      const full = JSON.stringify({ id: 1, result: "split-result" }) + "\n";
+      const mid = Math.floor(full.length / 2);
+
+      // Send first half
+      mockSocket.emit("data", Buffer.from(full.slice(0, mid)));
+      // Send second half
+      mockSocket.emit("data", Buffer.from(full.slice(mid)));
+
+      await expect(p).resolves.toBe("split-result");
+    });
+  });
+
+  describe("disconnect rejects all pending requests", () => {
+    it("rejects multiple pending requests on disconnect", async () => {
+      await connectClient();
+
+      const p1 = client.call("a");
+      const p2 = client.call("b");
+      const p3 = client.call("c");
+
+      client.disconnect();
+
+      await expect(p1).rejects.toThrow("Agent disconnected");
+      await expect(p2).rejects.toThrow("Agent disconnected");
+      await expect(p3).rejects.toThrow("Agent disconnected");
+    });
+
+    it("rejects pending requests on socket close event", async () => {
+      await connectClient();
+
+      const p = client.call("pending");
+      mockSocket.emit("close");
+
+      await expect(p).rejects.toThrow("Agent disconnected: Socket closed");
+    });
+  });
+});

package/src/transport/agent-client.ts

@@ -0,0 +1,188 @@
+/**
+ * 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.
+ */
+
+import type { Socket } from "node:net";
+import { createConnection } from "node:net";
+
+/** A pending JSON-RPC request awaiting a response. */
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/** 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;
+
+export class AgentClient {
+  private socket: Socket | null = null;
+  private connected = false;
+  private nextId = 1;
+  private pending = new Map<number, PendingRequest>();
+  private buffer = "";
+  private readonly host: string;
+  private readonly port: number;
+
+  constructor(host: string, port: number) {
+    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(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.connected && this.socket) {
+        resolve();
+        return;
+      }
+
+      const socket = 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: Buffer) => {
+        this.buffer += chunk.toString("utf-8");
+        this.processBuffer();
+      });
+
+      socket.on("close", () => {
+        this.handleDisconnect("Socket closed");
+      });
+
+      socket.on("error", (err: Error) => {
+        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: string, params?: Record<string, unknown>, timeoutMs = RPC_TIMEOUT_MS): Promise<unknown> {
+    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(): void {
+    if (this.socket) {
+      this.socket.destroy();
+    }
+    this.handleDisconnect("Disconnect requested");
+  }
+
+  /**
+   * Check whether the agent TCP connection is alive.
+   */
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  // --- Private helpers ---
+
+  /** Process newline-delimited JSON messages from the buffer. */
+  private processBuffer(): void {
+    let newlineIdx: number;
+    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) as {
+          id?: number;
+          result?: unknown;
+          error?: { code: number; message: string; data?: unknown };
+        };
+
+        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. */
+  private handleDisconnect(reason: string): void {
+    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);
+    }
+  }
+}

package/src/transport/connection-manager.ts

@@ -0,0 +1,140 @@
+/**
+ * Connection Manager - Maintains ADB and agent connections with health checks
+ * and automatic reconnection.
+ */
+
+import { AdbClient } from "./adb-client.js";
+import { AgentClient } from "./agent-client.js";
+import { UiTreeCache } from "../util/ui-tree-cache.js";
+
+/** How often to run health checks (ms). */
+const HEALTH_CHECK_INTERVAL_MS = 30_000;
+
+/** Delay before attempting agent reconnection (ms). */
+const RECONNECT_DELAY_MS = 5_000;
+
+/** Maximum consecutive agent reconnect failures before backing off. */
+const MAX_RECONNECT_ATTEMPTS = 3;
+
+export interface ConnectionStatus {
+  adb: boolean;
+  agent: boolean;
+  device: string;
+  agentPort: number;
+}
+
+export class ConnectionManager {
+  readonly adb: AdbClient;
+  readonly agent: AgentClient;
+  readonly uiCache: UiTreeCache;
+  private readonly agentPort: number;
+  private readonly device: string;
+  private healthTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectAttempts = 0;
+
+  constructor(adbPath: string, device: string, agentPort: number) {
+    this.device = device;
+    this.agentPort = agentPort;
+    this.adb = new AdbClient(adbPath, device);
+    this.agent = new AgentClient("127.0.0.1", agentPort);
+    this.uiCache = new UiTreeCache();
+  }
+
+  /**
+   * Initialize connections: verify ADB, set up port forwarding, attempt agent connection.
+   * ADB must succeed; agent connection is best-effort (Phase 2 feature).
+   */
+  async initialize(): Promise<ConnectionStatus> {
+    // ADB is required
+    const adbOk = await this.adb.isConnected();
+    if (!adbOk) {
+      throw new Error(
+        `Device ${this.device} not reachable via ADB. ` +
+        `Ensure the emulator/device is running and 'adb devices' lists it.`
+      );
+    }
+
+    // Forward the agent port (best-effort)
+    try {
+      await this.adb.forward(this.agentPort, this.agentPort);
+    } catch {
+      // Port forwarding may fail if agent isn't installed yet - that's fine
+    }
+
+    // Try connecting to the on-device agent (optional for Phase 1)
+    await this.tryConnectAgent();
+
+    // Start periodic health checks
+    this.startHealthChecks();
+
+    return this.getStatus();
+  }
+
+  /**
+   * Get current connection status.
+   */
+  getStatus(): ConnectionStatus {
+    return {
+      adb: this.adb.isDeviceConnected,
+      agent: this.agent.isConnected(),
+      device: this.device,
+      agentPort: this.agentPort,
+    };
+  }
+
+  /**
+   * Cleanly shut down connections and timers.
+   */
+  shutdown(): void {
+    if (this.healthTimer) {
+      clearInterval(this.healthTimer);
+      this.healthTimer = null;
+    }
+    this.agent.disconnect();
+  }
+
+  // --- Private helpers ---
+
+  /** Attempt agent connection without throwing. */
+  private async tryConnectAgent(): Promise<void> {
+    try {
+      await this.agent.connect();
+      this.reconnectAttempts = 0;
+    } catch {
+      // Agent not available - Phase 1 operates without it
+    }
+  }
+
+  /** Periodic health check: verify ADB, reconnect agent if dropped. */
+  private startHealthChecks(): void {
+    this.healthTimer = setInterval(async () => {
+      // Check ADB
+      try {
+        await this.adb.isConnected();
+      } catch {
+        // ADB went away - not much we can do automatically
+      }
+
+      // Reset reconnect counter if agent is healthy
+      if (this.agent.isConnected()) {
+        this.reconnectAttempts = 0;
+      }
+
+      // Reconnect agent if it dropped
+      if (!this.agent.isConnected() && this.reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
+        this.reconnectAttempts++;
+        await this.sleep(RECONNECT_DELAY_MS);
+        await this.tryConnectAgent();
+      }
+    }, HEALTH_CHECK_INTERVAL_MS);
+
+    // Don't keep the process alive just for health checks
+    if (this.healthTimer.unref) {
+      this.healthTimer.unref();
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/util/logcat-parser.ts

@@ -0,0 +1,94 @@
+/**
+ * Logcat Parser - Parses Android logcat output into structured entries.
+ *
+ * Supports the "threadtime" format which is the default for `adb logcat -v threadtime`.
+ * Format: "MM-DD HH:MM:SS.mmm  PID  TID LEVEL TAG: MESSAGE"
+ */
+
+/** Log severity levels in ascending order. */
+export type LogLevel = "V" | "D" | "I" | "W" | "E" | "F";
+
+/** A single parsed logcat entry. */
+export interface LogEntry {
+  timestamp: string;
+  pid: string;
+  tid: string;
+  level: LogLevel;
+  tag: string;
+  message: string;
+}
+
+/** Regex for threadtime logcat format. */
+const THREADTIME_RE =
+  /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d{3})\s+(\d+)\s+(\d+)\s+([VDIWEF])\s+(.+?):\s+(.*)$/;
+
+/** Level priorities for filtering. */
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  V: 0,
+  D: 1,
+  I: 2,
+  W: 3,
+  E: 4,
+  F: 5,
+};
+
+/**
+ * Parse raw logcat output into structured entries.
+ *
+ * @param raw - Raw logcat text (threadtime format).
+ * @returns Array of parsed log entries.
+ */
+export function parseLogcat(raw: string): LogEntry[] {
+  const lines = raw.split("\n");
+  const entries: LogEntry[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("-----")) continue;
+
+    const match = trimmed.match(THREADTIME_RE);
+    if (match) {
+      entries.push({
+        timestamp: match[1],
+        pid: match[2],
+        tid: match[3],
+        level: match[4] as LogLevel,
+        tag: match[5].trim(),
+        message: match[6],
+      });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Filter log entries by minimum level.
+ */
+export function filterByLevel(entries: LogEntry[], minLevel: LogLevel): LogEntry[] {
+  const minPriority = LEVEL_PRIORITY[minLevel];
+  return entries.filter((e) => LEVEL_PRIORITY[e.level] >= minPriority);
+}
+
+/**
+ * Filter log entries by tag (case-insensitive substring match).
+ */
+export function filterByTag(entries: LogEntry[], tag: string): LogEntry[] {
+  const lower = tag.toLowerCase();
+  return entries.filter((e) => e.tag.toLowerCase().includes(lower));
+}
+
+/**
+ * Filter log entries by grep pattern (applied to message, case-insensitive).
+ */
+export function filterByGrep(entries: LogEntry[], pattern: string): LogEntry[] {
+  const re = new RegExp(pattern, "i");
+  return entries.filter((e) => re.test(e.message) || re.test(e.tag));
+}
+
+/**
+ * Format a log entry back to a human-readable string.
+ */
+export function formatEntry(entry: LogEntry): string {
+  return `${entry.timestamp} ${entry.pid} ${entry.tid} ${entry.level} ${entry.tag}: ${entry.message}`;
+}