@beeos-ai/device-agent 0.9.3 → 0.9.5

package/dist/health/adb-track-devices.d.ts

@@ -0,0 +1,103 @@
+/**
+ * AdbTrackDevices — push-source for MCPHealthMonitor.
+ *
+ * Subscribes to `adb track-devices` events for a single target serial and
+ * emits a debounced `change` event whenever the device's authoritative
+ * ADB state transitions. Wired into MCPHealthMonitor in the ACP plugin so
+ * USB unplug events propagate to the cluster within ~2-3s instead of
+ * waiting for the 60s active probe / 5s flap window.
+ *
+ * Why a thin wrapper around fleet's LocalAdbSource?
+ *   The fleet supervisor already implements a complete `adb track-devices`
+ *   client (frame parser, retry with backoff, snapshot diffing). Spawning
+ *   a second client from inside device-agent (when running under fleet)
+ *   wastes one process per device, but the alternative — fleet → child
+ *   IPC — is materially more complex (~170 lines vs ~80 lines for double-
+ *   spawn). Per-device overhead is < 5 MB; the adb daemon supports
+ *   multiple concurrent track-devices clients without coordination, and
+ *   keeping the two stacks independent gives us fault isolation (if fleet
+ *   crashes, device-agent still detects the disconnect).
+ *
+ * Asymmetric debounce (KISS-derived from real UX requirements):
+ *   - Non-healthy states (offline / unauthorized / absent) → 2000 ms
+ *     trailing debounce. Covers typical USB jitter (cable wiggle, hub
+ *     re-enumeration, ADB auth race) without spamming the control plane.
+ *     Each new observation cancels the pending emission, so a single
+ *     short hiccup never reaches health-reporter.
+ *   - Healthy state (device) → emitted immediately (0 ms). The user is
+ *     actively waiting for "I plugged back in, did it work?" feedback, so
+ *     any delay is a UX regression. Emitting healthy also cancels any
+ *     pending offline emission so post-jitter recovery doesn't briefly
+ *     report disconnect.
+ *
+ * Both values are module-level constants (YAGNI — no env override until
+ * a real user reports their hub jitters longer than 2s; tests inject
+ * mock LocalAdbSource events directly).
+ */
+import { LocalAdbSource } from "../fleet/adapters/sources/local-adb.js";
+import { EventEmitter } from "node:events";
+import type { Logger } from "pino";
+export type AdbHealthState = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "device_disconnected" | "device_unauthorized";
+};
+export interface AdbTrackDevicesOptions {
+    /** Target serial — only emit for this serial. Required. */
+    targetSerial: string;
+    logger: Logger;
+    /**
+     * Test seam — inject a custom IDeviceSource (e.g. a mock that exposes
+     * `emit`) instead of spawning a real `adb track-devices`. Production
+     * callers omit and get the default LocalAdbSource.
+     */
+    source?: ConstructorOf<LocalAdbSource> | LocalAdbSource;
+}
+type ConstructorOf<T> = new (...args: never[]) => T;
+export declare class AdbTrackDevices extends EventEmitter {
+    private readonly targetSerial;
+    private readonly logger;
+    private readonly source;
+    private unsubscribe;
+    private pendingTimer;
+    private lastEmitted;
+    private currentObserved;
+    private disposed;
+    constructor(opts: AdbTrackDevicesOptions);
+    /**
+     * Begin observing. Idempotent. If the underlying `adb` command can't be
+     * spawned, LocalAdbSource will retry with exponential backoff — we
+     * surface that via log only; no `unavailable` event because the source
+     * may eventually recover.
+     */
+    start(): Promise<void>;
+    /**
+     * Tear down: unsubscribe from source, stop the source, clear any pending
+     * debounce timer. Safe to call multiple times.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Translate an AdbEvent into the AdbHealthState shape and feed it
+     * through the asymmetric debounce machinery.
+     *
+     * Mapping:
+     *   adb_online        → ok: true              (immediate emit)
+     *   adb_unauthorized  → ok: false / unauth    (2s debounce — user may
+     *                                              still tap "Allow")
+     *   adb_offline       → ok: false / discon    (2s debounce — USB jitter)
+     */
+    private observeEvent;
+    /**
+     * Asymmetric trailing debounce.
+     *   - If `next` is unchanged from `lastEmitted`, no-op.
+     *   - Always cancel any pending timer (a new observation supersedes a
+     *     previously scheduled emit — this is what kills false alarms
+     *     during sub-2s jitter).
+     *   - Healthy: emit immediately (HEALTHY_DEBOUNCE_MS=0).
+     *   - Unhealthy: schedule emit after OFFLINE_DEBOUNCE_MS=2000.
+     */
+    private scheduleEmit;
+    private emitNow;
+}
+export {};

