deepadb 1.0.0

package/build/bridge/adb-bridge.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ADB Bridge — Core subprocess wrapper for all ADB interactions.
+ *
+ * Every ADB command in DeepADB flows through this module.
+ * Handles: subprocess spawning, timeout enforcement, error normalization,
+ * device serial routing, output capture, and transient failure retry.
+ */
+import { ChildProcess } from "child_process";
+import { Logger } from "../middleware/logger.js";
+export interface AdbResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+    bufferExceeded: boolean;
+    device?: string;
+}
+export interface AdbExecOptions {
+    /** Target device serial. Falls back to config.defaultDevice. */
+    device?: string;
+    /** Timeout in ms. Falls back to config.commandTimeout. */
+    timeout?: number;
+    /** If true, don't throw on non-zero exit codes */
+    ignoreExitCode?: boolean;
+    /** Override retry count for this call (0 = no retry) */
+    retries?: number;
+}
+export declare class AdbBridge {
+    private adbPath;
+    private logger;
+    constructor(logger: Logger);
+    /**
+     * Execute an ADB command with automatic retry on transient failures.
+     * This is the single entry point for all ADB subprocess calls.
+     */
+    exec(args: string[], options?: AdbExecOptions): Promise<AdbResult>;
+    private sleep;
+    /**
+     * Single-attempt ADB execution (no retry).
+     */
+    private execOnce;
+    /** Execute an ADB shell command on the device. */
+    shell(command: string, options?: AdbExecOptions): Promise<AdbResult>;
+    /** Execute a root shell command (via su). */
+    rootShell(command: string, options?: AdbExecOptions): Promise<AdbResult>;
+    /** Verify ADB is accessible and return version info. */
+    version(): Promise<string>;
+    /** Check if ADB server is running and reachable. */
+    ping(): Promise<boolean>;
+    /**
+     * Spawn a long-running ADB command as a streaming child process.
+     * Used by logcat watchers and RIL interceptors that need continuous output.
+     * Returns the ChildProcess — caller manages stdout/stderr/lifecycle.
+     *
+     * In ADB mode: spawns `adb -s <serial> <args...>`
+     * LocalBridge overrides this to spawn commands directly.
+     */
+    spawnStreaming(args: string[], device?: string): ChildProcess;
+}
+/** Structured error type for ADB failures. */
+export declare class AdbError extends Error {
+    readonly result: AdbResult;
+    constructor(message: string, result: AdbResult);
+}
+//# sourceMappingURL=adb-bridge.d.ts.map

package/build/bridge/adb-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb-bridge.d.ts","sourceRoot":"","sources":["../../src/bridge/adb-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAoC,YAAY,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGjD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkBD,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAK1B;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAuB5E,OAAO,CAAC,KAAK;IAIb;;OAEG;YACW,QAAQ;IAiEtB,kDAAkD;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAI9E,6CAA6C;IACvC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAIlF,wDAAwD;IAClD,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAKhC,oDAAoD;IAC9C,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAS9B;;;;;;;OAOG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY;CAe9D;AAED,8CAA8C;AAC9C,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,MAAM,EAAE,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS;CAK/C"}

package/build/bridge/adb-bridge.js

