@beeos-ai/device-agent 0.4.0

package/dist/fleet/installer/spawn-env.js

@@ -0,0 +1,224 @@
+/**
+ * Fleet OS-service spawn-env derivation.
+ *
+ * Goal: make `device-agent fleet enable` produce a launchd plist whose
+ * `EnvironmentVariables` block has EVERYTHING the supervisor needs to
+ * spawn its mcp + daemon (+ optional scrcpy) children, without the user
+ * having to hand-edit the plist.
+ *
+ * Concretely, when we install the fleet plist we capture three pieces
+ * of state from the operator's current login shell:
+ *
+ *   1. **PATH** — the launchd `EnvironmentVariables` we inherit on a
+ *      fresh boot is minimal (`/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin`),
+ *      so spawned children can't resolve `adb`, `node`, our managed
+ *      `~/.beeos/bin/*` shims, or anything from the user's profile.
+ *      We snapshot `process.env.PATH` at install time so the supervisor
+ *      and ITS children see the same PATH the operator did when they
+ *      ran `device-agent fleet enable`.
+ *
+ *   2. **Binary overrides** — `NodeProcessManager` defaults to bare
+ *      names (`device-agent`, `device-mcp-server`, `scrcpy-bridge`)
+ *      and relies on PATH. To make the chain robust against PATH
+ *      drift we also seed `BEEOS_DEVICE_AGENT_BIN`,
+ *      `BEEOS_DEVICE_MCP_BIN`, and `BEEOS_SCRCPY_BRIDGE_BIN` with
+ *      absolute paths discovered now. Sibling-of-cliEntry is the
+ *      cheapest discovery (covers `~/.beeos/bin/` from
+ *      `install-local.sh` and `node_modules/.bin/` from npm
+ *      installs); `~/.beeos/bin/` and `which` are progressive
+ *      fallbacks.
+ *
+ *   3. **Platform URLs** — `AGENT_GATEWAY_URL` (and `BRIDGE_URL` when
+ *      present) are read from `~/.beeos/config.toml` so the daemons
+ *      the fleet spawns talk to the same backend the rest of BeeOS
+ *      CLI does. The operator can still override either one
+ *      explicitly via `--agent-gateway-url` on `fleet enable` or by
+ *      editing the plist after install.
+ *
+ * This module is intentionally pure: every external resource is
+ * abstracted behind an injected hook (`fileExists`, `which`,
+ * `readConfig`) so unit tests can drive every branch deterministically.
+ */
+import { execFile } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+/**
+ * The list of binaries the supervisor needs to spawn (mcp / daemon /
+ * scrcpy). Each entry maps to the env var the
+ * `NodeProcessManager` reads when an explicit override is required.
+ */
+const SUPERVISED_BINARIES = [
+    { envVar: "BEEOS_DEVICE_AGENT_BIN", bin: "device-agent", required: true },
+    { envVar: "BEEOS_DEVICE_MCP_BIN", bin: "device-mcp-server", required: true },
+    { envVar: "BEEOS_SCRCPY_BRIDGE_BIN", bin: "scrcpy-bridge", required: false },
+];
+/**
+ * Derive the env vars that should be threaded into the launchd
+ * `EnvironmentVariables` block for the fleet plist.
+ *
+ * Returns ONLY the keys that have a value — `installFleetLaunchd` will
+ * merge them with `BEEOS_HOME` (always) and `PATH` (defaulted to the
+ * minimal mac PATH if neither operator nor this function provides one).
+ */
+export async function deriveFleetSpawnEnv(opts) {
+    const env = {};
+    const warnings = [];
+    const fe = opts.fileExists ?? defaultFileExists;
+    const wh = opts.whichBin ?? defaultWhich;
+    const rc = opts.readConfigToml ?? defaultReadConfigToml;
+    const currentEnv = opts.currentEnv ?? process.env;
+    // 1. Snapshot the current shell's PATH so launchd-spawned children
+    // resolve `adb`, `node`, `~/.beeos/bin/*` etc. the same way the
+    // user's interactive shell does.
+    if (currentEnv.PATH && currentEnv.PATH.length > 0) {
+        env.PATH = currentEnv.PATH;
+    }
+    // 2. Resolve absolute paths for the supervised binaries.
+    const beeosHome = resolveBeeosHome(opts.beeosHome, currentEnv);
+    const cliDir = path.dirname(opts.cliEntry);
+    const managedDir = path.join(beeosHome, "bin");
+    for (const target of SUPERVISED_BINARIES) {
+        const found = await resolveBinary({
+            name: target.bin,
+            cliEntry: opts.cliEntry,
+            cliDir,
+            managedDir,
+            fileExists: fe,
+            whichBin: wh,
+        });
+        if (found) {
+            env[target.envVar] = found;
+        }
+        else if (target.required) {
+            warnings.push(`could not locate ${target.bin} (looked next to ${opts.cliEntry}, in ${managedDir}, and on PATH); ` +
+                `set ${target.envVar} explicitly or symlink ${target.bin} into ${managedDir} before the fleet spawns it.`);
+        }
+    }
+    // 3. Pull AGENT_GATEWAY_URL / BRIDGE_URL from ~/.beeos/config.toml
+    // so the fleet uses the same backend as the rest of `beeos *`.
+    const cfg = await rc(path.join(beeosHome, "config.toml"));
+    if (cfg?.agentGatewayUrl)
+        env.AGENT_GATEWAY_URL = cfg.agentGatewayUrl;
+    if (cfg?.bridgeUrl)
+        env.BRIDGE_URL = cfg.bridgeUrl;
+    // 4. Operator-supplied overrides win over everything we discovered.
+    // `undefined` values are treated as "unset"; empty strings are
+    // honoured (operator may want to clear a default).
+    if (opts.overrides) {
+        for (const [k, v] of Object.entries(opts.overrides)) {
+            if (v !== undefined)
+                env[k] = v;
+        }
+    }
+    return { env, warnings };
+}
+async function resolveBinary(args) {
+    const exeSuffix = process.platform === "win32" ? ".exe" : "";
+    const filename = `${args.name}${exeSuffix}`;
+    // 1. Sibling of cliEntry (covers `~/.beeos/bin/` from install-local.sh
+    // and `node_modules/.bin/` from npm consumers).
+    // Also short-circuit when the requested binary IS cliEntry itself
+    // (i.e. `device-agent`).
+    const baseCli = path.basename(args.cliEntry);
+    if (baseCli === args.name || baseCli === filename) {
+        if (await args.fileExists(args.cliEntry))
+            return args.cliEntry;
+    }
+    const siblingPlain = path.join(args.cliDir, args.name);
+    if (await args.fileExists(siblingPlain))
+        return siblingPlain;
+    if (filename !== args.name) {
+        const siblingExe = path.join(args.cliDir, filename);
+        if (await args.fileExists(siblingExe))
+            return siblingExe;
+    }
+    // 2. ~/.beeos/bin/<name> (cargo-dist + install-local.sh canonical install location).
+    const managed = path.join(args.managedDir, filename);
+    if (await args.fileExists(managed))
+        return managed;
+    // 3. PATH lookup (last resort — the launchd PATH may differ from
+    // the install-time PATH, so we still keep BEEOS_*_BIN as the
+    // canonical hint).
+    return args.whichBin(args.name);
+}
+async function defaultFileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultWhich(name) {
+    const cmd = process.platform === "win32" ? "where" : "which";
+    try {
+        const { stdout } = await execFileP(cmd, [name]);
+        const first = stdout.split(/\r?\n/).find((l) => l.trim().length > 0);
+        return first ? first.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Minimal `~/.beeos/config.toml` reader — only extracts the two keys
+ * we care about (`platform.agent_gateway_url`, `platform.bridge_url`).
+ *
+ * Keeping this inline avoids pulling `smol-toml` (or any other parser)
+ * into the device-agent runtime — `config.toml` is shaped exactly as
+ * the BeeOS CLI writes it: a single `[platform]` section with bare
+ * `key = "value"` lines. Comments and arrays are not supported here
+ * because they are not part of the file we own.
+ */
+export async function defaultReadConfigToml(cfgPath) {
+    let text;
+    try {
+        text = await fs.readFile(cfgPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    return parseConfigToml(text);
+}
+/**
+ * Pure parser exported for unit tests — operates on the file body text.
+ */
+export function parseConfigToml(text) {
+    const out = {};
+    let inPlatform = false;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const sect = line.match(/^\[([^\]]+)\]/);
+        if (sect) {
+            inPlatform = sect[1] === "platform";
+            continue;
+        }
+        if (!inPlatform)
+            continue;
+        const kv = line.match(/^([A-Za-z_][\w]*)\s*=\s*"([^"]*)"/);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        const value = kv[2];
+        if (key === "agent_gateway_url")
+            out.agentGatewayUrl = value;
+        else if (key === "bridge_url")
+            out.bridgeUrl = value;
+    }
+    return out;
+}
+function resolveBeeosHome(override, env) {
+    if (override && override.length > 0)
+        return override;
+    const fromEnv = env.BEEOS_HOME;
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return path.join(os.homedir(), ".beeos");
+}
+//# sourceMappingURL=spawn-env.js.map

package/dist/fleet/installer/spawn-env.js.map

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

package/dist/fleet/ports/clock.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Port — clock & timer abstraction.
+ *
+ * Centralising `Date.now()` and `setTimeout` behind this port lets unit tests
+ * for the supervisor advance time deterministically (`FakeClock`). Pure FSM
+ * tests don't need this — they pass `now` directly into `step()`.
+ */
+export type CancelFn = () => void;
+export interface IClock {
+    /** Monotonic-ish wall clock millis. */
+    now(): number;
+    /** Schedule `cb` to run after `ms`. Returns a cancel handle. */
+    schedule(ms: number, cb: () => void): CancelFn;
+}
+/** Default `IClock` backed by Node.js `Date.now()` + `setTimeout`. */
+export declare class SystemClock implements IClock {
+    now(): number;
+    schedule(ms: number, cb: () => void): CancelFn;
+}

package/dist/fleet/ports/clock.js

@@ -0,0 +1,26 @@
+/**
+ * Port — clock & timer abstraction.
+ *
+ * Centralising `Date.now()` and `setTimeout` behind this port lets unit tests
+ * for the supervisor advance time deterministically (`FakeClock`). Pure FSM
+ * tests don't need this — they pass `now` directly into `step()`.
+ */
+/** Default `IClock` backed by Node.js `Date.now()` + `setTimeout`. */
+export class SystemClock {
+    now() {
+        return Date.now();
+    }
+    schedule(ms, cb) {
+        const handle = setTimeout(cb, ms);
+        if (typeof handle === "object" && handle && "unref" in handle) {
+            try {
+                handle.unref();
+            }
+            catch {
+                /* node 20+ always supports unref */
+            }
+        }
+        return () => clearTimeout(handle);
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/fleet/ports/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../../src/fleet/ports/clock.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,sEAAsE;AACtE,MAAM,OAAO,WAAW;IACtB,GAAG;QACD,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IACD,QAAQ,CAAC,EAAU,EAAE,EAAc;QACjC,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAClC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;YAC9D,IAAI,CAAC;gBACF,MAAgC,CAAC,KAAK,EAAE,CAAC;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,oCAAoC;YACtC,CAAC;QACH,CAAC;QACD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/fleet/ports/device-source.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Port — device source.
+ *
+ * A `DeviceSource` is an event stream surfacing ADB-style device events.
+ * Implementations:
+ *   - `LocalAdbSource` (M2)  — `adb track-devices` long-running subprocess.
+ *   - `RemoteAdbSource` (M6) — static `host:port` list (e.g. ReDroid containers).
+ *
+ * Sources MUST emit:
+ *   1. An `adb_online` event for every serial currently attached at start
+ *      (initial sync), and
+ *   2. Subsequent online / offline / unauthorized transitions in real time.
+ *
+ * Sources MUST NOT spawn anything or touch the FSM directly. They are pure
+ * observation channels — the supervisor wires the events into FSM updates.
+ */
+import type { AdbEvent } from "../domain/events.js";
+export type AdbEventListener = (event: AdbEvent) => void;
+export interface IDeviceSource {
+    /** Begin emitting events. Must be idempotent. */
+    start(): Promise<void>;
+    /** Stop the underlying watcher and release resources. */
+    stop(): Promise<void>;
+    /** Subscribe; returns an unsubscribe function. */
+    on(listener: AdbEventListener): () => void;
+    /** Snapshot of currently-online serials (for `/fleet/devices` queries). */
+    snapshot(): readonly string[];
+}

package/dist/fleet/ports/device-source.js

@@ -0,0 +1,18 @@
+/**
+ * Port — device source.
+ *
+ * A `DeviceSource` is an event stream surfacing ADB-style device events.
+ * Implementations:
+ *   - `LocalAdbSource` (M2)  — `adb track-devices` long-running subprocess.
+ *   - `RemoteAdbSource` (M6) — static `host:port` list (e.g. ReDroid containers).
+ *
+ * Sources MUST emit:
+ *   1. An `adb_online` event for every serial currently attached at start
+ *      (initial sync), and
+ *   2. Subsequent online / offline / unauthorized transitions in real time.
+ *
+ * Sources MUST NOT spawn anything or touch the FSM directly. They are pure
+ * observation channels — the supervisor wires the events into FSM updates.
+ */
+export {};
+//# sourceMappingURL=device-source.js.map

package/dist/fleet/ports/device-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-source.js","sourceRoot":"","sources":["../../../src/fleet/ports/device-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/fleet/ports/process-manager.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Port — process manager.
+ *
+ * Owns the spawn/kill lifecycle of the per-device child processes:
+ *   - `device-mcp-server --backend android --adb-serial <serial> --port <p>`
+ *   - `device-agent` (no subcommand → daemon) `--adb <serial> --key <keyFile>`
+ *   - `scrcpy-bridge` (optional sibling for WebRTC video; supervised when
+ *     `video_mode === "scrcpy"`)
+ *
+ * The implementation lives in `fleet/adapters/process/`. The port is
+ * deliberately narrow so a fake can drive the FSM end-to-end in tests.
+ *
+ * Health & crash semantics:
+ *   - The implementation must emit `mcp_started` / `daemon_started` /
+ *     `scrcpy_started` once the child has cleared a basic readiness check
+ *     (TCP probe on `mcpUrl` / daemon HTTP `/healthz` / N-second startup
+ *     liveness for scrcpy-bridge which has no /healthz).
+ *   - `*_exited` events MUST set `expected = true` if and only if the
+ *     supervisor previously asked for a kill (so the FSM doesn't penalise
+ *     `restartCount`).
+ *   - `spawnScrcpy` is best-effort: when the binary cannot be found the
+ *     adapter logs and emits a `scrcpy_exited` with `reason` set, but never
+ *     blocks the rest of the device's spawn pipeline (video gracefully
+ *     degrades; mcp + daemon still come up).
+ */
+import type { ProcessEvent } from "../domain/events.js";
+export type ProcessEventListener = (event: ProcessEvent) => void;
+export interface SpawnOptions {
+    serial: string;
+    /** Allocated port for the mcp-server. */
+    mcpPort: number;
+    /** Path to the Ed25519 identity key file (daemon only). */
+    keyFile: string;
+    /** Agent Gateway URL (daemon only). Defaults via env. */
+    agentGatewayUrl?: string;
+    /** Daemon-side HTTP debug port (sticky from devices.json). */
+    daemonHttpPort?: number;
+    /** Optional binding name (for log decoration). */
+    name?: string;
+    /** Platform instance id (used for `--vlm-config-file` resolution and scrcpy-bridge `DEVICE_ID`). */
+    instanceId?: string;
+    /**
+     * Per-device `device-mcp-server --backend <name>` selection. When
+     * unset, `NodeProcessManager` falls back to its constructor-time
+     * default (`opts.mcpBackend` / `BEEOS_MCP_BACKEND` / `android`).
+     *
+     * In production this is read from `devices.json#backend` by the
+     * supervisor (`spawnOptionsFor`), which maps the canonical short
+     * name (`adb` / `macos` / `linux` / `windows` / `desktop` /
+     * `mock-desktop`) directly into `--backend`.
+     */
+    backend?: string;
+}
+/**
+ * Options for spawning `scrcpy-bridge`. Mirrors the env contract documented
+ * in `web/packages/core/src/runtime/scrcpy-bridge.ts` `buildEnv`. We
+ * intentionally re-declare the shape here instead of importing from
+ * `@beeos/core` so the device-agent package stays free of CLI deps.
+ */
+export interface SpawnScrcpyOptions {
+    serial: string;
+    /** Platform instance id used to compute scrcpy-bridge `DEVICE_ID` (`device-<instanceId>`). */
+    instanceId: string;
+    agentGatewayUrl: string;
+    /** Path to Ed25519 private key (raw base64 or `.key.json`). */
+    bridgePrivateKeyFile: string;
+    /** Path to Ed25519 public key (may equal private when using `.key.json`). */
+    bridgePublicKeyFile: string;
+    /** Optional video/ICE/TURN tuning. */
+    videoBitrateKbps?: number;
+    maxFps?: number;
+    iceUrls?: string[];
+    turnUrls?: string[];
+    turnUsername?: string;
+    turnCredential?: string;
+    /** Extra `KEY=VAL` pairs merged into the spawned process env. */
+    extraEnv?: Record<string, string>;
+}
+export type ManagedProcess = "mcp" | "daemon" | "scrcpy";
+export interface IProcessManager {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Spawn the device-mcp-server child for a given serial. */
+    spawnMcp(opts: SpawnOptions): Promise<void>;
+    /** Spawn the device-agent daemon child for a given serial. */
+    spawnDaemon(opts: SpawnOptions): Promise<void>;
+    /**
+     * Spawn the optional scrcpy-bridge sibling for a given serial. Best-effort:
+     * a missing binary yields a `scrcpy_exited` with `reason` rather than a
+     * thrown error.
+     */
+    spawnScrcpy(opts: SpawnScrcpyOptions): Promise<void>;
+    /** Stop the mcp child (SIGTERM, then SIGKILL after grace). */
+    killMcp(serial: string, opts?: {
+        expected?: boolean;
+    }): Promise<void>;
+    /** Stop the daemon child. */
+    killDaemon(serial: string, opts?: {
+        expected?: boolean;
+    }): Promise<void>;
+    /** Stop the scrcpy-bridge child (idempotent — no-op if not running). */
+    killScrcpy(serial: string, opts?: {
+        expected?: boolean;
+    }): Promise<void>;
+    /** Whether the requested child is currently alive (best-effort, observation only). */
+    isAlive(serial: string, which: ManagedProcess): boolean;
+    /** Best-effort PID introspection. */
+    pid(serial: string, which: ManagedProcess): number | null;
+    on(listener: ProcessEventListener): () => void;
+}

package/dist/fleet/ports/process-manager.js

@@ -0,0 +1,27 @@
+/**
+ * Port — process manager.
+ *
+ * Owns the spawn/kill lifecycle of the per-device child processes:
+ *   - `device-mcp-server --backend android --adb-serial <serial> --port <p>`
+ *   - `device-agent` (no subcommand → daemon) `--adb <serial> --key <keyFile>`
+ *   - `scrcpy-bridge` (optional sibling for WebRTC video; supervised when
+ *     `video_mode === "scrcpy"`)
+ *
+ * The implementation lives in `fleet/adapters/process/`. The port is
+ * deliberately narrow so a fake can drive the FSM end-to-end in tests.
+ *
+ * Health & crash semantics:
+ *   - The implementation must emit `mcp_started` / `daemon_started` /
+ *     `scrcpy_started` once the child has cleared a basic readiness check
+ *     (TCP probe on `mcpUrl` / daemon HTTP `/healthz` / N-second startup
+ *     liveness for scrcpy-bridge which has no /healthz).
+ *   - `*_exited` events MUST set `expected = true` if and only if the
+ *     supervisor previously asked for a kill (so the FSM doesn't penalise
+ *     `restartCount`).
+ *   - `spawnScrcpy` is best-effort: when the binary cannot be found the
+ *     adapter logs and emits a `scrcpy_exited` with `reason` set, but never
+ *     blocks the rest of the device's spawn pipeline (video gracefully
+ *     degrades; mcp + daemon still come up).
+ */
+export {};
+//# sourceMappingURL=process-manager.js.map

package/dist/fleet/ports/process-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.js","sourceRoot":"","sources":["../../../src/fleet/ports/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/fleet/ports/state-registry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Port — binding state registry.
+ *
+ * Adapter contract for reading per-device bindings from `~/.beeos/devices.json`
+ * (the file owned by `web/packages/cli` `attach` / `detach`). Fleet treats
+ * the file as read-only; the CLI is the writer. The store also exposes a
+ * watcher so fleet can react when a user runs `beeos device attach` mid-flight.
+ *
+ * Implementation: `fleet/adapters/state/beeos-cli-store.ts`.
+ */
+import type { DeviceBinding } from "../domain/device.js";
+import type { BindingEvent } from "../domain/events.js";
+export type BindingEventListener = (event: BindingEvent) => void;
+export interface IStateRegistry {
+    /** Begin watching the underlying file (idempotent). */
+    start(): Promise<void>;
+    /** Stop watching and release resources. */
+    stop(): Promise<void>;
+    /** Force-reload the file and emit diff events. */
+    reload(): Promise<void>;
+    /** Snapshot of all bindings currently visible. */
+    list(): readonly DeviceBinding[];
+    /** Lookup by ADB serial. */
+    get(serial: string): DeviceBinding | null;
+    on(listener: BindingEventListener): () => void;
+}
+/**
+ * Port — port allocator (sticky).
+ *
+ * Allocates one mcp-server port per serial. Allocations are persisted to
+ * `~/.beeos/fleet.json` so the same serial always lands on the same port
+ * across restarts (URLs in user UI stay stable). On collision with another
+ * already-running process, the allocator probes the next free port within a
+ * configurable range.
+ *
+ * Implementation: `fleet/adapters/state/port-allocator.ts`.
+ */
+export interface IPortAllocator {
+    /** Lazy-initialise: load persisted file if any. */
+    start(): Promise<void>;
+    /** Persist + close the underlying file. */
+    stop(): Promise<void>;
+    /** Get the (existing or freshly-allocated) port for a serial. */
+    acquire(serial: string): Promise<number>;
+    /** Free the slot — does not delete the persisted entry (kept sticky). */
+    release(serial: string): Promise<void>;
+    /** Read-only snapshot for `/fleet/devices`. */
+    snapshot(): ReadonlyMap<string, number>;
+}

package/dist/fleet/ports/state-registry.js

@@ -0,0 +1,12 @@
+/**
+ * Port — binding state registry.
+ *
+ * Adapter contract for reading per-device bindings from `~/.beeos/devices.json`
+ * (the file owned by `web/packages/cli` `attach` / `detach`). Fleet treats
+ * the file as read-only; the CLI is the writer. The store also exposes a
+ * watcher so fleet can react when a user runs `beeos device attach` mid-flight.
+ *
+ * Implementation: `fleet/adapters/state/beeos-cli-store.ts`.
+ */
+export {};
+//# sourceMappingURL=state-registry.js.map

package/dist/fleet/ports/state-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-registry.js","sourceRoot":"","sources":["../../../src/fleet/ports/state-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/fleet/supervisor.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Fleet supervisor — orchestrator that translates the pure FSM (`domain/fsm.ts`)
+ * effects into real side effects against the adapter ports.
+ *
+ * Responsibilities:
+ *
+ *   1. Wire `IDeviceSource` (ADB events), `IStateRegistry` (devices.json),
+ *      `IProcessManager` (mcp + daemon spawn/kill) and `IClock` (timers).
+ *   2. Maintain one `DeviceRecord` per serial discovered from EITHER source
+ *      (a device with a binding but no ADB → `adb_offline`; a device with
+ *      ADB but no binding → `awaiting_bind`).
+ *   3. For every event, call `step()` to compute `(record', effects)` and
+ *      enact each effect (spawn / kill / timer / port allocation / log).
+ *   4. Track `mcpAlive` / `daemonAlive` outside the FSM and call
+ *      `markHealthy()` when both are observed in `spawning`.
+ *   5. Expose a read-only `snapshot()` for the HTTP `/fleet/devices` endpoint
+ *      in M4.
+ *
+ * Concurrency model: single async serializer. All inbound events queue through
+ * `dispatch()` which pulls one at a time. This guarantees a coherent view of
+ * the FSM during multi-effect transitions and removes any need for locks.
+ */
+import type { DeviceSnapshot } from "./domain/device.js";
+import type { IClock } from "./ports/clock.js";
+import type { IDeviceSource } from "./ports/device-source.js";
+import type { IProcessManager } from "./ports/process-manager.js";
+import type { IPortAllocator, IStateRegistry } from "./ports/state-registry.js";
+export interface SupervisorLogger {
+    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;
+}
+export interface FleetSupervisorOptions {
+    source: IDeviceSource;
+    registry: IStateRegistry;
+    allocator: IPortAllocator;
+    processManager: IProcessManager;
+    clock?: IClock;
+    /** HEALTHY → DEGRADED window (default 5 s). */
+    graceMs?: number;
+    /** DEGRADED → GONE window (default 5 min). */
+    keepMs?: number;
+    logger?: SupervisorLogger;
+    /** Daemon-side metadata pulled from `devices.json` (overrides). */
+    defaultAgentGatewayUrl?: string;
+}
+export declare class FleetSupervisor {
+    private readonly source;
+    private readonly registry;
+    private readonly allocator;
+    private readonly processManager;
+    private readonly clock;
+    private readonly graceMs;
+    private readonly keepMs;
+    private readonly logger;
+    private readonly defaultAgentGatewayUrl?;
+    private readonly slots;
+    private readonly queue;
+    private dispatching;
+    private started;
+    private unsubAdb;
+    private unsubBinding;
+    private unsubProcess;
+    constructor(opts: FleetSupervisorOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Read-only snapshot for `/fleet/devices`. */
+    snapshot(): DeviceSnapshot[];
+    /**
+     * Force the registry to re-read `devices.json` (e.g. after `beeos device
+     * attach` finished). Returns once the diff has been queued; the per-slot
+     * effects fire asynchronously.
+     */
+    reload(): Promise<void>;
+    /**
+     * User-initiated full restart of one device's mcp + daemon pair.
+     *
+     * Flow: kill both children → reset slot to `adb_offline` (cancels timers,
+     * releases port, clears restartCount) → if ADB is currently online and
+     * the device is still bound, synthesise an `adb_online` event so the FSM
+     * walks the normal spawn path. The result mirrors what would happen if
+     * the user yanked the cable and plugged it back in immediately, except
+     * that grace/keep windows are skipped.
+     *
+     * Returns `false` if `serial` is unknown, `true` otherwise.
+     */
+    restartDevice(serial: string): Promise<boolean>;
+    private enqueue;
+    private drain;
+    private dispatch;
+    private bindingFor;
+    private ensureSlot;
+    private applyEffect;
+    private spawnOptionsFor;
+    /**
+     * Build `SpawnScrcpyOptions` for a slot, returning `null` when scrcpy is
+     * not requested (`videoMode !== "scrcpy"`) or the binding lacks the
+     * mandatory fields (`instanceId` / `keyFile` / Agent Gateway URL).
+     *
+     * We deliberately pass `bridgePrivateKeyFile === bridgePublicKeyFile`
+     * (both pointing at the same `.key.json` file written by `beeos device
+     * attach`). The Rust side accepts that layout (see scrcpy-bridge's
+     * `bootstrap/mod.rs`).
+     */
+    private scrcpySpawnOptionsFor;
+}