package/dist/health/adb-track-devices.js

@@ -0,0 +1,171 @@
+/**
+ * AdbTrackDevices — push-source for MCPHealthMonitor.
+ *
+ * Subscribes to `adb track-devices` events for a single target serial and
+ * emits a debounced `change` event whenever the device's authoritative
+ * ADB state transitions. Wired into MCPHealthMonitor in the ACP plugin so
+ * USB unplug events propagate to the cluster within ~2-3s instead of
+ * waiting for the 60s active probe / 5s flap window.
+ *
+ * Why a thin wrapper around fleet's LocalAdbSource?
+ *   The fleet supervisor already implements a complete `adb track-devices`
+ *   client (frame parser, retry with backoff, snapshot diffing). Spawning
+ *   a second client from inside device-agent (when running under fleet)
+ *   wastes one process per device, but the alternative — fleet → child
+ *   IPC — is materially more complex (~170 lines vs ~80 lines for double-
+ *   spawn). Per-device overhead is < 5 MB; the adb daemon supports
+ *   multiple concurrent track-devices clients without coordination, and
+ *   keeping the two stacks independent gives us fault isolation (if fleet
+ *   crashes, device-agent still detects the disconnect).
+ *
+ * Asymmetric debounce (KISS-derived from real UX requirements):
+ *   - Non-healthy states (offline / unauthorized / absent) → 2000 ms
+ *     trailing debounce. Covers typical USB jitter (cable wiggle, hub
+ *     re-enumeration, ADB auth race) without spamming the control plane.
+ *     Each new observation cancels the pending emission, so a single
+ *     short hiccup never reaches health-reporter.
+ *   - Healthy state (device) → emitted immediately (0 ms). The user is
+ *     actively waiting for "I plugged back in, did it work?" feedback, so
+ *     any delay is a UX regression. Emitting healthy also cancels any
+ *     pending offline emission so post-jitter recovery doesn't briefly
+ *     report disconnect.
+ *
+ * Both values are module-level constants (YAGNI — no env override until
+ * a real user reports their hub jitters longer than 2s; tests inject
+ * mock LocalAdbSource events directly).
+ */
+import { LocalAdbSource } from "../fleet/adapters/sources/local-adb.js";
+import { EventEmitter } from "node:events";
+const OFFLINE_DEBOUNCE_MS = 2000;
+const HEALTHY_DEBOUNCE_MS = 0;
+export class AdbTrackDevices extends EventEmitter {
+    targetSerial;
+    logger;
+    source;
+    unsubscribe = null;
+    pendingTimer = null;
+    lastEmitted = null;
+    currentObserved = null;
+    disposed = false;
+    constructor(opts) {
+        super();
+        this.targetSerial = opts.targetSerial;
+        this.logger = opts.logger;
+        // The injected `source` is for tests; production path constructs a
+        // fresh LocalAdbSource so each device-agent process has its own
+        // `adb track-devices` subprocess (per the fault-isolation rationale
+        // in the file header).
+        this.source =
+            opts.source instanceof LocalAdbSource
+                ? opts.source
+                : new LocalAdbSource({
+                    logger: {
+                        debug: (msg, data) => this.logger.debug(data ?? {}, msg),
+                        info: (msg, data) => this.logger.info(data ?? {}, msg),
+                        warn: (msg, data) => this.logger.warn(data ?? {}, msg),
+                        error: (msg, data) => this.logger.error(data ?? {}, msg),
+                    },
+                });
+    }
+    /**
+     * Begin observing. Idempotent. If the underlying `adb` command can't be
+     * spawned, LocalAdbSource will retry with exponential backoff — we
+     * surface that via log only; no `unavailable` event because the source
+     * may eventually recover.
+     */
+    async start() {
+        if (this.disposed || this.unsubscribe)
+            return;
+        this.unsubscribe = this.source.on((event) => {
+            if (event.serial !== this.targetSerial)
+                return;
+            this.observeEvent(event);
+        });
+        await this.source.start();
+    }
+    /**
+     * Tear down: unsubscribe from source, stop the source, clear any pending
+     * debounce timer. Safe to call multiple times.
+     */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.pendingTimer) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+        await this.source.stop();
+    }
+    /**
+     * Translate an AdbEvent into the AdbHealthState shape and feed it
+     * through the asymmetric debounce machinery.
+     *
+     * Mapping:
+     *   adb_online        → ok: true              (immediate emit)
+     *   adb_unauthorized  → ok: false / unauth    (2s debounce — user may
+     *                                              still tap "Allow")
+     *   adb_offline       → ok: false / discon    (2s debounce — USB jitter)
+     */
+    observeEvent(event) {
+        const next = event.kind === "adb_online"
+            ? { ok: true }
+            : event.kind === "adb_unauthorized"
+                ? { ok: false, reason: "device_unauthorized" }
+                : { ok: false, reason: "device_disconnected" };
+        this.scheduleEmit(next);
+    }
+    /**
+     * Asymmetric trailing debounce.
+     *   - If `next` is unchanged from `lastEmitted`, no-op.
+     *   - Always cancel any pending timer (a new observation supersedes a
+     *     previously scheduled emit — this is what kills false alarms
+     *     during sub-2s jitter).
+     *   - Healthy: emit immediately (HEALTHY_DEBOUNCE_MS=0).
+     *   - Unhealthy: schedule emit after OFFLINE_DEBOUNCE_MS=2000.
+     */
+    scheduleEmit(next) {
+        if (this.disposed)
+            return;
+        this.currentObserved = next;
+        if (this.pendingTimer) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+        if (sameState(this.lastEmitted, next))
+            return;
+        const debounceMs = next.ok ? HEALTHY_DEBOUNCE_MS : OFFLINE_DEBOUNCE_MS;
+        if (debounceMs === 0) {
+            this.emitNow(next);
+            return;
+        }
+        this.pendingTimer = setTimeout(() => {
+            this.pendingTimer = null;
+            // Re-check `currentObserved` — by the time the timer fires the
+            // observed state may have flipped back. Always emit the latest
+            // truth, not the value captured when the timer was scheduled.
+            if (this.currentObserved && !sameState(this.lastEmitted, this.currentObserved)) {
+                this.emitNow(this.currentObserved);
+            }
+        }, debounceMs);
+    }
+    emitNow(next) {
+        this.lastEmitted = next;
+        this.logger.debug({ state: next }, "adb-track-devices: emitted change");
+        this.emit("change", next);
+    }
+}
+function sameState(a, b) {
+    if (!a)
+        return false;
+    if (a.ok !== b.ok)
+        return false;
+    if (!a.ok && !b.ok)
+        return a.reason === b.reason;
+    return true;
+}
+//# sourceMappingURL=adb-track-devices.js.map

