@beeos-ai/device-agent 0.4.0

package/dist/device/ui-xml.js

@@ -0,0 +1,194 @@
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Fetch UI hierarchy from the device and return a compact, LLM-ready string.
+ *
+ * No query  → all interactive + standalone-text nodes, one line each.
+ * With query → same list filtered by substring match on text / resource-id /
+ *              content-desc / class (case-insensitive).
+ */
+export async function queryUiXml(device, query) {
+    const xml = await device.getUiXml();
+    if (!xml)
+        return "Failed to get UI XML";
+    return formatUiXmlToolOutput(xml, query);
+}
+/** Same string the `ui_xml` tool returns, given already-fetched XML. */
+export function formatUiXmlToolOutput(xml, query) {
+    const root = parseXmlTree(xml);
+    if (!root)
+        return "Failed to parse UI XML";
+    const nodes = collectNodes(root);
+    const filtered = query ? filterNodes(nodes, query) : nodes;
+    if (filtered.length === 0) {
+        return query ? `No elements found matching "${query}"` : "No interactive elements found";
+    }
+    return filtered.map(formatNode).join("\n");
+}
+/**
+ * Search raw XML for nodes matching a query — used by test:ui-xml script.
+ * Returns UiNode[] for JSON dump; formatUiXmlToolOutput() is the tool path.
+ */
+export function searchUiXmlNodes(xml, query) {
+    const root = parseXmlTree(xml);
+    if (!root)
+        return [];
+    const nodes = collectNodes(root);
+    const filtered = query ? filterNodes(nodes, query) : nodes;
+    return filtered.map(treeNodeToUiNode);
+}
+// ── XML tree parser ───────────────────────────────────────────────────────────
+function parseXmlTree(xml) {
+    // Tokenise: <node ...>, <node .../>, </node>
+    const re = /<(\/?)node(\s[^>]*)?(\/?)>/g;
+    let m;
+    const dummy = makeNode("");
+    const stack = [dummy];
+    while ((m = re.exec(xml)) !== null) {
+        const isClose = m[1] === "/";
+        const isSelf = m[3] === "/";
+        const attrs = m[2] ?? "";
+        if (isClose) {
+            if (stack.length > 1)
+                stack.pop();
+        }
+        else {
+            const node = makeNode(attrs);
+            const parent = stack[stack.length - 1];
+            node.parent = parent;
+            parent.children.push(node);
+            if (!isSelf)
+                stack.push(node);
+        }
+    }
+    return dummy.children[0] ?? null;
+}
+function makeNode(attrs) {
+    const bounds = attr(attrs, "bounds");
+    return {
+        text: attr(attrs, "text"),
+        contentDesc: attr(attrs, "content-desc"),
+        resourceId: attr(attrs, "resource-id"),
+        className: attr(attrs, "class"),
+        bounds,
+        clickable: attr(attrs, "clickable") === "true",
+        longClickable: attr(attrs, "long-clickable") === "true",
+        scrollable: attr(attrs, "scrollable") === "true",
+        focusable: attr(attrs, "focusable") === "true",
+        enabled: attr(attrs, "enabled") !== "false",
+        center: boundsCenter(bounds),
+        children: [],
+    };
+}
+function attr(attrs, name) {
+    return attrs.match(new RegExp(`${name}="([^"]*)"`, "i"))?.[1] ?? "";
+}
+function boundsCenter(bounds) {
+    const m = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+    if (!m)
+        return { x: 0, y: 0 };
+    return { x: Math.round((+m[1] + +m[3]) / 2), y: Math.round((+m[2] + +m[4]) / 2) };
+}
+// ── Node collection ───────────────────────────────────────────────────────────
+function isInteractive(n) {
+    return n.enabled && (n.clickable || n.longClickable || n.scrollable || n.focusable);
+}
+function hasInteractiveAncestor(n) {
+    let p = n.parent;
+    while (p) {
+        if (isInteractive(p))
+            return true;
+        p = p.parent;
+    }
+    return false;
+}
+function displayText(n) {
+    return n.text || n.contentDesc;
+}
+/** Collect interactive nodes + standalone text nodes (no interactive ancestor). */
+function collectNodes(root) {
+    const result = [];
+    function walk(n) {
+        if (!n.enabled)
+            return;
+        if (isInteractive(n)) {
+            result.push(n);
+        }
+        else if (displayText(n) && !hasInteractiveAncestor(n)) {
+            result.push(n);
+        }
+        for (const child of n.children)
+            walk(child);
+    }
+    walk(root);
+    return result;
+}
+// ── Filtering ────────────────────────────────────────────────────────────────
+function filterNodes(nodes, query) {
+    const q = query.toLowerCase();
+    return nodes.filter((n) => n.text.toLowerCase().includes(q) ||
+        n.contentDesc.toLowerCase().includes(q) ||
+        n.resourceId.toLowerCase().includes(q) ||
+        n.className.toLowerCase().includes(q));
+}
+// ── Compact line formatter ────────────────────────────────────────────────────
+const CLASS_SHORT = {
+    Button: "Btn",
+    ImageButton: "ImgBtn",
+    TextView: "Text",
+    EditText: "Edit",
+    ImageView: "Img",
+    CheckBox: "Check",
+    Switch: "Switch",
+    RadioButton: "Radio",
+    ListView: "List",
+    RecyclerView: "List",
+    ScrollView: "Scroll",
+    HorizontalScrollView: "HScroll",
+    ViewPager: "Pager",
+    WebView: "Web",
+    FrameLayout: "Frame",
+    LinearLayout: "Layout",
+    RelativeLayout: "Layout",
+    ConstraintLayout: "Layout",
+};
+function shortClass(cls) {
+    const base = cls.split(".").pop() ?? cls;
+    return CLASS_SHORT[base] ?? base;
+}
+/**
+ * Compact one-liner: (x,y) Type "text" id=pkg:id/name *click *scroll *focus *lclick
+ * Omits empty text and false flags to minimise tokens.
+ */
+function formatNode(n) {
+    const parts = [];
+    parts.push(`(${n.center.x},${n.center.y})`);
+    parts.push(shortClass(n.className));
+    const label = displayText(n);
+    if (label)
+        parts.push(`"${label}"`);
+    if (n.resourceId)
+        parts.push(`id=${n.resourceId}`);
+    if (n.clickable)
+        parts.push("*click");
+    if (n.longClickable)
+        parts.push("*lclick");
+    if (n.scrollable)
+        parts.push("*scroll");
+    if (n.focusable && !n.clickable)
+        parts.push("*focus");
+    return parts.join(" ");
+}
+// ── UiNode conversion (for test script / backward compat) ────────────────────
+function treeNodeToUiNode(n) {
+    return {
+        text: n.text,
+        resourceId: n.resourceId,
+        contentDesc: n.contentDesc,
+        className: n.className,
+        bounds: n.bounds,
+        center: n.center,
+        clickable: n.clickable,
+        enabled: n.enabled,
+    };
+}
+//# sourceMappingURL=ui-xml.js.map

