@beeos-ai/device-agent 0.4.0

package/dist/mcp-client/autospawn.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Autospawn helper — fork a sibling `device-mcp-server` child process from
+ * inside the device-agent boot path, then hand back the URL the MCP client
+ * should connect to.
+ *
+ * The plan calls this `--mcp-autospawn` mode: the operator runs a single
+ * `device-agent` binary and we transparently start the MCP sibling as a
+ * child process. EdgeAgent / Kubernetes-managed deployments should NOT use
+ * this — they manage the two siblings themselves so the supervisor can
+ * restart them independently. Autospawn is purely for:
+ *
+ *   - local dev / quick-start (`device-agent --mcp-autospawn --mode desktop`)
+ *   - single-binary deployments where the user can't or doesn't want to run
+ *     a second process by hand
+ *
+ * Implementation notes:
+ *   - We resolve the MCP binary by package name (`@beeos-ai/device-mcp-server`)
+ *     so a `pnpm install` either workspace-symlinked or registry-installed
+ *     "just works". The override `DEVICE_MCP_BIN` env var lets EdgeAgent
+ *     point at a pre-built binary.
+ *   - A random ephemeral port is picked by binding a temporary OS socket
+ *     and immediately closing it; the kernel then leaves that port in
+ *     `TIME_WAIT` for a few hundred ms which is plenty of time for the
+ *     spawned MCP server to grab it.
+ *   - stdout / stderr are piped into the agent's logger so a sidecar log
+ *     stream is preserved.
+ *   - On agent shutdown the helper's `stop()` sends SIGTERM and then
+ *     SIGKILL after `gracePeriodMs` if the child hasn't exited.
+ */
+import { type ChildProcess } from "node:child_process";
+import type { Logger } from "../logger/index.js";
+export interface AutospawnOptions {
+    /** Backend family to forward to the MCP server's `--backend` flag. */
+    backend: "android" | "desktop" | "ios" | "windows" | "macos";
+    /** ADB serial — forwarded only for the `android` backend. */
+    adbSerial?: string;
+    /** Bind host for the spawned server (default `127.0.0.1`). */
+    host?: string;
+    /**
+     * Override the MCP binary path. Useful when the device-agent runs from a
+     * stand-alone `npm install -g` install where the workspace resolution
+     * doesn't apply, or in EdgeAgent where we point at a baked-in binary.
+     * Defaults to the `dist/cli.js` shipped by `@beeos-ai/device-mcp-server`,
+     * resolved via `require.resolve` against the device-agent package.
+     */
+    mcpBin?: string;
+    /** Extra arguments appended to the spawn command. */
+    extraArgs?: string[];
+    /** Logger sink — `stdout/stderr` lines are forwarded line-by-line. */
+    logger?: Logger;
+    /** Time we wait for SIGTERM before escalating to SIGKILL. */
+    gracePeriodMs?: number;
+}
+export interface AutospawnHandle {
+    /** `http://host:port` — pass to `McpClient` as its `baseUrl`. */
+    url: string;
+    /** The spawned child process (kept for tests and for log fan-out). */
+    child: ChildProcess;
+    /** Promise that resolves when the child exits. */
+    exited: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+    /** Terminate the child gracefully (SIGTERM → SIGKILL fallback). */
+    stop: () => Promise<void>;
+}
+export declare function autospawnMcpServer(opts: AutospawnOptions): Promise<AutospawnHandle>;

package/dist/mcp-client/autospawn.js