@@ -0,0 +1,164 @@
+/**
+ * ADB Bridge — Core subprocess wrapper for all ADB interactions.
+ *
+ * Every ADB command in DeepADB flows through this module.
+ * Handles: subprocess spawning, timeout enforcement, error normalization,
+ * device serial routing, output capture, and transient failure retry.
+ */
+import { execFile, spawn } from "child_process";
+import { config } from "../config/config.js";
+import { shellEscape } from "../middleware/sanitize.js";
+/** Patterns in stderr/message that indicate a transient, retryable failure. */
+const TRANSIENT_PATTERNS = [
+    "device not found",
+    "device offline",
+    "no devices/emulators found",
+    "protocol fault",
+    "closed",
+    "Connection reset",
+    "ECONNRESET",
+];
+function isTransientError(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return TRANSIENT_PATTERNS.some((p) => msg.includes(p));
+}
+export class AdbBridge {
+    adbPath;
+    logger;
+    constructor(logger) {
+        this.adbPath = config.adbPath;
+        this.logger = logger;
+    }
+    /**
+     * Execute an ADB command with automatic retry on transient failures.
+     * This is the single entry point for all ADB subprocess calls.
+     */
+    async exec(args, options = {}) {
+        const maxRetries = options.retries ?? config.retryCount;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await this.execOnce(args, options);
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxRetries && isTransientError(error)) {
+                    const delay = config.retryBaseDelay * Math.pow(2, attempt);
+                    this.logger.warn(`Transient ADB failure (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms: ${error instanceof Error ? error.message : error}`);
+                    await this.sleep(delay);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw lastError; // Should never reach here, but TypeScript needs it
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Single-attempt ADB execution (no retry).
+     */
+    async execOnce(args, options) {
+        const device = options.device || config.defaultDevice;
+        const timeout = options.timeout || config.commandTimeout;
+        const fullArgs = [];
+        if (device) {
+            fullArgs.push("-s", device);
+        }
+        fullArgs.push(...args);
+        this.logger.debug(`adb ${fullArgs.join(" ")}`);
+        return new Promise((resolve, reject) => {
+            const execOptions = {
+                timeout,
+                maxBuffer: config.maxOutputSize * 2,
+                windowsHide: true,
+            };
+            execFile(this.adbPath, fullArgs, execOptions, (error, stdout, stderr) => {
+                const bufferExceeded = error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+                    || error?.message?.includes("maxBuffer") === true;
+                const timedOut = error?.killed === true && !bufferExceeded;
+                const exitCode = error?.code != null
+                    ? (typeof error.code === "number" ? error.code : 1)
+                    : 0;
+                const result = {
+                    stdout: stdout?.toString() ?? "",
+                    stderr: stderr?.toString() ?? "",
+                    exitCode,
+                    timedOut,
+                    bufferExceeded,
+                    device: device || undefined,
+                };
+                this.logger.debug(`Exit: ${exitCode}, timedOut: ${timedOut}, bufferExceeded: ${bufferExceeded}, stdout: ${result.stdout.length} chars`);
+                if (timedOut) {
+                    reject(new AdbError(`Command timed out after ${timeout}ms: adb ${fullArgs.join(" ")}`, result));
+                    return;
+                }
+                if (bufferExceeded) {
+                    this.logger.warn(`Output exceeded maxBuffer, returning partial result`);
+                    resolve(result);
+                    return;
+                }
+                if (exitCode !== 0 && !options.ignoreExitCode) {
+                    reject(new AdbError(`ADB command failed (exit ${exitCode}): ${result.stderr || result.stdout}`.trim(), result));
+                    return;
+                }
+                resolve(result);
+            });
+        });
+    }
+    /** Execute an ADB shell command on the device. */
+    async shell(command, options = {}) {
+        return this.exec(["shell", command], options);
+    }
+    /** Execute a root shell command (via su). */
+    async rootShell(command, options = {}) {
+        return this.exec(["shell", `su -c '${shellEscape(command)}'`], options);
+    }
+    /** Verify ADB is accessible and return version info. */
+    async version() {
+        const result = await this.exec(["version"], { retries: 0 });
+        return result.stdout.trim();
+    }
+    /** Check if ADB server is running and reachable. */
+    async ping() {
+        try {
+            await this.exec(["devices"], { timeout: 5000, retries: 0 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Spawn a long-running ADB command as a streaming child process.
+     * Used by logcat watchers and RIL interceptors that need continuous output.
+     * Returns the ChildProcess — caller manages stdout/stderr/lifecycle.
+     *
+     * In ADB mode: spawns `adb -s <serial> <args...>`
+     * LocalBridge overrides this to spawn commands directly.
+     */
+    spawnStreaming(args, device) {
+        const serial = device || config.defaultDevice;
+        const fullArgs = [];
+        if (serial) {
+            fullArgs.push("-s", serial);
+        }
+        fullArgs.push(...args);
+        this.logger.debug(`spawn: adb ${fullArgs.join(" ")}`);
+        return spawn(this.adbPath, fullArgs, {
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+}
+/** Structured error type for ADB failures. */
+export class AdbError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.name = "AdbError";
+        this.result = result;
+    }
+}
+//# sourceMappingURL=adb-bridge.js.map

package/build/bridge/adb-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb-bridge.js","sourceRoot":"","sources":["../../src/bridge/adb-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAmB,KAAK,EAAgB,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAsBxD,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG;IACzB,kBAAkB;IAClB,gBAAgB;IAChB,4BAA4B;IAC5B,gBAAgB;IAChB,QAAQ;IACR,kBAAkB;IAClB,YAAY;CACb,CAAC;AAEF,SAAS,gBAAgB,CAAC,KAAc;IACtC,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnE,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,OAAO,SAAS;IACZ,OAAO,CAAS;IAChB,MAAM,CAAS;IAEvB,YAAY,MAAc;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,IAAc,EAAE,UAA0B,EAAE;QACrD,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU,CAAC;QACxD,IAAI,SAAkB,CAAC;QAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YACvD,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG,KAAK,CAAC;gBAClB,IAAI,OAAO,GAAG,UAAU,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;oBACpD,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;oBAC3D,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,kCAAkC,OAAO,GAAG,CAAC,IAAI,UAAU,GAAG,CAAC,kBAAkB,KAAK,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAC9I,CAAC;oBACF,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;oBACxB,SAAS;gBACX,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,MAAM,SAAS,CAAC,CAAC,mDAAmD;IACtE,CAAC;IAEO,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,QAAQ,CAAC,IAAc,EAAE,OAAuB;QAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,aAAa,CAAC;QACtD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,cAAc,CAAC;QAEzD,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,MAAM,EAAE,CAAC;YACX,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAEvB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAE/C,OAAO,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAChD,MAAM,WAAW,GAAoB;gBACnC,OAAO;gBACP,SAAS,EAAE,MAAM,CAAC,aAAa,GAAG,CAAC;gBACnC,WAAW,EAAE,IAAI;aAClB,CAAC;YAEF,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;gBACtE,MAAM,cAAc,GAAG,KAAK,EAAE,IAAI,KAAK,mCAAmC;uBACrE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;gBACpD,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,CAAC;gBAE3D,MAAM,QAAQ,GAAG,KAAK,EAAE,IAAI,IAAI,IAAI;oBAClC,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;oBACnD,CAAC,CAAC,CAAC,CAAC;gBAEN,MAAM,MAAM,GAAc;oBACxB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAChC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAChC,QAAQ;oBACR,QAAQ;oBACR,cAAc;oBACd,MAAM,EAAE,MAAM,IAAI,SAAS;iBAC5B,CAAC;gBAEF,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,SAAS,QAAQ,eAAe,QAAQ,qBAAqB,cAAc,aAAa,MAAM,CAAC,MAAM,CAAC,MAAM,QAAQ,CACrH,CAAC;gBAEF,IAAI,QAAQ,EAAE,CAAC;oBACb,MAAM,CAAC,IAAI,QAAQ,CAAC,2BAA2B,OAAO,WAAW,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;oBAChG,OAAO;gBACT,CAAC;gBAED,IAAI,cAAc,EAAE,CAAC;oBACnB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;oBACxE,OAAO,CAAC,MAAM,CAAC,CAAC;oBAChB,OAAO;gBACT,CAAC;gBAED,IAAI,QAAQ,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;oBAC9C,MAAM,CAAC,IAAI,QAAQ,CACjB,4BAA4B,QAAQ,MAAM,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EACjF,MAAM,CACP,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;gBAED,OAAO,CAAC,MAAM,CAAC,CAAC;YAClB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,UAA0B,EAAE;QACvD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAED,6CAA6C;IAC7C,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,UAA0B,EAAE;QAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,UAAU,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,OAAO;QACX,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5D,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,IAAI;QACR,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5D,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,cAAc,CAAC,IAAc,EAAE,MAAe;QAC5C,MAAM,MAAM,GAAG,MAAM,IAAI,MAAM,CAAC,aAAa,CAAC;QAC9C,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,MAAM,EAAE,CAAC;YACX,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAEvB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEtD,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE;YACnC,WAAW,EAAE,IAAI;YACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;CACF;AAED,8CAA8C;AAC9C,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjB,MAAM,CAAY;IAElC,YAAY,OAAe,EAAE,MAAiB;QAC5C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/build/bridge/device-manager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Device Manager — Discovery, caching, state tracking, and device selection.
+ *
+ * Includes a TTL-based device list cache to avoid redundant `adb devices`
+ * calls on every tool invocation. Cache is automatically invalidated on
+ * connection-related errors.
+ */
+import { AdbBridge } from "./adb-bridge.js";
+export interface DeviceInfo {
+    serial: string;
+    state: "device" | "offline" | "unauthorized" | "no permissions" | string;
+    model?: string;
+    product?: string;
+    transportId?: string;
+}
+export declare class DeviceManager {
+    private bridge;
+    private cache;
+    constructor(bridge: AdbBridge);
+    /**
+     * List all connected devices with their properties.
+     * Results are cached for config.deviceCacheTtl milliseconds.
+     */
+    listDevices(): Promise<DeviceInfo[]>;
+    /**
+     * Force-refresh the device cache on next call.
+     * Call this after connect/disconnect/pair operations.
+     */
+    invalidateCache(): void;
+    /**
+     * Get a single device, auto-selecting if only one is connected.
+     * Throws if zero or multiple devices and no serial specified.
+     */
+    resolveDevice(serial?: string): Promise<DeviceInfo>;
+    /**
+     * Get detailed device properties via getprop.
+     */
+    getDeviceProps(serial?: string): Promise<Record<string, string>>;
+    private parseDeviceLine;
+}
+//# sourceMappingURL=device-manager.d.ts.map

package/build/bridge/device-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-manager.d.ts","sourceRoot":"","sources":["../../src/bridge/device-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,gBAAgB,GAAG,MAAM,CAAC;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAA4B;gBAE7B,MAAM,EAAE,SAAS;IAI7B;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAkB1C;;;OAGG;IACH,eAAe,IAAI,IAAI;IAIvB;;;OAGG;IACG,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA6CzD;;OAEG;IACG,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IActE,OAAO,CAAC,eAAe;CAgBxB"}

package/build/bridge/device-manager.js

@@ -0,0 +1,109 @@
+/**
+ * Device Manager — Discovery, caching, state tracking, and device selection.
+ *
+ * Includes a TTL-based device list cache to avoid redundant `adb devices`
+ * calls on every tool invocation. Cache is automatically invalidated on
+ * connection-related errors.
+ */
+import { config } from "../config/config.js";
+export class DeviceManager {
+    bridge;
+    cache = null;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    /**
+     * List all connected devices with their properties.
+     * Results are cached for config.deviceCacheTtl milliseconds.
+     */
+    async listDevices() {
+        const now = Date.now();
+        if (this.cache && (now - this.cache.timestamp) < config.deviceCacheTtl) {
+            return this.cache.devices;
+        }
+        const result = await this.bridge.exec(["devices", "-l"]);
+        const lines = result.stdout.split("\n").slice(1); // Skip header
+        const devices = lines
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => this.parseDeviceLine(line));
+        this.cache = { devices, timestamp: now };
+        return devices;
+    }
+    /**
+     * Force-refresh the device cache on next call.
+     * Call this after connect/disconnect/pair operations.
+     */
+    invalidateCache() {
+        this.cache = null;
+    }
+    /**
+     * Get a single device, auto-selecting if only one is connected.
+     * Throws if zero or multiple devices and no serial specified.
+     */
+    async resolveDevice(serial) {
+        const devices = await this.listDevices();
+        const online = devices.filter((d) => d.state === "device");
+        if (serial) {
+            const found = devices.find((d) => d.serial === serial);
+            if (!found) {
+                // Invalidate cache — device might have just connected
+                this.invalidateCache();
+                throw new Error(`Device ${serial} not found. Connected: ${devices.map((d) => d.serial).join(", ") || "none"}`);
+            }
+            if (found.state !== "device") {
+                throw new Error(`Device ${serial} is ${found.state}. ` +
+                    (found.state === "unauthorized"
+                        ? "Check the device screen for the RSA key approval dialog."
+                        : "Verify the device is online and USB debugging is enabled."));
+            }
+            return found;
+        }
+        if (online.length === 0) {
+            this.invalidateCache(); // Force refresh next time
+            const unauthorized = devices.filter((d) => d.state === "unauthorized");
+            if (unauthorized.length > 0) {
+                throw new Error(`No authorized devices. ${unauthorized.length} device(s) pending USB debugging authorization. ` +
+                    `Check the device screen for the RSA key approval dialog.`);
+            }
+            throw new Error("No devices connected. Verify USB connection and USB debugging is enabled.");
+        }
+        if (online.length > 1) {
+            throw new Error(`Multiple devices connected. Specify a device serial: ${online.map((d) => d.serial).join(", ")}`);
+        }
+        return online[0];
+    }
+    /**
+     * Get detailed device properties via getprop.
+     */
+    async getDeviceProps(serial) {
+        const device = await this.resolveDevice(serial);
+        const result = await this.bridge.shell("getprop", { device: device.serial });
+        const props = {};
+        for (const line of result.stdout.split("\n")) {
+            const match = line.trim().match(/^\[(.+?)\]: \[(.*)?\]$/);
+            if (match) {
+                props[match[1]] = match[2] ?? "";
+            }
+        }
+        return props;
+    }
+    parseDeviceLine(line) {
+        const parts = line.split(/\s+/);
+        const serial = parts[0];
+        const state = parts[1];
+        const info = { serial, state };
+        // Parse key:value pairs like model:Pixel_6a product:bluejay
+        for (let i = 2; i < parts.length; i++) {
+            const [key, value] = parts[i].split(":");
+            if (key === "model")
+                info.model = value;
+            else if (key === "product")
+                info.product = value;
+            else if (key === "transport_id")
+                info.transportId = value;
+        }
+        return info;
+    }
+}
+//# sourceMappingURL=device-manager.js.map

package/build/bridge/device-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-manager.js","sourceRoot":"","sources":["../../src/bridge/device-manager.ts"],"names":[],"mappings":"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"}

package/build/bridge/local-bridge.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Local Bridge — On-device execution without ADB.
+ *
+ * Drop-in replacement for AdbBridge when DeepADB runs directly on the Android
+ * device (e.g., inside Termux). All commands execute locally via sh/su instead
+ * of routing through adb over USB.
+ *
+ * Extends AdbBridge so it is type-compatible with the entire tool suite —
+ * no tool module changes required. The override of exec() is the single
+ * interception point; shell() and rootShell() flow through it automatically.
+ *
+ * Environment detection: see config.ts isOnDevice().
+ */
+import { ChildProcess } from "child_process";
+import { AdbBridge, AdbResult, AdbExecOptions } from "./adb-bridge.js";
+import { Logger } from "../middleware/logger.js";
+export declare class LocalBridge extends AdbBridge {
+    private localLogger;
+    private deviceInfoCache;
+    /**
+     * Cached root availability. null = not yet checked, true/false = checked.
+     * Probed lazily on first command that needs elevation.
+     */
+    private rootAvailable;
+    /**
+     * Android system commands that require shell-user (uid=2000) or root privileges.
+     * In ADB mode, all shell commands run as uid=2000 automatically.
+     * In on-device mode (Termux app user), these need su elevation.
+     *
+     * SECURITY: This is a FROZEN allowlist — hardcoded and immutable.
+     * Not configurable via environment variables or runtime API.
+     * Only commands explicitly listed here get routed through su.
+     */
+    private static readonly ELEVATED_COMMANDS;
+    constructor(logger: Logger);
+    /** Quote a string for safe use as a shell argument (wraps in single quotes with escaping). */
+    private shellQuote;
+    /**
+     * Check if root (su) is available. Result is cached after first probe.
+     * Uses a fast, side-effect-free check: `su -c id`.
+     */
+    private checkRootAvailable;
+    /**
+     * Wrap a command in `su -c '...'` for privilege elevation.
+     * Uses shellEscape() to safely handle single quotes in the inner command.
+     * This is the same escaping path used by AdbBridge.rootShell().
+     */
+    private elevate;
+    /**
+     * Android filesystem paths that require elevated access in on-device mode.
+     * Commands referencing these paths need su to bypass scoped storage restrictions.
+     * In ADB mode (uid=2000), these paths are accessible by default.
+     */
+    private static readonly RESTRICTED_PATH_PATTERNS;
+    /**
+     * Check if a shell command needs privilege elevation.
+     * Two criteria (either triggers elevation):
+     * 1. Command name is in the frozen ELEVATED_COMMANDS allowlist (system tools)
+     * 2. Command references restricted filesystem paths (scoped storage bypass)
+     *
+     * Security note: all commands reaching this point have already been validated
+     * by validateShellArg/shellEscape at the tool layer. The su -c '...' wrapper
+     * uses shellEscape() to prevent injection within the single-quote context.
+     */
+    private commandNeedsElevation;
+    /**
+     * Execute an "ADB command" locally by translating the subcommand.
+     * This is the single interception point — shell(), rootShell(), and all
+     * tool calls to exec() flow through here.
+     */
+    exec(args: string[], options?: AdbExecOptions): Promise<AdbResult>;
+    /** Execute a command directly on the local device via sh. */
+    private execLocal;
+    /**
+     * Synthesize an `adb devices -l` response for DeviceManager.
+     * Reads device properties once and caches them.
+     */
+    private syntheticDeviceList;
+    /** Create a successful AdbResult from a string. */
+    private makeResult;
+    /** Always reachable — we are the device. */
+    ping(): Promise<boolean>;
+    /** Return local version info. */
+    version(): Promise<string>;
+    /**
+     * Spawn a long-running streaming command locally.
+     * In ADB mode the args are ["logcat", ...flags] prefixed with "adb -s serial".
+     * Here we strip the ADB layer and spawn the command directly.
+     */
+    spawnStreaming(args: string[], _device?: string): ChildProcess;
+}
+//# sourceMappingURL=local-bridge.d.ts.map

package/build/bridge/local-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-bridge.d.ts","sourceRoot":"","sources":["../../src/bridge/local-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAoC,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAY,MAAM,iBAAiB,CAAC;AAEjF,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGjD,qBAAa,WAAY,SAAQ,SAAS;IACxC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAuB;IAE9C;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAwB;IAE7C;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAiBrC;gBAEQ,MAAM,EAAE,MAAM;IAK1B,8FAA8F;IAC9F,OAAO,CAAC,UAAU;IAIlB;;;OAGG;YACW,kBAAkB;IAkBhC;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAIf;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAuC;IAEvF;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;;;OAIG;IACY,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IA0HrF,6DAA6D;IAC7D,OAAO,CAAC,SAAS;IAqDjB;;;OAGG;YACW,mBAAmB;IAmBjC,mDAAmD;IACnD,OAAO,CAAC,UAAU;IAWlB,4CAA4C;IAC7B,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAIvC,iCAAiC;IAClB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IASzC;;;;OAIG;IACM,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY;CA0BxE"}