@beeos-ai/device-mcp-server 0.2.3

package/dist/backends/index.js

@@ -0,0 +1,105 @@
+/**
+ * Backend registry — string → backend factory.
+ *
+ * Used by the CLI (`device-mcp-server --backend android ...`) and
+ * `server/app.ts` to resolve a `SandboxBackend` from configuration.
+ *
+ * **Naming convention** (after the self-hosted plan §3.4 "去掉 backend
+ * 私有词"):
+ *
+ *   Canonical short name (CLI surface)  Aliases (back-compat / verbose)
+ *   ---------------------------------   --------------------------------------
+ *   adb        → AndroidAdbBackend      "android"
+ *   macos      → MacOsBackend           "mac", "desktop-macos"
+ *   linux      → LinuxBackend           "desktop-linux" (used to be the mock —
+ *                                       now resolves to the real native
+ *                                       LinuxBackend; the in-memory mock is
+ *                                       still reachable via "mock-desktop"
+ *                                       and is used by integration tests)
+ *   windows    → WindowsBackend         "win", "desktop-windows"
+ *   ios        → IosBackend (zero caps stub, reserved for WDA / libimobiledevice)
+ *
+ *   desktop                             "smart-resolve": MacOsBackend on darwin,
+ *                                       LinuxBackend on linux, WindowsBackend
+ *                                       on win32, mock elsewhere.
+ *
+ *   mock-desktop                        DesktopBackend (in-memory, for tests
+ *                                       — never picks itself in `desktop`).
+ */
+import { DeviceError } from "@beeos-ai/device-common";
+import { AndroidAdbBackend } from "./android-adb.js";
+import { DesktopBackend } from "./desktop.js";
+import { LinuxBackend } from "./linux.js";
+import { MacOsBackend } from "./mac.js";
+import { WindowsBackend } from "./stubs/windows.js";
+import { IosBackend } from "./stubs/ios.js";
+/**
+ * Resolve any of the canonical / alias / smart-resolve names to a real
+ * backend instance. Aliases collapse early so the rest of the codebase
+ * only ever sees the canonical name when building options.
+ */
+export function createBackend(name, opts = {}) {
+    switch (name) {
+        /* — Android / ADB — */
+        case "adb":
+        case "android":
+            return new AndroidAdbBackend(opts.android);
+        /* — macOS — */
+        case "macos":
+        case "mac":
+        case "desktop-macos":
+            return new MacOsBackend(opts.macos);
+        /* — Linux (real native, gnome-screenshot/scrot/import + /bin/sh) — */
+        case "linux":
+        case "desktop-linux":
+            return new LinuxBackend(opts.linux);
+        /* — Windows (real native, PowerShell + cmd.exe) — */
+        case "windows":
+        case "win":
+        case "desktop-windows":
+            return new WindowsBackend(opts.windows);
+        /* — Smart-resolve — */
+        case "desktop":
+            if (process.platform === "darwin")
+                return new MacOsBackend(opts.macos);
+            if (process.platform === "linux")
+                return new LinuxBackend(opts.linux);
+            if (process.platform === "win32")
+                return new WindowsBackend(opts.windows);
+            // Anything exotic falls back to the mock so the agent main loop
+            // still boots in unusual sandboxes / CI runners.
+            return new DesktopBackend({ ...opts.desktop, os: "desktop-linux" });
+        /* — Explicit in-memory mock for tests — */
+        case "mock-desktop":
+            return new DesktopBackend({ ...opts.desktop, os: "desktop-linux" });
+        /* — Reserved stub — */
+        case "ios":
+            return new IosBackend();
+        default:
+            throw new DeviceError(`unknown backend '${name}'`, {
+                subtype: "unsupported",
+                retriable: false,
+            });
+    }
+}
+/**
+ * `--backend` autocomplete / `--help` source. Lists canonical names
+ * first, then aliases, so help output reads top-down most-useful.
+ */
+export const SUPPORTED_BACKENDS = [
+    "adb",
+    "macos",
+    "linux",
+    "windows",
+    "desktop",
+    "android",
+    "mac",
+    "win",
+    "desktop-linux",
+    "desktop-windows",
+    "desktop-macos",
+    "mock-desktop",
+    "ios",
+];
+export { AndroidAdbBackend, DesktopBackend, LinuxBackend, MacOsBackend, WindowsBackend, IosBackend, };
+//# sourceMappingURL=index.js.map