@@ -0,0 +1,173 @@
+/**
+ * Autospawn helper — fork a sibling `device-mcp-server` child process from
+ * inside the device-agent boot path, then hand back the URL the MCP client
+ * should connect to.
+ *
+ * The plan calls this `--mcp-autospawn` mode: the operator runs a single
+ * `device-agent` binary and we transparently start the MCP sibling as a
+ * child process. EdgeAgent / Kubernetes-managed deployments should NOT use
+ * this — they manage the two siblings themselves so the supervisor can
+ * restart them independently. Autospawn is purely for:
+ *
+ *   - local dev / quick-start (`device-agent --mcp-autospawn --mode desktop`)
+ *   - single-binary deployments where the user can't or doesn't want to run
+ *     a second process by hand
+ *
+ * Implementation notes:
+ *   - We resolve the MCP binary by package name (`@beeos-ai/device-mcp-server`)
+ *     so a `pnpm install` either workspace-symlinked or registry-installed
+ *     "just works". The override `DEVICE_MCP_BIN` env var lets EdgeAgent
+ *     point at a pre-built binary.
+ *   - A random ephemeral port is picked by binding a temporary OS socket
+ *     and immediately closing it; the kernel then leaves that port in
+ *     `TIME_WAIT` for a few hundred ms which is plenty of time for the
+ *     spawned MCP server to grab it.
+ *   - stdout / stderr are piped into the agent's logger so a sidecar log
+ *     stream is preserved.
+ *   - On agent shutdown the helper's `stop()` sends SIGTERM and then
+ *     SIGKILL after `gracePeriodMs` if the child hasn't exited.
+ */
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import * as path from "node:path";
+import * as url from "node:url";
+import { createRequire } from "node:module";
+/**
+ * Allocate a free TCP port. Binds to port 0 then immediately closes the
+ * server, returning the kernel-assigned port.
+ */
+async function allocateFreePort(host) {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.unref();
+        srv.on("error", reject);
+        srv.listen(0, host, () => {
+            const addr = srv.address();
+            if (addr === null || typeof addr === "string") {
+                srv.close();
+                reject(new Error("failed to allocate ephemeral port"));
+                return;
+            }
+            const port = addr.port;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+/**
+ * Resolve the device-mcp-server CLI entry point. Honors `mcpBin` override,
+ * then `DEVICE_MCP_BIN` env, then falls back to the workspace package's
+ * `bin: device-mcp-server` (`dist/cli.js`).
+ */
+function resolveMcpBin(opts) {
+    if (opts.mcpBin)
+        return opts.mcpBin;
+    if (process.env.DEVICE_MCP_BIN)
+        return process.env.DEVICE_MCP_BIN;
+    // `import.meta.url` works at runtime for both src/ (tsx) and dist/ (node).
+    const here = url.fileURLToPath(import.meta.url);
+    const req = createRequire(here);
+    try {
+        // Resolve the package's `dist/cli.js` directly (relative to its
+        // package.json) so we don't depend on the bin shim being on PATH.
+        const pkgJson = req.resolve("@beeos-ai/device-mcp-server/package.json");
+        return path.join(path.dirname(pkgJson), "dist", "cli.js");
+    }
+    catch {
+        // Fallback to PATH lookup of the bin shim.
+        return "device-mcp-server";
+    }
+}
+export async function autospawnMcpServer(opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const port = await allocateFreePort(host);
+    const bin = resolveMcpBin(opts);
+    const args = [
+        "--backend", opts.backend,
+        "--host", host,
+        "--port", String(port),
+    ];
+    if (opts.backend === "android" && opts.adbSerial) {
+        args.push("--adb-serial", opts.adbSerial);
+    }
+    if (opts.extraArgs?.length)
+        args.push(...opts.extraArgs);
+    const log = opts.logger;
+    const isJs = bin.endsWith(".js") || bin.endsWith(".mjs") || bin.endsWith(".cjs");
+    const command = isJs ? process.execPath : bin;
+    const argv = isJs ? [bin, ...args] : args;
+    log?.info({ bin, host, port, backend: opts.backend, isJs }, "mcp: autospawn starting");
+    const child = spawn(command, argv, {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+            ...process.env,
+            DEVICEAGENT_BACKEND: opts.backend,
+            MCP_HOST: host,
+            MCP_PORT: String(port),
+            ...(opts.adbSerial ? { ANDROID_SERIAL: opts.adbSerial } : {}),
+        },
+    });
+    pipeLines(child.stdout, (line) => log?.info({ src: "mcp.stdout" }, line));
+    pipeLines(child.stderr, (line) => log?.warn({ src: "mcp.stderr" }, line));
+    const exited = new Promise((resolve) => {
+        child.once("exit", (code, signal) => resolve({ code, signal }));
+    });
+    exited.then((r) => log?.warn({ ...r }, "mcp: autospawned child exited")).catch(() => undefined);
+    const grace = opts.gracePeriodMs ?? 3_000;
+    let stopped = false;
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (child.exitCode !== null)
+            return;
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            /* already gone */
+        }
+        const settled = await Promise.race([
+            exited.then(() => "exited"),
+            new Promise((res) => setTimeout(() => res("timeout"), grace)),
+        ]);
+        if (settled === "timeout") {
+            log?.warn({ pid: child.pid }, "mcp: SIGTERM timed out, sending SIGKILL");
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    };
+    return {
+        url: `http://${host}:${port}`,
+        child,
+        exited,
+        stop,
+    };
+}
+/** Pipe a readable stream of bytes into a per-line callback. */
+function pipeLines(stream, emit) {
+    if (!stream)
+        return;
+    let buf = "";
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => {
+        buf += chunk;
+        let nl = buf.indexOf("\n");
+        while (nl !== -1) {
+            const line = buf.slice(0, nl).replace(/\r$/, "");
+            if (line.length)
+                emit(line);
+            buf = buf.slice(nl + 1);
+            nl = buf.indexOf("\n");
+        }
+    });
+    stream.on("end", () => {
+        if (buf.length)
+            emit(buf);
+        buf = "";
+    });
+}
+//# sourceMappingURL=autospawn.js.map