package/dist/health/adb-track-devices.js.map

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

package/dist/health/health-reporter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * HealthReporter — bridges MCPHealthMonitor state changes onto the
+ * Bridge ACP transport as `device/health` notifications, and re-emits
+ * the last-known state on every transport reconnect.
+ *
+ * Why the reconnect re-emit?
+ *   The bridge-client SDK auto-reconnects on transport loss, but its
+ *   `send()` quietly drops messages while disconnected (`.catch(()
+ *   => undefined)` in the inbound notifier). Without a reconnect-time
+ *   replay, a transition that fires while the WebSocket is down is
+ *   lost forever — and the cluster's view of `connectivity_reason` is
+ *   stuck on the prior value. The "connected" event handler here
+ *   makes every reconnect an opportunity to re-sync server-side state.
+ *
+ * trace_id:
+ *   Every emission generates a fresh UUID. Logged here, propagated
+ *   verbatim by Bridge → BridgeHub → Cluster (via the new
+ *   `connectivity_reason` field carrying it through), and surfaced in
+ *   each hop's structured logs. On-call can grep one ID and see the
+ *   whole chain.
+ *
+ * Lifecycle:
+ *   `dispose()` removes both the monitor `change` listener and the
+ *   transport `connected` listener — the IBridgeTransport now exposes
+ *   `off()` precisely so this reporter can clean up symmetrically.
+ */
+import type { Logger } from "pino";
+import type { MCPHealthMonitor } from "./mcp-health-monitor.js";
+import type { IBridgeTransport } from "../ports/transport.js";
+export interface HealthReporterOptions {
+    monitor: MCPHealthMonitor;
+    transport: IBridgeTransport;
+    logger: Logger;
+    /** Override UUID generator for tests. */
+    generateTraceId?: () => string;
+}
+export declare class HealthReporter {
+    private readonly monitor;
+    private readonly transport;
+    private readonly logger;
+    private readonly generateTraceId;
+    private readonly onChange;
+    private readonly onConnected;
+    /** Last reported state. Null until the first `change` event fires. */
+    private last;
+    private disposed;
+    constructor(opts: HealthReporterOptions);
+    /**
+     * Edge-triggered emission: only sends when the new state differs from
+     * the last reported one. Suppresses redundant traffic from the
+     * underlying monitor's idempotent re-fires (the monitor itself does
+     * the same suppression, but the double-check here makes the reporter
+     * safe to drive from any other source as well).
+     */
+    private maybeReport;
+    /**
+     * Re-emit the last-known state after the bridge transport reconnects.
+     * No-op when no state has been observed yet (cold start before the
+     * first probe completes). When `last` is non-null, treats reconnect
+     * as a "deliver-once" opportunity regardless of whether the value
+     * has changed — the cluster might have lost the prior message.
+     */
+    private flushOnReconnect;
+    private send;
+    /** Tear down both subscriptions. Safe to call multiple times. */
+    dispose(): void;
+}