package/dist/device/ui-xml.js.map

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

package/dist/fleet/adapters/process/node-process-manager.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Adapter — `IProcessManager` implementation backed by `child_process.spawn`.
+ *
+ * Spawns and supervises up to three long-running siblings per bound device:
+ *
+ *   - **mcp**    `device-mcp-server --backend <kind> --adb-serial <serial>
+ *                 --host 127.0.0.1 --port <mcpPort>`
+ *   - **daemon** `device-agent --key <keyFile> --agent-gateway-url <url>
+ *                 --mcp-url http://127.0.0.1:<mcpPort> --adb <serial>
+ *                 [--http --http-port <httpPort>]`
+ *   - **scrcpy** `scrcpy-bridge` (no args; configured via env mirroring
+ *                 `web/packages/core/src/runtime/scrcpy-bridge.ts` `buildEnv`).
+ *                 Optional — only spawned when the binding's `videoMode === "scrcpy"`.
+ *
+ * Lifecycle responsibilities:
+ *
+ *   - `spawnMcp` waits for `GET /healthz` to return 200 (configurable timeout)
+ *     before emitting `mcp_started`. If readiness times out the spawn is
+ *     killed and an `mcp_exited` event is reported (so the FSM treats the
+ *     attempt as a crash and either retries or backs off).
+ *   - `spawnDaemon` emits `daemon_started` as soon as the child has a PID
+ *     (the daemon's own readiness is observable through ACP traffic which is
+ *     out of fleet scope; the daemon process itself dying is what we react to
+ *     here). Optional `daemonHttpPort` is probed similarly when set.
+ *   - `spawnScrcpy` is best-effort — a missing binary yields a synthetic
+ *     `scrcpy_exited` event (with `reason`) instead of a thrown error.
+ *     scrcpy-bridge has no `/healthz`, so readiness is degraded to
+ *     "process still alive `scrcpyStartupGraceMs` after spawn"; before that
+ *     window elapses we don't emit `scrcpy_started`. If the child exits
+ *     within the grace, we emit `scrcpy_exited` instead.
+ *   - `kill*` sends SIGTERM, then SIGKILL after `shutdownGraceMs`. When the
+ *     supervisor initiates the kill we mark the resulting exit as `expected`
+ *     so the pure FSM (`fsm.ts`) doesn't penalise restartCount.
+ *   - When a child dies on its own (`expected=false`), we emit the matching
+ *     `*_exited` event and let the supervisor (driving the FSM) decide whether
+ *     to respawn. We never auto-restart from inside this adapter — the FSM
+ *     owns the policy.
+ *
+ * Binary discovery:
+ *   - mcp:    `BEEOS_DEVICE_MCP_BIN` → `device-mcp-server` on PATH (override via opts.mcpBin).
+ *   - daemon: `BEEOS_DEVICE_AGENT_BIN` → `device-agent` on PATH (override via opts.daemonBin).
+ *   - scrcpy: `BEEOS_SCRCPY_BRIDGE_BIN` env → `~/.beeos/bin/scrcpy-bridge[.exe]` (managed install).
+ *             Override via `opts.scrcpyBin` (absolute path) or `opts.findScrcpyBinFn` (test hook).
+ *
+ * The implementation deliberately exposes a hookable `spawnFn` /
+ * `httpProbeFn` / `findScrcpyBinFn` so unit tests can drive the manager with
+ * fake children and synthetic /healthz responses without touching the OS.
+ */
+import type { IProcessManager, ManagedProcess, ProcessEventListener, SpawnOptions, SpawnScrcpyOptions } from "../../ports/process-manager.js";
+export interface ProcessManagerLogger {
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+}
+/** Minimal subset of `child_process.ChildProcess` we depend on. */
+export interface ManagedChild {
+    readonly pid: number | null | undefined;
+    kill(signal?: NodeJS.Signals): boolean;
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    once(event: "error", listener: (err: Error) => void): void;
+}
+export type SpawnFn = (bin: string, args: readonly string[], env: NodeJS.ProcessEnv) => ManagedChild;
+export type HttpProbeFn = (url: string, timeoutMs: number) => Promise<boolean>;
+export interface NodeProcessManagerOptions {
+    /** Path / argv0 for `device-mcp-server` (split via shlex if it has spaces). */
+    mcpBin?: string;
+    /** Path / argv0 for `device-agent` (the daemon entry). Defaults to current `argv[1]`. */
+    daemonBin?: string;
+    /**
+     * Path / argv0 for `scrcpy-bridge`. When unset the manager falls back to
+     * `BEEOS_SCRCPY_BRIDGE_BIN` env then `~/.beeos/bin/scrcpy-bridge[.exe]`
+     * (the cargo-dist managed install location used by `scrcpyBridgeRuntime`).
+     */
+    scrcpyBin?: string;
+    /** mcp backend (`android`, `desktop`, `macos`, …). Defaults to `android`. */
+    mcpBackend?: string;
+    /** Bind host for mcp-server (default `127.0.0.1`). */
+    mcpHost?: string;
+    /** Public Agent Gateway URL forwarded to daemons. */
+    agentGatewayUrl?: string;
+    /** Bridge URL forwarded to daemons (rarely needed; default discovers via Agent Gateway). */
+    bridgeUrl?: string;
+    /** Optional region passed to daemon. */
+    region?: string;
+    /** Initial readiness probe timeout for mcp `/healthz`. */
+    mcpHealthTimeoutMs?: number;
+    /**
+     * Window we wait for scrcpy-bridge to keep running before declaring it
+     * healthy (defaults to 5 s, matching the launchd `KeepAlive=on-failure`
+     * grace). Tests should set this to a small value (e.g. 10 ms) to keep the
+     * suite fast.
+     */
+    scrcpyStartupGraceMs?: number;
+    /** SIGTERM → SIGKILL grace. */
+    shutdownGraceMs?: number;
+    /** Hook for unit tests; defaults to `child_process.spawn`. */
+    spawnFn?: SpawnFn;
+    /** Hook for unit tests; defaults to a real HTTP GET. */
+    httpProbeFn?: HttpProbeFn;
+    /**
+     * Hook for unit tests + dependency injection — when supplied, takes
+     * precedence over the default discovery chain (`scrcpyBin` →
+     * `BEEOS_SCRCPY_BRIDGE_BIN` → `~/.beeos/bin/scrcpy-bridge`).
+     * Returns `null` when the binary cannot be located.
+     */
+    findScrcpyBinFn?: () => Promise<string | null>;
+    /** Optional logger. */
+    logger?: ProcessManagerLogger;
+    /** Extra env vars to merge into every child (e.g. `MCP_URL`). */
+    extraEnv?: NodeJS.ProcessEnv;
+}
+export declare class NodeProcessManager implements IProcessManager {
+    private readonly mcpBin;
+    private readonly daemonBin;
+    private readonly scrcpyBinOverride?;
+    private readonly mcpBackend;
+    private readonly mcpHost;
+    private readonly agentGatewayUrl?;
+    private readonly bridgeUrl?;
+    private readonly region?;
+    private readonly mcpHealthTimeoutMs;
+    private readonly scrcpyStartupGraceMs;
+    private readonly shutdownGraceMs;
+    private readonly spawnFn;
+    private readonly httpProbeFn;
+    private readonly findScrcpyBinFn;
+    private readonly logger;
+    private readonly extraEnv;
+    private readonly slots;
+    private readonly listeners;
+    private started;
+    constructor(opts?: NodeProcessManagerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    on(listener: ProcessEventListener): () => void;
+    isAlive(serial: string, which: ManagedProcess): boolean;
+    pid(serial: string, which: ManagedProcess): number | null;
+    private slotFor;
+    private setSlot;
+    spawnMcp(opts: SpawnOptions): Promise<void>;
+    spawnDaemon(opts: SpawnOptions): Promise<void>;
+    spawnScrcpy(opts: SpawnScrcpyOptions): Promise<void>;
+    killMcp(serial: string, opts?: {
+        expected?: boolean;
+    }): Promise<void>;
+    killDaemon(serial: string, opts?: {
+        expected?: boolean;
+    }): Promise<void>;
+    killScrcpy(serial: string, opts?: {
+        expected?: boolean;
+    }): Promise<void>;
+    private ensureSlot;
+    private attachExitListener;
+    private killChild;
+    private emit;
+}