package/dist/mcp-client/autospawn.js.map

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

package/dist/mcp-client/client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * McpClient — typed HTTP wrapper around `device-mcp-server`.
+ *
+ * The device-agent never talks to ADB / desktop sandboxes directly any more —
+ * everything goes through this client to the sibling MCP HTTP server. The
+ * client is intentionally thin: zero LLM / agent semantics, no caching, no
+ * retry on tool errors (only on connection-level failures during health
+ * probing).
+ *
+ * Defaults:
+ *   - baseUrl:  http://127.0.0.1:7900   (override via `MCP_URL` env)
+ *   - timeout:  30s per request
+ *
+ * Surface mirrors the Python reference's `MCPClient` plus a couple of
+ * device-agent–specific conveniences (`act`, `screenshot`, `uiDump`,
+ * `health`, `waitUntilReady`).
+ */
+import { type Action, type ActResponse, type DeviceInfo, type ExecuteCommandResult, type HealthResponse, type ScreenshotResult, type ToolListResponse, type UiDumpResult } from "@beeos-ai/device-common";
+import type { ExecuteCommandOptions, IMcpRuntime, UiDumpOptions } from "./runtime.js";
+export interface McpClientOptions {
+    /** HTTP base URL of the sibling device-mcp-server. Falls back to MCP_URL env / 127.0.0.1:7900. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Defaults to 30s. */
+    timeoutMs?: number;
+    /** Optional Bearer / shared-secret auth token forwarded as `Authorization: Bearer ...`. */
+    authToken?: string;
+    /** Optional fetch override (used by tests). */
+    fetchImpl?: typeof fetch;
+}
+export interface CallToolResult<T = unknown> {
+    ok: boolean;
+    raw: T;
+    durationMs: number;
+}
+/**
+ * Resolve the default MCP base URL (env-aware).
+ */
+export declare function resolveDefaultMcpUrl(): string;
+export declare class McpClient implements IMcpRuntime {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly authToken?;
+    private readonly fetchImpl;
+    constructor(opts?: McpClientOptions);
+    /** Backend health probe. Throws `McpUnreachableError` on connection failure. */
+    health(): Promise<HealthResponse>;
+    /**
+     * Wait until the MCP server's `/healthz` returns `ok=true`. Used by
+     * bootstrap to gate startup on the sibling process.
+     *
+     * Strategy: linear retry with `attemptDelayMs` between probes; gives up
+     * after `attempts` tries. Default: 10 × 500ms = ~5s.
+     */
+    waitUntilReady(opts?: {
+        attempts?: number;
+        attemptDelayMs?: number;
+    }): Promise<HealthResponse>;
+    /** List all registered MCP tool descriptors. */
+    listTools(): Promise<ToolListResponse>;
+    /** Invoke a single MCP tool by name. */
+    callTool<T = unknown>(name: string, args?: Record<string, unknown>): Promise<CallToolResult<T>>;
+    /** Submit a unified Action — server maps to the right tool internally. */
+    act(action: Action): Promise<ActResponse>;
+    /** Convenience: take a screenshot via `tool: screenshot`. */
+    screenshot(): Promise<ScreenshotResult>;
+    /**
+     * Convenience: dump UI hierarchy. `format: "compact"` returns the LLM-ready
+     * filtered text; `"raw"` returns full uiautomator XML.
+     */
+    uiDump(opts?: UiDumpOptions): Promise<UiDumpResult>;
+    /** Convenience: backend `device_info` tool — the canonical DeviceInfo descriptor. */
+    info(): Promise<DeviceInfo>;
+    /** Convenience: install an APK on the (Android) sandbox. */
+    installApk(path: string): Promise<void>;
+    /** Convenience: run a shell command on the sandbox. */
+    executeCommand(body: string, opts?: ExecuteCommandOptions): Promise<ExecuteCommandResult>;
+    private request;
+}