package/dist/health/health-reporter.js

@@ -0,0 +1,123 @@
+/**
+ * HealthReporter — bridges MCPHealthMonitor state changes onto the
+ * Bridge ACP transport as `device/health` notifications, and re-emits
+ * the last-known state on every transport reconnect.
+ *
+ * Why the reconnect re-emit?
+ *   The bridge-client SDK auto-reconnects on transport loss, but its
+ *   `send()` quietly drops messages while disconnected (`.catch(()
+ *   => undefined)` in the inbound notifier). Without a reconnect-time
+ *   replay, a transition that fires while the WebSocket is down is
+ *   lost forever — and the cluster's view of `connectivity_reason` is
+ *   stuck on the prior value. The "connected" event handler here
+ *   makes every reconnect an opportunity to re-sync server-side state.
+ *
+ * trace_id:
+ *   Every emission generates a fresh UUID. Logged here, propagated
+ *   verbatim by Bridge → BridgeHub → Cluster (via the new
+ *   `connectivity_reason` field carrying it through), and surfaced in
+ *   each hop's structured logs. On-call can grep one ID and see the
+ *   whole chain.
+ *
+ * Lifecycle:
+ *   `dispose()` removes both the monitor `change` listener and the
+ *   transport `connected` listener — the IBridgeTransport now exposes
+ *   `off()` precisely so this reporter can clean up symmetrically.
+ */
+import { randomUUID } from "node:crypto";
+export class HealthReporter {
+    monitor;
+    transport;
+    logger;
+    generateTraceId;
+    onChange;
+    onConnected;
+    /** Last reported state. Null until the first `change` event fires. */
+    last = null;
+    disposed = false;
+    constructor(opts) {
+        this.monitor = opts.monitor;
+        this.transport = opts.transport;
+        this.logger = opts.logger.child({ component: "health-reporter" });
+        this.generateTraceId = opts.generateTraceId ?? randomUUID;
+        this.onChange = (s) => this.maybeReport(s);
+        this.onConnected = () => this.flushOnReconnect();
+        this.monitor.on("change", this.onChange);
+        this.transport.on("connected", this.onConnected);
+    }
+    /**
+     * Edge-triggered emission: only sends when the new state differs from
+     * the last reported one. Suppresses redundant traffic from the
+     * underlying monitor's idempotent re-fires (the monitor itself does
+     * the same suppression, but the double-check here makes the reporter
+     * safe to drive from any other source as well).
+     */
+    maybeReport(s) {
+        if (this.disposed)
+            return;
+        if (this.last && equalState(this.last, s))
+            return;
+        this.last = s;
+        this.send(s, "edge");
+    }
+    /**
+     * Re-emit the last-known state after the bridge transport reconnects.
+     * No-op when no state has been observed yet (cold start before the
+     * first probe completes). When `last` is non-null, treats reconnect
+     * as a "deliver-once" opportunity regardless of whether the value
+     * has changed — the cluster might have lost the prior message.
+     */
+    flushOnReconnect() {
+        if (this.disposed)
+            return;
+        if (!this.last)
+            return;
+        this.send(this.last, "reconnect");
+    }
+    send(s, cause) {
+        const traceId = this.generateTraceId();
+        const params = s.healthy
+            ? { healthy: true, trace_id: traceId }
+            : { healthy: false, reason: s.reason, trace_id: traceId };
+        this.logger.info({
+            trace_id: traceId,
+            cause,
+            healthy: s.healthy,
+            reason: s.healthy ? undefined : s.reason,
+        }, "device health reported");
+        void this.transport
+            .send(JSON.stringify({
+            jsonrpc: "2.0",
+            method: "device/health",
+            params,
+        }))
+            .catch((err) => {
+            // Transport dropped the send (typically: disconnected). We
+            // intentionally do not retry inline — the next monitor edge or
+            // the next "connected" event will pick it up. Log at debug
+            // because this is the expected failure mode during reconnect
+            // windows, not an error to alert on.
+            this.logger.debug({
+                trace_id: traceId,
+                cause,
+                err: err instanceof Error ? err.message : String(err),
+            }, "device/health send rejected (will retry on next edge / reconnect)");
+        });
+    }
+    /** Tear down both subscriptions. Safe to call multiple times. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.monitor.off("change", this.onChange);
+        this.transport.off("connected", this.onConnected);
+    }
+}
+function equalState(a, b) {
+    if (a.healthy !== b.healthy)
+        return false;
+    if (!a.healthy && !b.healthy)
+        return a.reason === b.reason;
+    return true;
+}
+//# sourceMappingURL=health-reporter.js.map

package/dist/health/health-reporter.js.map

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

package/dist/health/index.d.ts

@@ -0,0 +1,6 @@
+export { MCPHealthMonitor } from "./mcp-health-monitor.js";
+export type { HealthState, MCPHealthMonitorOptions } from "./mcp-health-monitor.js";
+export { HealthReporter } from "./health-reporter.js";
+export type { HealthReporterOptions } from "./health-reporter.js";
+export { AdbTrackDevices } from "./adb-track-devices.js";
+export type { AdbTrackDevicesOptions, AdbHealthState } from "./adb-track-devices.js";

package/dist/health/index.js

@@ -0,0 +1,4 @@
+export { MCPHealthMonitor } from "./mcp-health-monitor.js";
+export { HealthReporter } from "./health-reporter.js";
+export { AdbTrackDevices } from "./adb-track-devices.js";
+//# sourceMappingURL=index.js.map

package/dist/health/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/health/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}