package/dist/backends/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAiC,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAE,cAAc,EAA8B,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAA4B,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,YAAY,EAA4B,MAAM,UAAU,CAAC;AAClE,OAAO,EAAE,cAAc,EAA8B,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAsC5C;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAiB,EACjB,OAA6B,EAAE;IAE/B,QAAQ,IAAI,EAAE,CAAC;QACb,uBAAuB;QACvB,KAAK,KAAK,CAAC;QACX,KAAK,SAAS;YACZ,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE7C,eAAe;QACf,KAAK,OAAO,CAAC;QACb,KAAK,KAAK,CAAC;QACX,KAAK,eAAe;YAClB,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEtC,sEAAsE;QACtE,KAAK,OAAO,CAAC;QACb,KAAK,eAAe;YAClB,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEtC,qDAAqD;QACrD,KAAK,SAAS,CAAC;QACf,KAAK,KAAK,CAAC;QACX,KAAK,iBAAiB;YACpB,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE1C,uBAAuB;QACvB,KAAK,SAAS;YACZ,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;gBAAE,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;gBAAE,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;gBAAE,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1E,gEAAgE;YAChE,iDAAiD;YACjD,OAAO,IAAI,cAAc,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;QAEtE,2CAA2C;QAC3C,KAAK,cAAc;YACjB,OAAO,IAAI,cAAc,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;QAEtE,uBAAuB;QACvB,KAAK,KAAK;YACR,OAAO,IAAI,UAAU,EAAE,CAAC;QAE1B;YACE,MAAM,IAAI,WAAW,CAAC,oBAAoB,IAAc,GAAG,EAAE;gBAC3D,OAAO,EAAE,aAAa;gBACtB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;IACP,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAkB;IAC/C,KAAK;IACL,OAAO;IACP,OAAO;IACP,SAAS;IACT,SAAS;IACT,SAAS;IACT,KAAK;IACL,KAAK;IACL,eAAe;IACf,iBAAiB;IACjB,eAAe;IACf,cAAc;IACd,KAAK;CACN,CAAC;AAYF,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,UAAU,GACX,CAAC"}

package/dist/backends/linux.d.ts