package/dist/mcp-client/client.js

@@ -0,0 +1,168 @@
+/**
+ * McpClient — typed HTTP wrapper around `device-mcp-server`.
+ *
+ * The device-agent never talks to ADB / desktop sandboxes directly any more —
+ * everything goes through this client to the sibling MCP HTTP server. The
+ * client is intentionally thin: zero LLM / agent semantics, no caching, no
+ * retry on tool errors (only on connection-level failures during health
+ * probing).
+ *
+ * Defaults:
+ *   - baseUrl:  http://127.0.0.1:7900   (override via `MCP_URL` env)
+ *   - timeout:  30s per request
+ *
+ * Surface mirrors the Python reference's `MCPClient` plus a couple of
+ * device-agent–specific conveniences (`act`, `screenshot`, `uiDump`,
+ * `health`, `waitUntilReady`).
+ */
+import { McpUnreachableError, } from "@beeos-ai/device-common";
+const DEFAULT_BASE_URL = "http://127.0.0.1:7900";
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Resolve the default MCP base URL (env-aware).
+ */
+export function resolveDefaultMcpUrl() {
+    return process.env.MCP_URL ?? DEFAULT_BASE_URL;
+}
+export class McpClient {
+    baseUrl;
+    timeoutMs;
+    authToken;
+    fetchImpl;
+    constructor(opts = {}) {
+        this.baseUrl = trimTrailingSlash(opts.baseUrl ?? resolveDefaultMcpUrl());
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.authToken = opts.authToken;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    /** Backend health probe. Throws `McpUnreachableError` on connection failure. */
+    async health() {
+        try {
+            return await this.request("GET", "/healthz");
+        }
+        catch (e) {
+            throw new McpUnreachableError(`MCP server unreachable at ${this.baseUrl}: ${e.message}`, e);
+        }
+    }
+    /**
+     * Wait until the MCP server's `/healthz` returns `ok=true`. Used by
+     * bootstrap to gate startup on the sibling process.
+     *
+     * Strategy: linear retry with `attemptDelayMs` between probes; gives up
+     * after `attempts` tries. Default: 10 × 500ms = ~5s.
+     */
+    async waitUntilReady(opts = {}) {
+        const attempts = opts.attempts ?? 10;
+        const delay = opts.attemptDelayMs ?? 500;
+        let lastErr;
+        for (let i = 0; i < attempts; i++) {
+            try {
+                const h = await this.health();
+                if (h.ok)
+                    return h;
+            }
+            catch (e) {
+                lastErr = e;
+            }
+            await new Promise((res) => setTimeout(res, delay));
+        }
+        throw new McpUnreachableError(`MCP server at ${this.baseUrl} did not become ready after ${attempts} attempts`, lastErr);
+    }
+    /** List all registered MCP tool descriptors. */
+    async listTools() {
+        return this.request("POST", "/mcp/tools/list", {});
+    }
+    /** Invoke a single MCP tool by name. */
+    async callTool(name, args = {}) {
+        const res = await this.request("POST", "/mcp/tools/call", {
+            name,
+            arguments: args,
+        });
+        return { ok: res.ok, raw: res.result, durationMs: res.durationMs };
+    }
+    /** Submit a unified Action — server maps to the right tool internally. */
+    async act(action) {
+        return this.request("POST", "/act", { action });
+    }
+    /** Convenience: take a screenshot via `tool: screenshot`. */
+    async screenshot() {
+        const r = await this.callTool("screenshot", {});
+        return r.raw;
+    }
+    /**
+     * Convenience: dump UI hierarchy. `format: "compact"` returns the LLM-ready
+     * filtered text; `"raw"` returns full uiautomator XML.
+     */
+    async uiDump(opts = {}) {
+        const args = {};
+        if (opts.query !== undefined)
+            args.query = opts.query;
+        if (opts.format !== undefined)
+            args.format = opts.format;
+        const r = await this.callTool("ui_dump", args);
+        return r.raw;
+    }
+    /** Convenience: backend `device_info` tool — the canonical DeviceInfo descriptor. */
+    async info() {
+        const r = await this.callTool("device_info", {});
+        return r.raw;
+    }
+    /** Convenience: install an APK on the (Android) sandbox. */
+    async installApk(path) {
+        await this.callTool("install_apk", { path });
+    }
+    /** Convenience: run a shell command on the sandbox. */
+    async executeCommand(body, opts = {}) {
+        const r = await this.callTool("execute_command", {
+            body,
+            ...(opts.timeoutS !== undefined ? { timeoutS: opts.timeoutS } : {}),
+            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        });
+        return r.raw;
+    }
+    /* ------------------------------------------------------------------ */
+    /* Internal HTTP plumbing                                               */
+    /* ------------------------------------------------------------------ */
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = { "content-type": "application/json" };
+        if (this.authToken)
+            headers.authorization = `Bearer ${this.authToken}`;
+        const controller = new AbortController();
+        const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            const text = await res.text();
+            const parsed = text ? safeJson(text) : undefined;
+            if (!res.ok) {
+                const errMsg = (parsed && typeof parsed === "object" && parsed.error) ||
+                    `HTTP ${res.status} ${res.statusText}`;
+                const err = new Error(`MCP ${method} ${path} failed: ${errMsg}`);
+                err.status = res.status;
+                err.body = parsed ?? text;
+                throw err;
+            }
+            return parsed;
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+    }
+}
+function trimTrailingSlash(s) {
+    return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+function safeJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/mcp-client/client.js.map

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

package/dist/mcp-client/index.d.ts

@@ -0,0 +1,7 @@
+export { McpClient, resolveDefaultMcpUrl } from "./client.js";
+export type { McpClientOptions, CallToolResult } from "./client.js";
+export type { IMcpRuntime, UiDumpOptions, ExecuteCommandOptions } from "./runtime.js";
+export { InProcMcpClient } from "./inproc.js";
+export type { InProcMcpClientOptions } from "./inproc.js";
+export { autospawnMcpServer } from "./autospawn.js";
+export type { AutospawnOptions, AutospawnHandle } from "./autospawn.js";

package/dist/mcp-client/index.js

@@ -0,0 +1,4 @@
+export { McpClient, resolveDefaultMcpUrl } from "./client.js";
+export { InProcMcpClient } from "./inproc.js";
+export { autospawnMcpServer } from "./autospawn.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp-client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp-client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/mcp-client/inproc.d.ts

@@ -0,0 +1,47 @@
+/**
+ * InProcMcpClient — legacy `Device` bridge that satisfies the `IMcpRuntime`
+ * contract without any HTTP hop.
+ *
+ * Used internally by the legacy `Agent` shim and by tests / harness scripts
+ * that already hold a low-level `Device` and want to drive it via the new
+ * `AgentLoop` pipeline. Production paths should always go through the real
+ * `McpClient` (sibling device-mcp-server).
+ *
+ * The translation layer lives here on purpose:
+ *   - `Action` (new schema) → legacy `Device` method calls
+ *   - `Device.takeScreenshot()` → `ScreenshotResult` wire shape
+ *   - `Device.getUiXml()` → `UiDumpResult` wire shape
+ *
+ * The ACP plugin and the sibling-MCP path additionally need
+ * `info / installApk / executeCommand`. When the constructor is also given
+ * a high-level `IDevice` (which has `getInfo / install / shell`) those
+ * methods are wired through; otherwise they throw a clear error.
+ *
+ * Coordinates are forwarded as-is — `AgentLoop.scaleAction()` already does
+ * its 0-1000 / smart_resize → absolute conversion before calling `act()`.
+ */
+import type { Action, ActResponse, DeviceInfo, ExecuteCommandResult, ScreenshotResult, UiDumpResult } from "@beeos-ai/device-common";
+import type { Device } from "../device/base.js";
+import type { IDevice } from "../ports/device.js";
+import type { ExecuteCommandOptions, IMcpRuntime, UiDumpOptions } from "./runtime.js";
+export interface InProcMcpClientOptions {
+    /**
+     * High-level device handle — when provided, enables the ACP-only
+     * `info / installApk / executeCommand` methods so the legacy in-process
+     * single-binary deployment can keep handling `device/info` etc. without
+     * a sibling MCP server.
+     */
+    idevice?: IDevice;
+}
+export declare class InProcMcpClient implements IMcpRuntime {
+    private readonly device;
+    private readonly idevice?;
+    constructor(device: Device, opts?: InProcMcpClientOptions);
+    screenshot(): Promise<ScreenshotResult>;
+    uiDump(_opts?: UiDumpOptions): Promise<UiDumpResult>;
+    info(): Promise<DeviceInfo>;
+    installApk(path: string): Promise<void>;
+    executeCommand(body: string, _opts?: ExecuteCommandOptions): Promise<ExecuteCommandResult>;
+    act(action: Action): Promise<ActResponse>;
+    private dispatch;
+}