@beeos-ai/device-mcp-server 0.3.0 → 0.4.2

package/dist/backends/android-adb.d.ts

@@ -49,10 +49,31 @@
  * system). The Android backend no longer compresses by default — the
  * agent layer decides whether to resize.
  */
-import { DeviceError, type DeviceInfo } from "@beeos-ai/device-common";
-import { BaseSandboxBackend, type ExecuteCommandOutput, type ListDirectoryEntry, type ScreenSize, type ScreenshotOutput, type UiDumpOutput } from "./base.js";
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import { DeviceError, type AppInfo, type CrashSummary, type DeviceInfo, type Orientation, type SaveScreenshotResult, type ScreenRecordHandle, type ScreenRecordResult, type UiElement } from "@beeos-ai/device-common";
+import { BaseSandboxBackend, type ExecuteCommandOutput, type LaunchAppOptions, type StartScreenRecordOptions, type ListDirectoryEntry, type ScreenSize, type ScreenshotOptions, type ScreenshotOutput, type UiDumpOutput } from "./base.js";
 import { type AdbRunOptions, type AdbRunResult, type AdbRunner } from "./android-adb-runner.js";
 export type { AdbRunOptions, AdbRunResult, AdbRunner };
+/**
+ * Friendly button name → Android `KEYCODE_*`. Names are case-insensitive.
+ *
+ * The vocabulary mirrors mobile-mcp `mobile_press_button` so prompts that
+ * already work against mobile-mcp port over without rewording. The
+ * registry exposes `Object.keys(PRESS_BUTTON_KEYMAP)` so the MCP tool's
+ * `enum` is auto-derived rather than maintained in two places.
+ */
+export declare const PRESS_BUTTON_KEYMAP: Readonly<Record<string, string>>;
+/**
+ * Pluggable spawner used by `screen_record_*` to fork a long-lived
+ * `adb shell screenrecord` child. Mirrors `node:child_process.spawn`'s
+ * shape — exposed so tests can fake the recording lifecycle without
+ * actually invoking adb.
+ *
+ * Mutable `string[]` (not `readonly`) on purpose — `node:child_process.spawn`
+ * itself takes a mutable array, and using `readonly` here would force
+ * every implementation through a type assertion.
+ */
+export type AdbProcessSpawner = (file: string, args: string[], opts?: SpawnOptions) => ChildProcess;
 export interface AndroidAdbBackendOptions {
     /** ADB serial, e.g. `emulator-5554`. Optional when a single device is connected. */
     serial?: string;
@@ -72,6 +93,22 @@ export interface AndroidAdbBackendOptions {
     fileTimeoutMs?: number;
     /** Sleep helper, injectable for deterministic tests. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Long-process spawner for `screen_record_*`. Defaults to
+     * `node:child_process.spawn`.
+     */
+    processSpawner?: AdbProcessSpawner;
+    /**
+     * Hard host-side timeout for waiting on a recording to flush after
+     * SIGINT before escalating to SIGKILL. Default 5_000 ms.
+     */
+    recordKillGraceMs?: number;
+    /**
+     * Device-side hard cap forwarded as `screenrecord --time-limit`.
+     * Default 300 (5 minutes — also adb's own legacy cap so any value
+     * above that is silently ignored).
+     */
+    recordTimeLimitS?: number;
 }
 export declare class AndroidAdbBackend extends BaseSandboxBackend {
     readonly os: "android";
@@ -85,11 +122,29 @@ export declare class AndroidAdbBackend extends BaseSandboxBackend {
     private readonly screenshotTimeoutMs;
     private readonly installTimeoutMs;
     private readonly fileTimeoutMs;
+    private readonly processSpawner;
+    private readonly recordKillGraceMs;
+    private readonly recordTimeLimitS;
+    private readonly recordings;
+    /** Cached `android.software.leanback` system feature — drives `info().isTv`. */
+    private isLeanback;
+    /** True after `probeLeanback()` has resolved (success OR failure). */
+    private leanbackProbed;
     constructor(opts?: AndroidAdbBackendOptions);
     connect(): Promise<void>;
+    /**
+     * Detect Android TV / leanback so `info().isTv` can hint at LLM
+     * prompts that should default to DPAD navigation. Cached for the
+     * lifetime of the backend — running `pm has-feature` once per device
+     * is enough; the answer doesn't change at runtime. Lazy on purpose —
+     * `connect()` with `skipConnectValidation: true` (the registry path)
+     * MUST NOT issue any adb commands, so we defer this probe to the
+     * first `info()` call.
+     */
+    private ensureLeanbackProbed;
     disconnect(): Promise<void>;
     info(): Promise<DeviceInfo>;
-    screenshot(): Promise<ScreenshotOutput>;
+    screenshot(opts?: ScreenshotOptions): Promise<ScreenshotOutput>;
     screenSize(): Promise<ScreenSize>;
     uiDump(): Promise<UiDumpOutput>;
     tap(x: number, y: number): Promise<void>;
@@ -98,13 +153,24 @@ export declare class AndroidAdbBackend extends BaseSandboxBackend {
     longPress(x: number, y: number, durationMs?: number): Promise<void>;
     swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
     drag(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
-    scroll(x: number, y: number, direction: "up" | "down" | "left" | "right", _amount?: number): Promise<void>;
+    scroll(x: number, y: number, direction: "up" | "down" | "left" | "right", amount?: number): Promise<void>;
     typeText(text: string): Promise<void>;
     pressKey(key: string): Promise<void>;
     back(): Promise<void>;
     home(): Promise<void>;
     navigate(direction: "back" | "forward" | "up"): Promise<void>;
-    launchApp(pkgOrName: string, activity?: string): Promise<void>;
+    launchApp(pkgOrName: string, opts?: LaunchAppOptions | string): Promise<void>;
+    openUrl(url: string): Promise<void>;
+    listApps(opts?: {
+        includeSystem?: boolean;
+        launchableOnly?: boolean;
+    }): Promise<AppInfo[]>;
+    terminateApp(pkg: string): Promise<void>;
+    listElements(opts?: {
+        query?: string;
+    }): Promise<UiElement[]>;
+    getOrientation(): Promise<Orientation>;
+    setOrientation(o: Orientation): Promise<void>;
     executeCommand(body: string, opts?: {
         timeoutS?: number;
         cwd?: string;
@@ -113,7 +179,55 @@ export declare class AndroidAdbBackend extends BaseSandboxBackend {
     fileWrite(path: string, content: Buffer | string): Promise<void>;
     listDirectory(path: string): Promise<ListDirectoryEntry[]>;
     install(path: string): Promise<void>;
-    private getCurrentApp;
+    uninstallApp(pkgOrName: string): Promise<void>;
+    /**
+     * Parse `dumpsys dropbox --print` and return one entry per recorded
+     * crash / ANR / WTF. The list is best-effort — the dumpsys output
+     * format has shifted slightly across Android releases, so we tolerate
+     * unknown lines instead of rejecting them.
+     */
+    listCrashes(): Promise<CrashSummary[]>;
+    /**
+     * Re-run `dumpsys dropbox --print` and return the body of the entry
+     * whose `id` matches. Stateless so the result stays correct even if
+     * `listCrashes` was called from a different MCP session.
+     */
+    getCrash(id: string): Promise<string>;
+    /**
+     * Spawn `adb shell screenrecord` for a single recording. The device
+     * enforces a hard `--time-limit` (default 5 min, capped at 300s by
+     * Android itself); the host sends SIGINT on `stopScreenRecord` and
+     * falls back to SIGKILL after `recordKillGraceMs` if the child
+     * hasn't exited.
+     *
+     * The same-pid `screenrecord` invocation also lets us pipe the output
+     * to a `/sdcard/<id>.mp4` so `adb pull` after stop can fetch the
+     * exact file without guessing names.
+     *
+     * `opts.timeLimitS` (mobile-mcp parity, r3): caller-supplied cap,
+     * clamped into `[1, 300]` and passed to `screenrecord --time-limit`.
+     * `opts.localPath`: caller-supplied host-side destination registered
+     * at start time. Already passed through `assertSafeOutputPathWithExt`
+     * — backend treats as trusted.
+     */
+    startScreenRecord(opts?: StartScreenRecordOptions): Promise<ScreenRecordHandle>;
+    stopScreenRecord(id: string, opts?: {
+        path?: string;
+    }): Promise<ScreenRecordResult>;
+    /**
+     * Capture a screenshot via `adb pull` of `/sdcard/screenshot.png`.
+     * Bypasses the JSON-RPC body cap by writing the bytes straight to a
+     * host filesystem path the caller chose. Useful for 4K Android
+     * captures where base64-over-HTTP would otherwise blow past 16 MB.
+     */
+    saveScreenshot(localPath: string, opts?: ScreenshotOptions): Promise<SaveScreenshotResult>;
+    /**
+     * Count the number of displays the device exposes. Reads
+     * `dumpsys SurfaceFlinger --display-id` (Android 10+) and falls back
+     * to "1" on older builds where the flag isn't recognised.
+     */
+    getDisplayCount(): Promise<number>;
+    getCurrentApp(): Promise<string>;
     private getCurrentIme;
     private setIme;
     private clearText;
@@ -151,3 +265,30 @@ export declare function listAdbDevices(runner?: AdbRunner, timeoutMs?: number):
  * a `DeviceError` in another `DeviceError`.
  */
 export declare function wrapAdbFailure(verb: string, args: string[], cause: unknown, timeoutMs?: number): DeviceError;
+export declare function assertSafeUrl(url: string): void;
+/**
+ * Parse the textual output of `dumpsys dropbox --print` into one
+ * `CrashSummary` per crash / ANR / WTF entry.
+ *
+ * Output shape (Android 7+):
+ *
+ *   2024-08-15 12:34:56 system_app_crash (text, 1234 bytes):
+ *   Process: com.foo.bar
+ *   ...stack trace lines...
+ *   2024-08-15 12:35:00 data_app_anr (text, 5678 bytes):
+ *   ...
+ *
+ * We extract the leading `<timestamp> <tag> (text, N bytes):` row and
+ * include the first non-blank body line as a `headline` for at-a-glance
+ * triage. The id encodes both the tag and the timestamp so `getCrash`
+ * can re-locate the same row on the next `dumpsys` invocation without
+ * holding state.
+ */
+export declare function parseDropboxEntries(out: string): CrashSummary[];
+/**
+ * Pull the body of a single dumpsys-dropbox entry out of the `--print`
+ * blob, indexed by `<tag>:<timestamp>` (the same id `parseDropboxEntries`
+ * returns). The body is everything between the matching header and the
+ * next entry header.
+ */
+export declare function extractDropboxBody(out: string, id: string): string | undefined;