@@ -0,0 +1,69 @@
+/**
+ * LinuxBackend — minimal `SandboxBackend` driving a real Linux host.
+ *
+ * Scope (v0.2.0 stub): only `screenshot` / `screen_size` / `device_info` /
+ * `execute_command` are implemented natively. Pointer / keyboard /
+ * accessibility tools are deliberately NOT in `LINUX_STUB_TOOLS` so the MCP
+ * tool registry filters them out at startup — agents see exactly the verbs
+ * the backend can actually fulfill, no runtime "unsupported" surprises.
+ *
+ * Implementations (all synchronous shell-outs to keep deps zero):
+ *
+ *   - **Screenshot**: prefer `gnome-screenshot --file -` if available
+ *     (GNOME / Wayland-native), then `scrot -o -` (X11), then ImageMagick
+ *     `import -window root png:-`. The first one that exists on `PATH`
+ *     wins. All three pipe PNG bytes to stdout, so the implementation
+ *     stays uniform — we just buffer the child's stdout.
+ *   - **Screen size**: parsed from `xdpyinfo | grep dimensions:` on X11,
+ *     falls back to `wlr-randr` on Wayland-Sway, finally falls back to
+ *     `1920x1080` if neither is available so the agent main loop still
+ *     boots on headless CI containers (the screenshot call will then
+ *     surface a `DeviceError("environment")` which is the right place to
+ *     report the missing tooling).
+ *   - **executeCommand**: `/bin/sh -c body` — same shape as ADB / macOS.
+ *
+ * **Testability**: like `MacOsBackend`, the constructor accepts an
+ * injected `runner` (spawn-shape) so the suite can run without ever
+ * touching a real X server / Wayland compositor. The default runner
+ * binds to `node:child_process.spawn`.
+ */
+import { type DeviceInfo } from "@beeos-ai/device-common";
+import { BaseSandboxBackend, type ExecuteCommandOutput, type ScreenSize, type ScreenshotOutput } from "./base.js";
+export interface RunResult {
+    code: number;
+    stdout: Buffer;
+    stderr: string;
+}
+export type Runner = (bin: string, args: readonly string[], opts?: {
+    stdin?: string;
+    timeoutMs?: number;
+}) => Promise<RunResult>;
+export interface LinuxBackendOptions {
+    /** Override the spawn runner (tests). */
+    runner?: Runner;
+    /**
+     * Override which-binary lookup. Defaults to a runner-based `command -v`
+     * probe; tests inject a `Set<string>` of "available" binaries.
+     */
+    whichBinary?: (bin: string) => Promise<boolean>;
+    /** Default-shell command timeout in ms. Defaults to 30s. */
+    shellTimeoutMs?: number;
+}
+export declare class LinuxBackend extends BaseSandboxBackend {
+    readonly os: "desktop-linux";
+    readonly tools: ReadonlySet<string>;
+    private readonly runner;
+    private readonly whichBinary;
+    private readonly shellTimeoutMs;
+    private screenshotBackend;
+    constructor(opts?: LinuxBackendOptions);
+    info(): Promise<DeviceInfo>;
+    screenshot(): Promise<ScreenshotOutput>;
+    screenSize(): Promise<ScreenSize>;
+    executeCommand(command: string): Promise<ExecuteCommandOutput>;
+    /**
+     * Pick whichever screenshot tool is on `PATH`, in priority order.
+     * Cached after the first probe.
+     */
+    private pickScreenshotTool;
+}

package/dist/backends/linux.js

