@nickname4th/pura-cli 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 ![pura social preview](assets/pura-social-preview.png)
 
-pura is a LAN Android device mirror for product and design teams. A central Hub shows all online Android devices, while each developer runs a local Agent that talks to their own USB-connected phone through ADB.
+pura is a LAN Android device mirror for product and design teams. A central Hub shows all online Android devices, while each developer runs a local Agent that talks to their own USB-connected phone through ADB. Agents keep outbound connections to the Hub, so the Hub can run inside Docker without reaching back into developer laptops.
 
 No login, no cloud, no public tunnel. It is meant for trusted office networks.
 
@@ -105,9 +105,11 @@ Each developer connects their local Agent to the Hub. Once connected, the Hub we
 pura-cli connect 192.168.100.128:8787 --name "Zhang San"
 ```
 
-The Agent listens on `8788` by default and continuously reports local ADB devices to the Hub. Use the web UI to publish, rename, unpublish, and manage devices.
+The Agent keeps an outbound control WebSocket to the Hub and continuously reports local ADB devices. Use the web UI to publish, rename, unpublish, and manage devices.
 
-If the Hub cannot reach the auto-detected Agent URL, specify it:
+The Agent still exposes `8788` locally for diagnostics and standalone mode, but the Hub no longer depends on reverse HTTP access to that port. In normal Hub deployments, you should not need `--public-url`.
+
+For diagnostics, you can still override the announced local URL:
 
 ```bash
 pura-cli connect 192.168.100.128:8787 --name "Zhang San" --public-url http://192.168.100.45:8788
@@ -158,6 +160,7 @@ pura-cli connect device --serial RFCY10DHQ3P --name "Samsung S25" --owner "Li Si
 
 - Hub maintains online Agents and devices, serves the web UI, and proxies video WebSocket/tap requests.
 - Agent runs on each developer machine and owns ADB, screen capture, tap execution, and device metadata.
+- Agent opens outbound control/video WebSockets to the Hub. The Hub does not need to call back into Agent LAN addresses, which makes Docker/NAT/firewall deployment much more reliable.
 - CLI commands:
   - `pura-cli hub`
   - `pura-cli connect <hub>`
@@ -177,6 +180,8 @@ Hub:
 - `DELETE /api/devices/:deviceId/publication`
 - `DELETE /api/sessions/:id`
 - `WS /ws/sessions/:id/video`
+- `WS /ws/agents/:agentId/control`
+- `WS /ws/agents/:agentId/sessions/:agentSessionId/video`
 
 Agent:
 
@@ -196,7 +201,7 @@ Agent:
 - `HUB_URL=http://<hub-ip>:8787`
 - `AGENT_ID`
 - `AGENT_NAME`
-- `PUBLIC_URL=http://<agent-ip>:8788`
+- `PUBLIC_URL=http://<agent-ip>:8788` optional diagnostic URL; Hub control does not depend on it
 - `ADB_PATH=adb`
 - `STREAM_SIZE` optional; unset uses native device resolution
 - `STREAM_BITRATE=8000000`
@@ -212,15 +217,15 @@ Release flow:
 
 1. Update `version` in `package.json`.
 2. Run `npm run check`, `npm run build`, and `npm pack --dry-run`.
-3. Push a tag like `v0.1.0`.
-4. GitHub Actions publishes `@nickname4th/pura-cli` to npm and `ghcr.io/liutianjie/pura` to GHCR.
+3. Publish manually with `npm publish --access public`, or push a tag like `v0.1.3` to use the release workflow.
+4. The Docker workflow publishes `ghcr.io/liutianjie/pura:main` from `main` and builds both `linux/amd64` and `linux/arm64`.
 
 The release workflow requires an `NPM_TOKEN` repository secret.
 
 ## Notes
 
 - The current video path uses Android `screenrecord` H.264 output. No Android app or root is required.
