@beeos-ai/device-agent 0.9.3 → 0.9.5

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

@@ -1,23 +1,54 @@
 /**
  * Adapter — `IProcessManager` implementation backed by `child_process.spawn`.
  *
- * Spawns and supervises up to three long-running siblings per bound device:
+ * 0.4.0 SINGLETON MCP TOPOLOGY:
  *
- *   - **mcp**    `device-mcp-server --backend <kind> --adb-serial <serial>
- *                 --host 127.0.0.1 --port <mcpPort>`
+ * Pre-0.4 the manager spawned **one mcp + one daemon per device** (1:1) so
+ * the daemon could pin its `--mcp-url` to a per-device port. With the new
+ * SDK-backed device-mcp-server (which is itself a singleton multi-device
+ * BackendRegistry process), the manager keeps the per-device `IProcessManager`
+ * API the FSM/supervisor expect but internally collapses every `spawnMcp`
+ * call onto a **single shared MCP child**:
+ *
+ *   - The first `spawnMcp` call actually starts `device-mcp-server` on the
+ *     supplied port, runs the `initialize` JSON-RPC readiness handshake,
+ *     and remembers that port as the global MCP port.
+ *   - Subsequent `spawnMcp` calls (for additional devices) skip the spawn,
+ *     immediately emit a synthetic per-device `mcp_started` for the
+ *     existing global port, and add the serial to a refcount set.
+ *   - `killMcp(serial)` removes the serial from the refcount; the actual
+ *     `device-mcp-server` child is only killed when the last device drops
+ *     out (or `stop()` is called).
+ *   - When the global MCP exits unexpectedly, every refcounted serial
+ *     receives a synthetic `mcp_exited` so each per-device FSM transitions
+ *     coherently and triggers a respawn (whose first call rebuilds the
+ *     singleton).
+ *
+ * The daemon's `--mcp-url` always points at the global port (recorded in
+ * `globalMcpPort`), so per-device daemons all share the same backend
+ * registry. Tool calls route by the `device` argument the daemon's
+ * `McpClient` injects from its `defaultDevice = serial`. The MCP server's
+ * own `--adb-serial` per-device pin flag is gone; the registry discovers
+ * every connected device on its own.
+ *
+ * Spawn surface:
+ *
+ *   - **mcp**    `device-mcp-server --backend <kind>
+ *                 --host 127.0.0.1 --port <globalMcpPort>` (singleton)
  *   - **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"`.
+ *                 --mcp-url http://127.0.0.1:<globalMcpPort>
+ *                 --device <serial> [--adb <serial> for ADB backends]
+ *                 [--http --http-port <httpPort>]`  (per device)
+ *   - **scrcpy** `scrcpy-bridge` (no args; per device, 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).
+ *   - `spawnMcp` (first call) waits for the MCP `initialize` handshake to
+ *     return 200/202 before emitting `mcp_started`. If readiness times out
+ *     the global child is killed and a synthetic `mcp_exited` is reported
+ *     so the FSM treats the attempt as a crash. Subsequent (refcount-bump)
+ *     calls emit `mcp_started` synchronously without re-probing.
  *   - `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
@@ -83,7 +114,11 @@ export interface NodeProcessManagerOptions {
     bridgeUrl?: string;
     /** Optional region passed to daemon. */
     region?: string;
-    /** Initial readiness probe timeout for mcp `/healthz`. */
+    /**
+     * Initial readiness probe timeout for the singleton mcp server. 0.4
+     * replaced the bespoke `GET /healthz` with a real MCP `initialize`
+     * JSON-RPC handshake on `POST /mcp` — see `defaultHttpProbeFn`.
+     */
     mcpHealthTimeoutMs?: number;
     /**
      * Window we wait for scrcpy-bridge to keep running before declaring it
@@ -130,6 +165,41 @@ export declare class NodeProcessManager implements IProcessManager {
     private readonly slots;
     private readonly listeners;
     private started;
+    /**
+     * The lone `device-mcp-server` child shared across all devices, or
+     * `undefined` when no device currently needs the MCP. First `spawnMcp`
+     * call spawns it; the last `killMcp` (or `stop()`) tears it down.
+     */
+    private globalMcpSlot?;
+    /** Port the singleton is bound to. 0 when not running. */
+    private globalMcpPort;
+    /**
+     * Port the most recent successfully-probed singleton was bound to.
+     * Survives `globalMcpPort` being reset to 0 on exit; consulted by
+     * the next `startGlobalMcp` to detect port drift across respawn.
+     * 0 means "no prior cycle has succeeded" (suppresses the false-
+     * positive `mcp_port_changed` on the very first spawn).
+     */
+    private previousGlobalMcpPort;
+    /** Serials currently refcounting the global MCP. */
+    private readonly mcpRefs;
+    /**
+     * Single-flight readiness: when two devices land on `spawnMcp` at the
+     * same time we want only one of them to actually probe `initialize`;
+     * the other just awaits this promise.
+     */
+    private mcpReadyPromise?;
+    /**
+     * Single-flight first-spawn: protects the
+     * (`globalMcpSlot === undefined` → `spawnFn` → `globalMcpSlot = …`)
+     * critical section. Without this, two concurrent first-time
+     * `spawnMcp(A)` / `spawnMcp(B)` calls could each call `spawnFn`
+     * (the `globalMcpSlot` write is post-spawn, so the second caller
+     * sees `undefined` and overwrites with its own child, leaking
+     * the first one). When non-undefined, every other caller waits
+     * here instead of starting a second mcp.
+     */
+    private globalMcpStartPromise?;
     constructor(opts?: NodeProcessManagerOptions);
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -139,6 +209,38 @@ export declare class NodeProcessManager implements IProcessManager {
     private slotFor;
     private setSlot;
     spawnMcp(opts: SpawnOptions): Promise<void>;
+    /**
+     * Spawn the singleton `device-mcp-server`. Driven by the FIRST device
+     * to enter the spawn pipeline — its `opts.mcpPort` becomes the global
+     * port, and its `opts.backend` (or the constructor default) selects
+     * the backend kind. On readiness failure, emits a synthetic per-device
+     * `mcp_exited` for `opts.serial` so the caller's FSM transitions
+     * cleanly; on success leaves `globalMcpSlot` populated for refcount
+     * attachment.
+     */
+    private startGlobalMcp;
+    /**
+     * Wire `serial` into the running global MCP: store a ref-pointing
+     * `ChildSlot` on the device's slots, register the ref, and emit a
+     * per-device `mcp_started` event using the global port. Idempotent —
+     * a serial already in `mcpRefs` becomes a no-op.
+     */
+    private attachToGlobalMcp;
+    /**
+     * Attach a single global exit listener to the singleton MCP child. When
+     * it dies, fan-out a synthetic `mcp_exited` to every refcounted serial
+     * (clearing their slots) so each per-device FSM transitions cleanly.
+     * The `expected` flag is taken from `globalMcpSlot.expectingKill`, which
+     * is set by `killGlobalMcp(expected=true)` during graceful shutdown.
+     */
+    private attachGlobalExitListener;
+    /**
+     * Tear down the singleton MCP child unconditionally. `expected=true`
+     * marks the upcoming exit so FSMs don't penalise restartCount; the
+     * actual `*_exited` events are emitted by the global exit listener.
+     * A no-op when the singleton is already gone.
+     */
+    private killGlobalMcp;
     spawnDaemon(opts: SpawnOptions): Promise<void>;
     spawnScrcpy(opts: SpawnScrcpyOptions): Promise<void>;
     killMcp(serial: string, opts?: {