@@ -0,0 +1,230 @@
+/**
+ * LinuxBackend — minimal `SandboxBackend` driving a real Linux host.
+ *
+ * Scope (v0.2.0 stub): only `screenshot` / `screen_size` / `device_info` /
+ * `execute_command` are implemented natively. Pointer / keyboard /
+ * accessibility tools are deliberately NOT in `LINUX_STUB_TOOLS` so the MCP
+ * tool registry filters them out at startup — agents see exactly the verbs
+ * the backend can actually fulfill, no runtime "unsupported" surprises.
+ *
+ * Implementations (all synchronous shell-outs to keep deps zero):
+ *
+ *   - **Screenshot**: prefer `gnome-screenshot --file -` if available
+ *     (GNOME / Wayland-native), then `scrot -o -` (X11), then ImageMagick
+ *     `import -window root png:-`. The first one that exists on `PATH`
+ *     wins. All three pipe PNG bytes to stdout, so the implementation
+ *     stays uniform — we just buffer the child's stdout.
+ *   - **Screen size**: parsed from `xdpyinfo | grep dimensions:` on X11,
+ *     falls back to `wlr-randr` on Wayland-Sway, finally falls back to
+ *     `1920x1080` if neither is available so the agent main loop still
+ *     boots on headless CI containers (the screenshot call will then
+ *     surface a `DeviceError("environment")` which is the right place to
+ *     report the missing tooling).
+ *   - **executeCommand**: `/bin/sh -c body` — same shape as ADB / macOS.
+ *
+ * **Testability**: like `MacOsBackend`, the constructor accepts an
+ * injected `runner` (spawn-shape) so the suite can run without ever
+ * touching a real X server / Wayland compositor. The default runner
+ * binds to `node:child_process.spawn`.
+ */
+import { spawn } from "node:child_process";
+import { DeviceError, } from "@beeos-ai/device-common";
+import { BaseSandboxBackend, } from "./base.js";
+import { parsePngDimensions } from "../util/image-dim.js";
+/**
+ * Linux backend tool catalogue (v0.2.0 stub).
+ *
+ * Only the four tools the stub can actually fulfill — observation +
+ * shell — are advertised. Everything else (gestures / keyboard / fs /
+ * install / ui_dump) is omitted so the tool registry never offers a
+ * verb the stub will reject.
+ *
+ * Future expansion path:
+ *   - click / drag / scroll → `xdotool` (X11) or `ydotool` (Wayland)
+ *   - type / key / hotkey   → same
+ *   - launch_app            → `wmctrl` / `gtk-launch` / .desktop lookup
+ *   - install_package       → `apt-get` / `dnf` / `pacman` dispatch
+ *   - file_read / write / list_directory → Node `fs/promises` direct
+ *   - ui_dump               → AT-SPI bridge (atspi-2 + dbus)
+ */
+const LINUX_STUB_TOOLS = new Set([
+    "screenshot",
+    "screen_size",
+    "device_info",
+    "execute_command",
+]);
+const defaultRunner = (bin, args, opts = {}) => new Promise((resolve, reject) => {
+    const child = spawn(bin, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const out = [];
+    let err = "";
+    let timer;
+    if (opts.timeoutMs && opts.timeoutMs > 0) {
+        timer = setTimeout(() => child.kill("SIGKILL"), opts.timeoutMs);
+    }
+    child.stdout.on("data", (b) => out.push(b));
+    child.stderr.on("data", (b) => (err += b.toString("utf8")));
+    child.on("error", (e) => {
+        if (timer)
+            clearTimeout(timer);
+        reject(e);
+    });
+    child.on("close", (code) => {
+        if (timer)
+            clearTimeout(timer);
+        resolve({ code: code ?? 0, stdout: Buffer.concat(out), stderr: err });
+    });
+    if (opts.stdin) {
+        child.stdin.end(opts.stdin);
+    }
+    else {
+        child.stdin.end();
+    }
+});
+/* ----------------------------------------------------------------------- */
+/* LinuxBackend                                                             */
+/* ----------------------------------------------------------------------- */
+export class LinuxBackend extends BaseSandboxBackend {
+    os = "desktop-linux";
+    tools = LINUX_STUB_TOOLS;
+    runner;
+    whichBinary;
+    shellTimeoutMs;
+    // Cached at first use to avoid re-probing every screenshot.
+    screenshotBackend = null;
+    constructor(opts = {}) {
+        super();
+        this.runner = opts.runner ?? defaultRunner;
+        this.shellTimeoutMs = opts.shellTimeoutMs ?? 30_000;
+        this.whichBinary =
+            opts.whichBinary ??
+                (async (bin) => {
+                    const r = await this.runner("/bin/sh", ["-c", `command -v ${bin}`]);
+                    return r.code === 0 && r.stdout.length > 0;
+                });
+    }
+    async info() {
+        // `DeviceCapability` is the agent-facing verb vocabulary (see
+        // common/device-info.ts). `screenshot` + `shell` are the two verbs
+        // the v0.2.0 stub actually fulfills. Distinct from `LINUX_STUB_TOOLS`
+        // above — that one drives the tool registry.
+        const caps = ["screenshot", "shell"];
+        const size = await this.screenSize().catch(() => ({ w: 1920, h: 1080 }));
+        return {
+            type: this.os,
+            name: "Linux desktop (stub)",
+            os: "Linux",
+            width: size.w,
+            height: size.h,
+            capabilities: caps,
+            metadata: {
+                stub: "true",
+                screenshotBackend: this.screenshotBackend ?? "auto",
+            },
+        };
+    }
+    async screenshot() {
+        const tool = await this.pickScreenshotTool();
+        let result;
+        switch (tool) {
+            case "gnome-screenshot":
+                result = await this.runner("gnome-screenshot", ["--file=-"]);
+                break;
+            case "scrot":
+                result = await this.runner("scrot", ["-o", "-"]);
+                break;
+            case "import":
+                result = await this.runner("import", ["-window", "root", "png:-"]);
+                break;
+        }
+        if (result.code !== 0 || result.stdout.length === 0) {
+            throw new DeviceError(`linux screenshot via ${tool} failed: ${result.stderr.trim()}`, {
+                subtype: "environment",
+                retriable: true,
+            });
+        }
+        const png = result.stdout;
+        let width = 1920;
+        let height = 1080;
+        try {
+            const dims = parsePngDimensions(png);
+            width = dims[0];
+            height = dims[1];
+        }
+        catch {
+            /* fall back to size guess */
+        }
+        return { data: png, width, height, format: "png" };
+    }
+    async screenSize() {
+        // X11 first (xdpyinfo) — present on every desktop distro, doesn't
+        // need root, and prints `dimensions: WIDTHxHEIGHT pixels`.
+        const xdpy = await this.runner("/bin/sh", [
+            "-c",
+            "xdpyinfo 2>/dev/null | awk '/dimensions:/ {print $2; exit}'",
+        ]);
+        const xdpyOut = xdpy.stdout.toString("utf8").trim();
+        const xdpyMatch = xdpyOut.match(/^(\d+)x(\d+)$/);
+        if (xdpy.code === 0 && xdpyMatch) {
+            return { w: Number(xdpyMatch[1]), h: Number(xdpyMatch[2]) };
+        }
+        // Wayland (Sway / wlroots) — `wlr-randr` lists outputs; the first
+        // line containing "current" carries `WIDTHxHEIGHT@HZ`.
+        const wlr = await this.runner("/bin/sh", [
+            "-c",
+            "wlr-randr 2>/dev/null | awk '/current/ {gsub(/@.*/, \"\", $1); print $1; exit}'",
+        ]);
+        const wlrOut = wlr.stdout.toString("utf8").trim();
+        const wlrMatch = wlrOut.match(/^(\d+)x(\d+)$/);
+        if (wlr.code === 0 && wlrMatch) {
+            return { w: Number(wlrMatch[1]), h: Number(wlrMatch[2]) };
+        }
+        // Last-resort fallback. The screenshot path will surface a real
+        // error if we're actually running headless.
+        return { w: 1920, h: 1080 };
+    }
+    async executeCommand(command) {
+        const r = await this.runner("/bin/sh", ["-c", command], {
+            timeoutMs: this.shellTimeoutMs,
+        });
+        return {
+            stdout: r.stdout.toString("utf8"),
+            stderr: r.stderr,
+            exitCode: r.code,
+        };
+    }
+    /* All non-capability verbs (pointer / keyboard / navigation / app /
+     * filesystem / install / accessibility) inherit the
+     * `unsupported(verb)` rejection from `BaseSandboxBackend`. They are
+     * NEVER reached at runtime because the tool registry filters them
+     * out at `/mcp/tools/list` and `/mcp/tools/call` based on the
+     * `capabilities` set above — but defining the inherited stubs as
+     * the safety net keeps `instanceof SandboxBackend` clean for code
+     * paths that bypass the registry (e.g. legacy `/act` callers). */
+    /* --------------------------------------------------------------------- */
+    /* Helpers                                                                */
+    /* --------------------------------------------------------------------- */
+    /**
+     * Pick whichever screenshot tool is on `PATH`, in priority order.
+     * Cached after the first probe.
+     */
+    async pickScreenshotTool() {
+        if (this.screenshotBackend)
+            return this.screenshotBackend;
+        if (await this.whichBinary("gnome-screenshot")) {
+            this.screenshotBackend = "gnome-screenshot";
+            return "gnome-screenshot";
+        }
+        if (await this.whichBinary("scrot")) {
+            this.screenshotBackend = "scrot";
+            return "scrot";
+        }
+        if (await this.whichBinary("import")) {
+            this.screenshotBackend = "import";
+            return "import";
+        }
+        throw new DeviceError("linux screenshot requires `gnome-screenshot`, `scrot`, or ImageMagick `import` on PATH", { subtype: "environment", retriable: false });
+    }
+}
+//# sourceMappingURL=linux.js.map

package/dist/backends/linux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linux.js","sourceRoot":"","sources":["../../src/backends/linux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,OAAO,EACL,WAAW,GAGZ,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,kBAAkB,GAInB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAS;IAC5D,YAAY;IACZ,aAAa;IACb,aAAa;IACb,iBAAiB;CAClB,CAAC,CAAC;AAkBH,MAAM,aAAa,GAAW,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,EAAE,CACrD,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE;QAC7B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC;IACH,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,KAAiC,CAAC;IACtC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACzC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAClE,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACpE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;QACtB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC;IACZ,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QACzB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;IACH,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;AACH,CAAC,CAAC,CAAC;AAkBL,6EAA6E;AAC7E,8EAA8E;AAC9E,6EAA6E;AAE7E,MAAM,OAAO,YAAa,SAAQ,kBAAkB;IACzC,EAAE,GAAG,eAAwB,CAAC;IACrB,KAAK,GAAG,gBAAgB,CAAC;IAE1B,MAAM,CAAS;IACf,WAAW,CAAoC;IAC/C,cAAc,CAAS;IAExC,4DAA4D;IACpD,iBAAiB,GAAmD,IAAI,CAAC;IAEjF,YAAY,OAA4B,EAAE;QACxC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC;QAC3C,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC;QACpD,IAAI,CAAC,WAAW;YACd,IAAI,CAAC,WAAW;gBAChB,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;oBACb,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,cAAc,GAAG,EAAE,CAAC,CAAC,CAAC;oBACpE,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;gBAC7C,CAAC,CAAC,CAAC;IACP,CAAC;IAED,KAAK,CAAC,IAAI;QACR,8DAA8D;QAC9D,mEAAmE;QACnE,sEAAsE;QACtE,6CAA6C;QAC7C,MAAM,IAAI,GAAuB,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACzE,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,IAAI,EAAE,sBAAsB;YAC5B,EAAE,EAAE,OAAO;YACX,KAAK,EAAE,IAAI,CAAC,CAAC;YACb,MAAM,EAAE,IAAI,CAAC,CAAC;YACd,YAAY,EAAE,IAAI;YAClB,QAAQ,EAAE;gBACR,IAAI,EAAE,MAAM;gBACZ,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,IAAI,MAAM;aACpD;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC7C,IAAI,MAAiB,CAAC;QACtB,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,kBAAkB;gBACrB,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;gBAC7D,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;gBACjD,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBACnE,MAAM;QACV,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,WAAW,CAAC,wBAAwB,IAAI,YAAY,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE;gBACpF,OAAO,EAAE,aAAa;gBACtB,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;QAC1B,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,IAAI,MAAM,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YACrC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,6BAA6B;QAC/B,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,UAAU;QACd,kEAAkE;QAClE,2DAA2D;QAC3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;YACxC,IAAI;YACJ,6DAA6D;SAC9D,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACpD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;YACjC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,CAAC;QAED,kEAAkE;QAClE,uDAAuD;QACvD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;YACvC,IAAI;YACJ,iFAAiF;SAClF,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QAC/C,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC/B,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,CAAC;QAED,gEAAgE;QAChE,4CAA4C;QAC5C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,OAAe;QAClC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE;YACtD,SAAS,EAAE,IAAI,CAAC,cAAc;SAC/B,CAAC,CAAC;QACH,OAAO;YACL,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YACjC,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,QAAQ,EAAE,CAAC,CAAC,IAAI;SACjB,CAAC;IACJ,CAAC;IAED;;;;;;;sEAOkE;IAElE,2EAA2E;IAC3E,4EAA4E;IAC5E,2EAA2E;IAE3E;;;OAGG;IACK,KAAK,CAAC,kBAAkB;QAG9B,IAAI,IAAI,CAAC,iBAAiB;YAAE,OAAO,IAAI,CAAC,iBAAiB,CAAC;QAC1D,IAAI,MAAM,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC/C,IAAI,CAAC,iBAAiB,GAAG,kBAAkB,CAAC;YAC5C,OAAO,kBAAkB,CAAC;QAC5B,CAAC;QACD,IAAI,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC;YACjC,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,iBAAiB,GAAG,QAAQ,CAAC;YAClC,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,IAAI,WAAW,CACnB,wFAAwF,EACxF,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,EAAE,CAC7C,CAAC;IACJ,CAAC;CACF"}

package/dist/backends/mac.d.ts

@@ -0,0 +1,154 @@
+/**
+ * MacOsBackend — concrete `SandboxBackend` driving a real macOS host.
+ *
+ * Best-practice topology after researching the field (Anthropic Computer Use,
+ * OpenInterpreter os-mode, mac-control skill, the Python reference at
+ * `deviceagent_research/.../mcp_tools/backend_macos.py`, etc.):
+ *
+ *   - **Pointer** (click / move / drag / scroll / double / right / longPress):
+ *     `cliclick` (Homebrew, optional) preferred when on `PATH`; falls back to
+ *     `osascript` System Events when absent. cliclick is significantly more
+ *     reliable for coordinate-based mouse synthesis on modern (sandboxed) apps.
+ *   - **Keyboard** (typeText / pressKey / hotkey): `osascript` System Events.
+ *     Handles unicode, modifier chords, and raw key codes. No extra dependency.
+ *   - **Screenshot**: `screencapture -x -t png <tmpfile>`, read back into
+ *     memory, unlink — `screencapture` does NOT support stdout output despite
+ *     `-o -` / `-` folklore, so we round-trip through a per-call temp file.
+ *     `sharp` then resizes to the display's logical-point resolution so click
+ *     coords and screenshot pixels share one coordinate system (Retina-correct).
+ *   - **Screen size**: `system_profiler SPDisplaysDataType -json` parsed at
+ *     `connect()` time, cached for the process lifetime.
+ *   - **Launch app**: `open -a NAME` for human names, `open -b BUNDLE_ID` for
+ *     reverse-DNS bundle ids, `open <path>` for `.app`/`.dmg`/`.pkg`.
+ *   - **executeCommand**: `/bin/sh -c body`. Same shape as the Android backend.
+ *   - **file_read / write / list_directory**: Node `fs/promises` direct (we
+ *     run *on* the host).
+ *   - **Mobile verb aliasing** (matches reference convention): `tap → click`,
+ *     `swipe → drag`, `long_press → cliclick dd + sleep + du`. `back` is
+ *     unsupported on macOS, `home` is mapped to F11 (Mission Control "show
+ *     desktop").
+ *
+ * **Permissions**: the host process MUST hold Accessibility permission
+ * (System Settings → Privacy & Security → Accessibility). Without it macOS
+ * silently drops every synthetic input event. There is no programmatic
+ * bypass — we surface a `DeviceError("permission_required")` when cliclick /
+ * osascript exit non-zero so the operator can grant the permission.
+ *
+ * **Testability**: the constructor accepts an injected `runner` (an
+ * `execFile`-like async callable) and an `fs` shim. Defaults bind to a
+ * spawn-backed runner and `node:fs/promises`. Unit tests pass spy runners
+ * so the suite runs identically on Linux CI without any real shell calls.
+ */
+import { type DeviceInfo } from "@beeos-ai/device-common";
+import { BaseSandboxBackend, type ExecuteCommandOutput, type ListDirectoryEntry, type ScreenSize, type ScreenshotOutput } from "./base.js";
+export interface MacRunResult {
+    stdout: string | Buffer;
+    stderr: string;
+}
+export interface MacRunOptions {
+    encoding?: "buffer" | "utf8";
+    timeoutMs?: number;
+    input?: string | Buffer;
+    cwd?: string;
+}
+/**
+ * Async `execFile`-shaped callable. Throws on non-zero exit (with `code`,
+ * `stdout`, `stderr` decorated on the rejected error) so the backend can
+ * recognise the standard `NodeJS.ErrnoException` shape.
+ */
+export type MacRunner = (file: string, args: string[], opts?: MacRunOptions) => Promise<MacRunResult>;
+export interface MacFsShim {
+    readFile: (path: string) => Promise<Buffer>;
+    writeFile: (path: string, data: Buffer | string) => Promise<void>;
+    readdir: (path: string, opts: {
+        withFileTypes: true;
+    }) => Promise<Array<{
+        name: string;
+        isDirectory(): boolean;
+    }>>;
+    stat: (path: string) => Promise<{
+        size: number;
+        isDirectory(): boolean;
+    }>;
+    access: (path: string) => Promise<void>;
+    unlink: (path: string) => Promise<void>;
+    tmpdir: () => string;
+}
+export interface MacOsBackendOptions {
+    /** Override the default `child_process.spawn`-backed runner (tests). */
+    runner?: MacRunner;
+    /** Override `node:fs/promises` (tests). */
+    fs?: MacFsShim;
+    /**
+     * Override the resolved cliclick binary path. When omitted we probe
+     * `command -v cliclick` once at `connect()` time. Tests typically set this
+     * to "cliclick" (presence) or omit it together with `forceFallback`.
+     */
+    cliclickPath?: string;
+    /**
+     * When true, behave as if cliclick is absent — every pointer verb takes the
+     * `osascript` fallback path. Useful for unit tests and for hosts where
+     * cliclick is not installed.
+     */
+    forceFallback?: boolean;
+    /** Override autodetected pixel-to-point ratio (tests, multi-display). */
+    retinaScale?: number;
+    /** Override autodetected logical screen size (tests). */
+    size?: ScreenSize;
+    /** Sleep helper, injectable for deterministic tests of `longPress`. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class MacOsBackend extends BaseSandboxBackend {
+    readonly os: "desktop-macos";
+    readonly tools: ReadonlySet<string>;
+    private readonly runner;
+    private readonly fs;
+    private readonly sleep;
+    private cliclickPath;
+    private cliclickProbed;
+    private forceFallback;
+    private cachedSize;
+    private retinaScale;
+    constructor(opts?: MacOsBackendOptions);
+    connect(): Promise<void>;
+    info(): Promise<DeviceInfo>;
+    screenshot(): Promise<ScreenshotOutput>;
+    screenSize(): Promise<ScreenSize>;
+    click(x: number, y: number, button?: "left" | "right" | "middle", clicks?: number): Promise<void>;
+    doubleClick(x: number, y: number): Promise<void>;
+    rightClick(x: number, y: number): Promise<void>;
+    tap(x: number, y: number): Promise<void>;
+    longPress(x: number, y: number, durationMs?: number): Promise<void>;
+    drag(x1: number, y1: number, x2: number, y2: number, _durationMs?: number): Promise<void>;
+    swipe(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>;
+    move(x: number, y: number): Promise<void>;
+    typeText(text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    hotkey(...keys: string[]): Promise<void>;
+    home(): Promise<void>;
+    launchApp(pkgOrName: string, _activity?: string): Promise<void>;
+    executeCommand(body: string, opts?: {
+        timeoutS?: number;
+        cwd?: string;
+    }): Promise<ExecuteCommandOutput>;
+    fileRead(path: string): Promise<Buffer>;
+    fileWrite(path: string, content: Buffer | string): Promise<void>;
+    listDirectory(path: string): Promise<ListDirectoryEntry[]>;
+    install(path: string): Promise<void>;
+    private useCliclick;
+    private probeCliclick;
+    private probeDisplay;
+    private runCliclick;
+    private runOsa;
+    /**
+     * Run a JXA (JavaScript for Automation) script via `osascript -l JavaScript`.
+     * Used for pointer / scroll synthesis — JXA's ObjC bridge gives us direct
+     * Quartz CGEvent access, which is the only dependency-free way to drive
+     * synthetic mouse input on modern macOS (the AppleScript `click at {x, y}`
+     * surface has been broken since the 10.14 era).
+     */
+    private runJxa;
+    private runUtf8;
+    private runBuffer;
+}