-- Mouse control currently supports tap only.
+- Mouse control supports tap, long press, scroll/swipe, system keys, text input, screenshots, and shared cursor annotations.
 - Do not expose Hub or Agent ports directly to the public internet.
 - Agent Docker is intentionally not the default because local USB/ADB access is much smoother with native `pura-cli`.
 - Some Android builds enforce `screenrecord` time limits; the Agent restarts the stream automatically when it exits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nickname4th/pura-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "LAN Android device mirroring hub and developer CLI for distributed teams.",
   "license": "MIT",
   "type": "module",

package/server/dist/adb.js

@@ -1,7 +1,10 @@
 import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-const ADB = process.env.ADB_PATH ?? "adb";
+const ADB = resolveAdbCommand();
 const INCLUDE_TCP_DEVICES = process.env.INCLUDE_TCP_DEVICES === "true";
 export function adbCommand(args) {
     return {
@@ -151,6 +154,18 @@ export async function getDisplaySize(serial) {
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
+function resolveAdbCommand() {
+    if (process.env.ADB_PATH)
+        return process.env.ADB_PATH;
+    const sdkRoot = process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT;
+    const candidates = [
+        sdkRoot ? path.join(sdkRoot, "platform-tools", "adb") : "",
+        path.join(os.homedir(), "Library", "Android", "sdk", "platform-tools", "adb"),
+        "/opt/homebrew/bin/adb",
+        "/usr/local/bin/adb"
+    ].filter(Boolean);
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? "adb";
+}
 const keyEvents = {
     back: "KEYCODE_BACK",
     home: "KEYCODE_HOME",

package/server/dist/agent.js

@@ -1,8 +1,10 @@
+import { WebSocket } from "ws";
 import { captureScreenshot, controlDevice, listDevices, longPressDevice, swipeDevice, tapDevice } from "./adb.js";
-import { getLanAddress, normalizeHttpUrl } from "./network.js";
+import { getLanAddress, httpToWs, normalizeHttpUrl } from "./network.js";
 import { getPublications, publishDevice, unpublishDevice } from "./registry.js";
 import { listDeviceScreenshots, saveScreenshot } from "./screenshots.js";
 import { deleteSession, getOrCreateSession, listSessions } from "./sessions.js";
+const activeVideoRelays = new Map();
 export function installAgentRoutes(app) {
     app.get("/api/devices", async (_req, res) => {
         try {
@@ -170,6 +172,183 @@ export function startAgentHeartbeat(options) {
     void tick();
     setInterval(tick, Number(process.env.HEARTBEAT_MS ?? 3000));
 }
+export function startAgentControlChannel(options) {
+    if (!options.hubUrl)
+        return;
+    const hubUrl = normalizeHttpUrl(options.hubUrl);
+    const controlUrl = `${httpToWs(hubUrl)}/ws/agents/${encodeURIComponent(options.agentId)}/control`;
+    let reconnectTimer;
+    const connect = () => {
+        const socket = new WebSocket(controlUrl);
+        socket.on("open", () => {
+            socket.send(JSON.stringify({
+                type: "hello",
+                agentId: options.agentId,
+                agentName: options.agentName
+            }));
+        });
+        socket.on("message", (data) => {
+            void handleControlMessage(socket, data.toString("utf8"), options);
+        });
+        socket.on("close", () => {
+            reconnectTimer = setTimeout(connect, Number(process.env.AGENT_RECONNECT_MS ?? 1500));
+        });
+        socket.on("error", (error) => {
+            console.error(`Hub control channel failed: ${error instanceof Error ? error.message : String(error)}`);
+            socket.close();
+        });
+    };
+    connect();
+    return () => {
+        if (reconnectTimer)
+            clearTimeout(reconnectTimer);
+    };
+}
+async function handleControlMessage(socket, text, options) {
+    let request;
+    try {
+        request = JSON.parse(text);
+    }
+    catch {
+        socket.close(1003, "invalid control message");
+        return;
+    }
+    if (request.type !== "request" || !request.requestId || !request.command)
+        return;
+    try {
+        const body = await runControlCommand(request, options);
+        sendControlResponse(socket, { type: "response", requestId: request.requestId, ok: true, body });
+    }
+    catch (error) {
+        sendControlResponse(socket, {
+            type: "response",
+            requestId: request.requestId,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+async function runControlCommand(request, options) {
+    const serial = request.serial;
+    const body = request.body ?? {};
+    switch (request.command) {
+        case "publish":
+            return {
+                publication: publishDevice(requireSerial(serial), {
+                    label: asString(body.label),
+                    owner: asString(body.owner),
+                    note: asString(body.note)
+                })
+            };
+        case "unpublish":
+            return { publication: unpublishDevice(requireSerial(serial)) };
+        case "start-session": {
+            const session = getOrCreateSession(requireSerial(serial), { restart: body.restart === true });
+            const hubSessionId = asString(body.hubSessionId);
+            if (!hubSessionId)
+                throw new Error("hubSessionId is required");
+            connectVideoRelay({
+                hubUrl: requireHubUrl(options.hubUrl),
+                agentId: options.agentId,
+                agentSessionId: session.id,
+                hubSessionId,
+                port: options.port
+            });
+            return { session };
+        }
+        case "delete-session":
+            return { deleted: deleteSession(requireString(body.sessionId, "sessionId")) };
+        case "screenshot": {
+            const image = await captureScreenshot(requireSerial(serial));
+            return { contentType: "image/png", data: image.toString("base64") };
+        }
+        case "tap":
+            return { tap: await tapDevice(requireSerial(serial), requireRatio(body.xRatio, "xRatio"), requireRatio(body.yRatio, "yRatio")) };
+        case "long-press":
+            return {
+                longPress: await longPressDevice(requireSerial(serial), requireRatio(body.xRatio, "xRatio"), requireRatio(body.yRatio, "yRatio"), asNumber(body.durationMs) ?? 650)
+            };
+        case "swipe":
+            return {
+                swipe: await swipeDevice(requireSerial(serial), {
+                    xStartRatio: requireRatio(body.xStartRatio, "xStartRatio"),
+                    yStartRatio: requireRatio(body.yStartRatio, "yStartRatio"),
+                    xEndRatio: requireRatio(body.xEndRatio, "xEndRatio"),
+                    yEndRatio: requireRatio(body.yEndRatio, "yEndRatio"),
+                    durationMs: asNumber(body.durationMs)
+                })
+            };
+        case "control": {
+            const action = asString(body.action);
+            if (!action || !controlActions.includes(action))
+                throw new Error("A supported control action is required");
+            return { control: await controlDevice(requireSerial(serial), action, asString(body.value)) };
+        }
+        default:
+            throw new Error(`Unsupported agent command: ${request.command}`);
+    }
+}
+function connectVideoRelay(options) {
+    activeVideoRelays.get(options.hubSessionId)?.hub.close();
+    activeVideoRelays.get(options.hubSessionId)?.local.close();
+    const hub = new WebSocket(`${httpToWs(options.hubUrl)}/ws/agents/${encodeURIComponent(options.agentId)}/sessions/${encodeURIComponent(options.agentSessionId)}/video?hubSessionId=${encodeURIComponent(options.hubSessionId)}`);
+    const local = new WebSocket(`ws://127.0.0.1:${options.port}/ws/sessions/${encodeURIComponent(options.agentSessionId)}/video`);
+    activeVideoRelays.set(options.hubSessionId, { hub, local });
+    local.on("message", (data, isBinary) => {
+        if (hub.readyState === WebSocket.OPEN) {
+            hub.send(data, { binary: isBinary });
+        }
+    });
+    const cleanup = () => {
+        const relay = activeVideoRelays.get(options.hubSessionId);
+        if (relay?.hub === hub && relay.local === local) {
+            activeVideoRelays.delete(options.hubSessionId);
+        }
+        if (hub.readyState === WebSocket.OPEN || hub.readyState === WebSocket.CONNECTING)
+            hub.close();
+        if (local.readyState === WebSocket.OPEN || local.readyState === WebSocket.CONNECTING)
+            local.close();
+    };
+    hub.on("close", cleanup);
+    local.on("close", cleanup);
+    hub.on("error", cleanup);
+    local.on("error", cleanup);
+}
+function sendControlResponse(socket, response) {
+    if (socket.readyState === WebSocket.OPEN) {
+        socket.send(JSON.stringify(response));
+    }
+}
+function requireHubUrl(value) {
+    if (!value)
+        throw new Error("Agent is missing HUB_URL");
+    return normalizeHttpUrl(value);
+}
+function requireSerial(value) {
+    if (!value)
+        throw new Error("serial is required");
+    return value;
+}
+function requireString(value, name) {
+    const text = asString(value);
+    if (!text)
+        throw new Error(`${name} is required`);
+    return text;
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function asNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+function requireRatio(value, name) {
+    const number = Number(value);
+    if (!Number.isFinite(number) || number < 0 || number > 1) {
+        throw new Error(`${name} must be a number between 0 and 1`);
+    }
+    return number;
+}
 async function listAgentDevices() {
     const publications = getPublications();
     return (await listDevices()).map((device) => ({

package/server/dist/cli.js

@@ -204,6 +204,16 @@ function printLaunchAgentStatus() {
     }
 }
 function makeLaunchAgentPlist(nodePath, cliPath) {
+    const environment = {
+        PATH: process.env.PATH,
+        ANDROID_HOME: process.env.ANDROID_HOME,
+        ANDROID_SDK_ROOT: process.env.ANDROID_SDK_ROOT,
+        ADB_PATH: findExecutable("adb")
+    };
+    const environmentEntries = Object.entries(environment)
+        .filter((entry) => Boolean(entry[1]))
+        .map(([key, value]) => `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`)
+        .join("\n");
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -220,6 +230,10 @@ function makeLaunchAgentPlist(nodePath, cliPath) {
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+${environmentEntries}
+  </dict>
   <key>StandardOutPath</key>
   <string>${escapeXml(path.join(os.homedir(), "Library", "Logs", "pura-agent.log"))}</string>
   <key>StandardErrorPath</key>
@@ -256,6 +270,16 @@ function resolveAgentDataDir(value) {
         return path.join(os.homedir(), ".pura", "agent-data");
     return path.isAbsolute(value) ? value : path.resolve(value);
 }
+function findExecutable(name) {
+    for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = path.join(directory, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
 function startServer(env) {
     const child = spawn(process.execPath, [new URL("./index.js", import.meta.url).pathname], {
         stdio: "inherit",

package/server/dist/hub.js

@@ -1,24 +1,27 @@
 import { randomUUID } from "node:crypto";
 import { WebSocket } from "ws";
 import { makeDeviceId, parseDeviceId } from "./device-id.js";
-import { httpToWs } from "./network.js";
 import { listDeviceScreenshots, saveScreenshot } from "./screenshots.js";
 const agents = new Map();
 const sessions = new Map();
+const pendingAgentRequests = new Map();
 const AGENT_TTL_MS = Number(process.env.AGENT_TTL_MS ?? 15_000);
+const AGENT_REQUEST_TIMEOUT_MS = Number(process.env.AGENT_REQUEST_TIMEOUT_MS ?? 30_000);
 export function installHubRoutes(app) {
     app.post("/api/agents/heartbeat", (req, res) => {
         const body = req.body;
-        if (!body.agentId || !body.url || !Array.isArray(body.devices)) {
-            res.status(400).json({ error: "agentId, url and devices are required" });
+        if (!body.agentId || !Array.isArray(body.devices)) {
+            res.status(400).json({ error: "agentId and devices are required" });
             return;
         }
+        const existing = agents.get(body.agentId);
         agents.set(body.agentId, {
             agentId: body.agentId,
             agentName: body.agentName,
-            url: body.url.replace(/\/$/, ""),
+            url: body.url?.replace(/\/$/, "") ?? existing?.url ?? "",
             devices: body.devices,
-            lastSeen: Date.now()
+            lastSeen: Date.now(),
+            control: existing?.control
         });
         res.json({ ok: true });
     });
@@ -28,12 +31,15 @@ export function installHubRoutes(app) {
     app.put("/api/devices/:deviceId/publication", async (req, res) => {
         try {
             const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/publication`, {
-                method: "PUT",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(req.body ?? {})
+            const body = await sendAgentRequest(target.agent, "publish", {
+                serial: target.remoteSerial,
+                body: req.body ?? {}
+            });
+            res.json({
+                publication: body.publication
+                    ? { ...body.publication, serial: req.params.deviceId }
+                    : body.publication
             });
-            res.status(response.status).json(await response.json());
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to publish device" });
@@ -42,10 +48,14 @@ export function installHubRoutes(app) {
     app.delete("/api/devices/:deviceId/publication", async (req, res) => {
         try {
             const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/publication`, {
-                method: "DELETE"
+            const body = await sendAgentRequest(target.agent, "unpublish", {
+                serial: target.remoteSerial
+            });
+            res.json({
+                publication: body.publication
+                    ? { ...body.publication, serial: req.params.deviceId }
+                    : body.publication
             });
-            res.status(response.status).json(await response.json());
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to unpublish device" });
@@ -58,24 +68,19 @@ export function installHubRoutes(app) {
             if (restart) {
                 await deleteHubSessionsForDevice(req.params.deviceId);
             }
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/session`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ restart })
+            const sessionId = randomUUID();
+            const body = await sendAgentRequest(target.agent, "start-session", {
+                serial: target.remoteSerial,
+                body: { restart, hubSessionId: sessionId }
             });
-            if (!response.ok) {
-                res.status(response.status).json(await response.json());
-                return;
-            }
-            const body = (await response.json());
             const session = {
-                id: randomUUID(),
+                id: sessionId,
                 deviceId: req.params.deviceId,
                 agentId: target.agent.agentId,
-                agentUrl: target.agent.url,
                 agentSessionId: body.session.id,
                 serial: target.remoteSerial,
-                startedAt: Date.now()
+                startedAt: Date.now(),
+                clients: new Set()
             };
             sessions.set(session.id, session);
             res.json({
@@ -92,16 +97,10 @@ export function installHubRoutes(app) {
     });
     app.get("/api/devices/:deviceId/screenshot", async (req, res) => {
         try {
-            const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/screenshot`);
-            if (!response.ok) {
-                res.status(response.status).json({ error: await response.text() });
-                return;
-            }
-            const image = Buffer.from(await response.arrayBuffer());
-            res.setHeader("Content-Type", response.headers.get("content-type") ?? "image/png");
+            const image = await captureRemoteScreenshot(req.params.deviceId);
+            res.setHeader("Content-Type", image.contentType);
             res.setHeader("Cache-Control", "no-store");
-            res.end(image);
+            res.end(image.buffer);
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to capture remote device screenshot" });
@@ -109,14 +108,8 @@ export function installHubRoutes(app) {
     });
     app.post("/api/devices/:deviceId/screenshots", async (req, res) => {
         try {
-            const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/screenshot`);
-            if (!response.ok) {
-                res.status(response.status).json({ error: await response.text() });
-                return;
-            }
-            const image = Buffer.from(await response.arrayBuffer());
-            res.json({ screenshot: await saveScreenshot(image, req.params.deviceId) });
+            const image = await captureRemoteScreenshot(req.params.deviceId);
+            res.json({ screenshot: await saveScreenshot(image.buffer, req.params.deviceId) });
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to save remote device screenshot" });
@@ -134,12 +127,7 @@ export function installHubRoutes(app) {
     app.post("/api/devices/:deviceId/tap", async (req, res) => {
         try {
             const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/tap`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(req.body ?? {})
-            });
-            res.status(response.status).json(await response.json());
+            res.json(await sendAgentRequest(target.agent, "tap", { serial: target.remoteSerial, body: req.body ?? {} }));
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to tap remote device" });
@@ -148,12 +136,7 @@ export function installHubRoutes(app) {
     app.post("/api/devices/:deviceId/long-press", async (req, res) => {
         try {
             const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/long-press`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(req.body ?? {})
-            });
-            res.status(response.status).json(await response.json());
+            res.json(await sendAgentRequest(target.agent, "long-press", { serial: target.remoteSerial, body: req.body ?? {} }));
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to long press remote device" });
@@ -162,12 +145,7 @@ export function installHubRoutes(app) {
     app.post("/api/devices/:deviceId/swipe", async (req, res) => {
         try {
             const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/swipe`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(req.body ?? {})
-            });
-            res.status(response.status).json(await response.json());
+            res.json(await sendAgentRequest(target.agent, "swipe", { serial: target.remoteSerial, body: req.body ?? {} }));
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to swipe remote device" });
@@ -176,12 +154,7 @@ export function installHubRoutes(app) {
     app.post("/api/devices/:deviceId/control", async (req, res) => {
         try {
             const target = findDevice(req.params.deviceId);
-            const response = await fetch(`${target.agent.url}/api/devices/${encodeURIComponent(target.remoteSerial)}/control`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(req.body ?? {})
-            });
-            res.status(response.status).json(await response.json());
+            res.json(await sendAgentRequest(target.agent, "control", { serial: target.remoteSerial, body: req.body ?? {} }));
         }
         catch (error) {
             res.status(502).json({ error: error instanceof Error ? error.message : "Failed to control remote device" });
@@ -194,20 +167,91 @@ export function installHubRoutes(app) {
             res.json({ deleted: false });
             return;
         }
-        await fetch(`${session.agentUrl}/api/sessions/${encodeURIComponent(session.agentSessionId)}`, {
-            method: "DELETE"
-        }).catch(() => undefined);
+        closeHubSession(session);
+        const agent = agents.get(session.agentId);
+        if (agent) {
+            await sendAgentRequest(agent, "delete-session", {
+                body: { sessionId: session.agentSessionId }
+            }).catch(() => undefined);
+        }
         res.json({ deleted: true });
     });
 }
-async function deleteHubSessionsForDevice(deviceId) {
-    const staleSessions = [...sessions.values()].filter((session) => session.deviceId === deviceId);
-    await Promise.all(staleSessions.map(async (session) => {
-        sessions.delete(session.id);
-        await fetch(`${session.agentUrl}/api/sessions/${encodeURIComponent(session.agentSessionId)}`, {
-            method: "DELETE"
-        }).catch(() => undefined);
-    }));
+export function attachAgentControlClient(agentId, socket) {
+    const existing = agents.get(agentId);
+    if (existing?.control && existing.control.readyState === WebSocket.OPEN) {
+        existing.control.close(1001, "replaced by a new control channel");
+    }
+    agents.set(agentId, {
+        agentId,
+        agentName: existing?.agentName,
+        url: existing?.url ?? "",
+        devices: existing?.devices ?? [],
+        lastSeen: Date.now(),
+        control: socket
+    });
+    socket.on("message", (data) => {
+        try {
+            const message = JSON.parse(data.toString("utf8"));
+            if (message.type === "hello") {
+                const agent = agents.get(agentId);
+                if (agent) {
+                    agent.agentName = message.agentName ?? agent.agentName;
+                    agent.lastSeen = Date.now();
+                }
+                return;
+            }
+            if (message.type !== "response")
+                return;
+            const pending = pendingAgentRequests.get(message.requestId);
+            if (!pending)
+                return;
+            pendingAgentRequests.delete(message.requestId);
+            clearTimeout(pending.timer);
+            if (message.ok) {
+                pending.resolve(message.body);
+            }
+            else {
+                pending.reject(new Error(message.error || "Agent request failed"));
+            }
+        }
+        catch {
+            socket.close(1003, "invalid control message");
+        }
+    });
+    socket.on("close", () => {
+        const agent = agents.get(agentId);
+        if (agent?.control === socket) {
+            agent.control = undefined;
+            agent.lastSeen = Date.now();
+        }
+    });
+}
+export function attachAgentVideoStream(agentId, agentSessionId, hubSessionId, stream) {
+    const session = sessions.get(hubSessionId);
+    if (!session || session.agentId !== agentId || session.agentSessionId !== agentSessionId) {
+        stream.close(1008, "session not found");
+        return;
+    }
+    if (session.stream && session.stream.readyState === WebSocket.OPEN) {
+        session.stream.close(1001, "replaced by a new stream");
+    }
+    session.stream = stream;
+    stream.on("message", (data, isBinary) => {
+        for (const client of session.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(data, { binary: isBinary });
+            }
+        }
+    });
+    stream.on("close", () => {
+        if (session.stream === stream) {
+            session.stream = undefined;
+            for (const client of session.clients) {
+                client.close(1001, "agent stream closed");
+            }
+        }
+    });
 }
 export function attachHubVideoClient(sessionId, client) {
     const session = sessions.get(sessionId);
@@ -215,22 +259,51 @@ export function attachHubVideoClient(sessionId, client) {
         client.close(1008, "session not found");
         return;
     }
-    const remote = new WebSocket(`${httpToWs(session.agentUrl)}/ws/sessions/${session.agentSessionId}/video`);
-    remote.on("message", (data, isBinary) => {
-        if (client.readyState === WebSocket.OPEN) {
-            client.send(data, { binary: isBinary });
+    session.clients.add(client);
+    const waitTimer = setTimeout(() => {
+        if (!session.stream || session.stream.readyState !== WebSocket.OPEN) {
+            client.close(1011, "agent stream unavailable");
         }
-    });
-    remote.on("error", () => {
-        client.close(1011, "remote stream error");
-    });
-    remote.on("close", () => {
-        client.close(1001, "remote stream closed");
-    });
+    }, 8000);
     client.on("close", () => {
-        remote.close();
+        clearTimeout(waitTimer);
+        session.clients.delete(client);
     });
 }
+async function captureRemoteScreenshot(deviceId) {
+    const target = findDevice(deviceId);
+    const screenshot = await sendAgentRequest(target.agent, "screenshot", {
+        serial: target.remoteSerial
+    });
+    if (!screenshot.data) {
+        throw new Error("Agent returned an empty screenshot");
+    }
+    return {
+        contentType: screenshot.contentType ?? "image/png",
+        buffer: Buffer.from(screenshot.data, "base64")
+    };
+}
+async function deleteHubSessionsForDevice(deviceId) {
+    const staleSessions = [...sessions.values()].filter((session) => session.deviceId === deviceId);
+    await Promise.all(staleSessions.map(async (session) => {
+        sessions.delete(session.id);
+        closeHubSession(session);
+        const agent = agents.get(session.agentId);
+        if (agent) {
+            await sendAgentRequest(agent, "delete-session", {
+                body: { sessionId: session.agentSessionId }
+            }).catch(() => undefined);
+        }
+    }));
+}
+function closeHubSession(session) {
+    if (session.stream && session.stream.readyState === WebSocket.OPEN) {
+        session.stream.close(1001, "session ended");
+    }
+    for (const client of session.clients) {
+        client.close(1001, "session ended");
+    }
+}
 function listHubDevices() {
     pruneAgents();
     return [...agents.values()].flatMap((agent) => agent.devices.map((device) => ({
@@ -240,6 +313,7 @@ function listHubDevices() {
         agentId: agent.agentId,
         agentName: agent.agentName,
         agentUrl: agent.url,
+        controlOnline: agent.control?.readyState === WebSocket.OPEN,
         publication: device.publication
             ? {
                 ...device.publication,
@@ -252,7 +326,7 @@ function listHubSessions() {
     return [...sessions.values()].map((session) => ({
         id: session.id,
         serial: session.deviceId,
-        viewerCount: 0,
+        viewerCount: session.clients.size,
         startedAt: session.startedAt,
         stream: {
             codec: "h264",
@@ -277,10 +351,40 @@ function findDevice(deviceId) {
         remoteSerial: parsed.serial
     };
 }
+function sendAgentRequest(agent, command, payload = {}) {
+    if (!agent.control || agent.control.readyState !== WebSocket.OPEN) {
+        throw new Error("Agent control channel is offline");
+    }
+    const requestId = randomUUID();
+    const message = {
+        type: "request",
+        requestId,
+        command,
+        ...payload
+    };
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pendingAgentRequests.delete(requestId);
+            reject(new Error(`Agent request timed out: ${command}`));
+        }, AGENT_REQUEST_TIMEOUT_MS);
+        pendingAgentRequests.set(requestId, {
+            resolve: (body) => resolve(body),
+            reject,
+            timer
+        });
+        agent.control?.send(JSON.stringify(message), (error) => {
+            if (!error)
+                return;
+            pendingAgentRequests.delete(requestId);
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 function pruneAgents() {
     const now = Date.now();
     for (const [agentId, agent] of agents.entries()) {
-        if (now - agent.lastSeen > AGENT_TTL_MS) {
+        if (now - agent.lastSeen > AGENT_TTL_MS && agent.control?.readyState !== WebSocket.OPEN) {
             agents.delete(agentId);
         }
     }

package/server/dist/index.js

@@ -2,8 +2,8 @@ import express from "express";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
-import { installAgentRoutes, startAgentHeartbeat } from "./agent.js";
-import { attachHubVideoClient, installHubRoutes } from "./hub.js";
+import { installAgentRoutes, startAgentControlChannel, startAgentHeartbeat } from "./agent.js";
+import { attachAgentControlClient, attachAgentVideoStream, attachHubVideoClient, installHubRoutes } from "./hub.js";
 import { getLanAddress } from "./network.js";
 import { attachPresenceClient } from "./presence.js";
 import { installScreenshotRoutes } from "./screenshots.js";
@@ -28,6 +28,7 @@ else {
     installAgentRoutes(app);
     if (role === "agent") {
         startAgentHeartbeat({ hubUrl, agentId, agentName, publicUrl, port });
+        startAgentControlChannel({ hubUrl, agentId, agentName, publicUrl, port });
     }
 }
 const __filename = fileURLToPath(import.meta.url);
@@ -49,7 +50,9 @@ server.on("upgrade", (request, socket, head) => {
     const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
     const videoMatch = url.pathname.match(/^\/ws\/sessions\/([^/]+)\/video$/);
     const presenceMatch = url.pathname.match(/^\/ws\/presence\/([^/]+)$/);
-    if (!videoMatch && !presenceMatch) {
+    const agentControlMatch = url.pathname.match(/^\/ws\/agents\/([^/]+)\/control$/);
+    const agentVideoMatch = url.pathname.match(/^\/ws\/agents\/([^/]+)\/sessions\/([^/]+)\/video$/);
+    if (!videoMatch && !presenceMatch && !agentControlMatch && !agentVideoMatch) {
         socket.destroy();
         return;
     }
@@ -57,11 +60,20 @@ server.on("upgrade", (request, socket, head) => {
         if (presenceMatch) {
             attachPresenceClient(decodeURIComponent(presenceMatch[1]), ws);
         }
-        else if (role === "hub") {
+        else if (role === "hub" && agentControlMatch) {
+            attachAgentControlClient(decodeURIComponent(agentControlMatch[1]), ws);
+        }
+        else if (role === "hub" && agentVideoMatch) {
+            attachAgentVideoStream(decodeURIComponent(agentVideoMatch[1]), decodeURIComponent(agentVideoMatch[2]), url.searchParams.get("hubSessionId") ?? "", ws);
+        }
+        else if (role === "hub" && videoMatch) {
             attachHubVideoClient(videoMatch[1], ws);
         }
-        else {
+        else if (videoMatch) {
             attachClient(videoMatch[1], ws);
         }
+        else {
+            ws.close(1008, "unsupported websocket route");
+        }
     });
 });