@livedesk/hub 0.1.42 → 0.1.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",
@@ -11,7 +11,7 @@
   "scripts": {
     "dev": "node src/server.js",
     "start": "node src/server.js",
-    "check": "node --check src/server.js && node --check src/remote-hub.js",
+    "check": "node --check src/server.js && node --check src/remote-hub.js && node --check src/console-relay.js",
     "prepublishOnly": "node ../../scripts/livedesk-release-git-gate.mjs"
   },
   "dependencies": {

package/src/agents/agent-result-enrichment.js

@@ -0,0 +1,66 @@
+const DEFAULT_MAX_STATUS_AGE_MS = 30_000;
+
+function asRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function cpuUsageRatio(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1
+    ? value
+    : null;
+}
+
+function positiveInteger(value) {
+  const number = Number(value);
+  return Number.isSafeInteger(number) && number > 0 ? number : null;
+}
+
+function statusAgeMs(device, now) {
+  const sampledAt = Date.parse(String(device?.lastStatusAt || ''));
+  return Number.isFinite(sampledAt) ? Math.max(0, now - sampledAt) : null;
+}
+
+export function enrichAgentTaskResults({
+  operation,
+  results,
+  devices,
+  now = Date.now(),
+  maxStatusAgeMs = DEFAULT_MAX_STATUS_AGE_MS
+} = {}) {
+  const sourceResults = Array.isArray(results) ? results : [];
+  if (operation !== 'system.health') return sourceResults;
+
+  const devicesById = new Map(
+    (Array.isArray(devices) ? devices : []).map(device => [String(device?.deviceId || ''), device])
+  );
+
+  return sourceResults.map(result => {
+    if (!result || result.status !== 'completed') return result;
+    const data = asRecord(result.data);
+    const device = devicesById.get(String(result.deviceId || ''));
+    const status = asRecord(device?.status);
+    const statusCpu = asRecord(status.cpu);
+    const directRatio = cpuUsageRatio(data.cpuUsageRatio);
+    const latestRatio = cpuUsageRatio(statusCpu.usageRatio);
+    const latestAgeMs = statusAgeMs(device, now);
+    const useLatestStatus = directRatio === null
+      && latestRatio !== null
+      && latestAgeMs !== null
+      && latestAgeMs <= Math.max(0, Number(maxStatusAgeMs) || DEFAULT_MAX_STATUS_AGE_MS);
+    const cores = positiveInteger(data.cores) || positiveInteger(statusCpu.cores);
+    const nextData = { ...data };
+
+    if (cores !== null) nextData.cores = cores;
+    if (directRatio !== null) {
+      nextData.cpuUsageRatio = directRatio;
+      nextData.cpuUsageSource = 'system-health-task';
+    } else if (useLatestStatus) {
+      nextData.cpuUsageRatio = latestRatio;
+      nextData.cpuUsageSource = 'latest-client-status';
+      nextData.cpuUsageSampleAgeMs = latestAgeMs;
+      nextData.cpuUsageSampledAt = String(device.lastStatusAt);
+    }
+
+    return { ...result, data: nextData };
+  });
+}

package/src/agents/codex-agent-runtime.js

@@ -728,8 +728,10 @@ export function createCodexAgentRuntime({
       'Never use arbitrary MCP servers, change permissions, forge approvals, request credentials, or invent a tool result.',
       `The Hub has fixed this run to permission mode ${permissionPolicy?.mode || 'ask'} and enforces the policy independently of your instructions.`,
       'Use only the selected connected device IDs below. If the Hub asks for user approval, wait for that approval result and do not work around it.',
-      'You may perform multiple safe read-only checks when the request requires a sequence. For example, find Clients missing a named process, then check a related service only on those Clients.',
-      `Selected device IDs: ${JSON.stringify(deviceIds)}`,
+      'You may perform multiple safe read-only checks when the request requires a sequence. For example, find Clients missing a named process, then check a related service only on those Clients.',
+      'If one read-only result omits a fact the user requested, do not treat that missing field as proof that the fact is unavailable. Try another applicable registered LiveDesk read-only tool.',
+      'If only a high-risk registered tool such as livedesk.run_command can obtain the missing fact, use it only when necessary, one selected device per call, and let the Hub approval policy ask the user. If approval is denied or no applicable tool exists, explain that exact limit.',
+      `Selected device IDs: ${JSON.stringify(deviceIds)}`,
       'Return a concise Korean or English summary grounded only in tool results. Do not invent results.',
       `User request: ${safeText(instruction, 4000)}`
     ].join('\n');

package/src/console-relay.js

@@ -0,0 +1,415 @@
+import WebSocket from 'ws';
+
+const DEFAULT_CONSOLE_RELAY_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
+const DEFAULT_RETRY_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 20_000];
+const MAX_CHANNELS = 32;
+const MAX_HTTP_REQUEST_BYTES = 1024 * 1024;
+const MAX_HTTP_RESPONSE_BYTES = 4 * 1024 * 1024;
+const MAX_RELAY_BUFFERED_BYTES = 4 * 1024 * 1024;
+const HTTP_TIMEOUT_MS = 15_000;
+const BINARY_HEADER_BYTES = 73;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function normalizeRelayUrl(value) {
+  const source = String(value || DEFAULT_CONSOLE_RELAY_URL).trim();
+  if (!source || /^(off|disabled|none)$/i.test(source)) return '';
+  try {
+    const url = new URL(source);
+    url.protocol = url.protocol === 'http:' ? 'ws:' : url.protocol === 'https:' ? 'wss:' : url.protocol;
+    url.pathname = '/v1/hub';
+    url.search = '';
+    url.hash = '';
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function allowedHttpRequest(method, path) {
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return false;
+  const pathname = String(path || '').split('?')[0];
+  if (pathname === '/api/health'
+    || pathname === '/api/runtime/status'
+    || pathname === '/api/runtime/restart'
+    || pathname === '/api/auth/status'
+    || pathname === '/api/remote/status'
+    || pathname === '/api/hub/status'
+    || pathname === '/api/update/status'
+    || pathname === '/api/update/apply') {
+    return true;
+  }
+  if (/^\/api\/settings(?:\/|$)/.test(pathname)
+    || /^\/api\/captures(?:\/|$)/.test(pathname)
+    || /^\/api\/capture-sessions(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/devices(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/frames$/.test(pathname)
+    || /^\/api\/remote\/filesystem(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/files(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/tasks(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/license(?:\/sync)?$/.test(pathname)) {
+    return pathname !== '/api/remote/registry-credentials'
+      && pathname !== '/api/remote/pairing-pin'
+      && !pathname.startsWith('/api/remote/host-target')
+      && !pathname.startsWith('/api/remote/synthetic');
+  }
+  return false;
+}
+
+function allowedWebSocketPath(path) {
+  const pathname = String(path || '').split('?')[0];
+  return pathname === '/api/remote/frames/ws'
+    || pathname === '/api/remote/atlas/ws'
+    || pathname === '/api/remote/input/ws'
+    || pathname === '/api/remote/audio/ws';
+}
+
+function channelKey(consoleId, channelId) {
+  return `${consoleId}\n${channelId}`;
+}
+
+function parseMessage(raw) {
+  try {
+    return JSON.parse(String(raw || ''));
+  } catch {
+    return null;
+  }
+}
+
+function safeContentHeaders(headers) {
+  const result = {};
+  for (const name of ['accept', 'content-type', 'if-match', 'range']) {
+    const value = headers && typeof headers === 'object' ? headers[name] || headers[name.toUpperCase()] : '';
+    if (value) result[name] = String(value).slice(0, 512);
+  }
+  return result;
+}
+
+export function createHubConsoleRelay(options = {}) {
+  const relayUrl = normalizeRelayUrl(options.url);
+  const deviceId = String(options.deviceId || '').trim();
+  const httpBaseUrl = String(options.httpBaseUrl || '').replace(/\/+$/, '');
+  const WebSocketImpl = options.WebSocketImpl || WebSocket;
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const getAccessToken = typeof options.getAccessToken === 'function'
+    ? options.getAccessToken
+    : async () => String(options.accessToken || '').trim();
+  const logger = options.logger || console;
+  const retryDelaysMs = options.retryDelaysMs || DEFAULT_RETRY_DELAYS_MS;
+  const localSockets = new Map();
+  const pendingHttp = new Set();
+  let relaySocket = null;
+  let retryTimer = null;
+  let retryAttempt = 0;
+  let generation = 0;
+  let stopped = true;
+  let state = relayUrl ? 'idle' : 'disabled';
+  let lastConnectedAt = '';
+  let lastError = relayUrl instanceof URL ? '' : relayUrl === '' ? '' : 'invalid-relay-url';
+  let droppedBinaryMessages = 0;
+
+  const sendRelay = payload => {
+    if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN) return false;
+    if (Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) return false;
+    relaySocket.send(typeof payload === 'string' || Buffer.isBuffer(payload) ? payload : JSON.stringify(payload));
+    return true;
+  };
+
+  const sendError = (consoleId, channelId, error, type = 'relay-error') => {
+    sendRelay({ type, consoleId, channelId, error: String(error || 'console-relay-error').slice(0, 240) });
+  };
+
+  const closeLocalSocket = (key, code = 1000, reason = 'console-channel-closed') => {
+    const socket = localSockets.get(key);
+    if (!socket) return;
+    localSockets.delete(key);
+    try { socket.close(code, reason); } catch { /* exact socket is already closed */ }
+    try { socket.terminate?.(); } catch { /* exact socket is already closed */ }
+  };
+
+  const closeConsoleChannels = consoleId => {
+    for (const key of [...localSockets.keys()]) {
+      if (key.startsWith(`${consoleId}\n`)) closeLocalSocket(key, 1001, 'console-detached');
+    }
+  };
+
+  const closeAllLocalSockets = reason => {
+    for (const key of [...localSockets.keys()]) closeLocalSocket(key, 1012, reason);
+  };
+
+  const handleHttpRequest = async payload => {
+    const consoleId = String(payload?.consoleId || '');
+    const channelId = String(payload?.channelId || '');
+    const method = String(payload?.method || 'GET').toUpperCase();
+    const path = String(payload?.path || '');
+    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedHttpRequest(method, path)) {
+      sendError(consoleId, channelId, 'console-route-not-allowed', 'http-response');
+      return;
+    }
+    if (pendingHttp.size >= MAX_CHANNELS) {
+      sendError(consoleId, channelId, 'console-http-capacity-reached', 'http-response');
+      return;
+    }
+    let body;
+    try {
+      body = payload.bodyBase64 ? Buffer.from(String(payload.bodyBase64), 'base64') : undefined;
+    } catch {
+      sendError(consoleId, channelId, 'invalid-console-http-body', 'http-response');
+      return;
+    }
+    if (body && body.byteLength > MAX_HTTP_REQUEST_BYTES) {
+      sendError(consoleId, channelId, 'console-http-body-too-large', 'http-response');
+      return;
+    }
+
+    const requestKey = channelKey(consoleId, channelId);
+    pendingHttp.add(requestKey);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('console-http-timeout')), HTTP_TIMEOUT_MS);
+    timeout.unref?.();
+    try {
+      const response = await fetchImpl(`${httpBaseUrl}${path}`, {
+        method,
+        headers: safeContentHeaders(payload.headers),
+        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
+        signal: controller.signal
+      });
+      const responseBytes = Buffer.from(await response.arrayBuffer());
+      if (responseBytes.byteLength > MAX_HTTP_RESPONSE_BYTES) {
+        sendError(consoleId, channelId, 'console-http-response-too-large', 'http-response');
+        return;
+      }
+      sendRelay({
+        type: 'http-response',
+        consoleId,
+        channelId,
+        status: response.status,
+        statusText: response.statusText,
+        headers: {
+          'content-type': String(response.headers.get('content-type') || '').slice(0, 256),
+          'content-range': String(response.headers.get('content-range') || '').slice(0, 256)
+        },
+        bodyBase64: responseBytes.toString('base64')
+      });
+    } catch (error) {
+      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'http-response');
+    } finally {
+      clearTimeout(timeout);
+      pendingHttp.delete(requestKey);
+    }
+  };
+
+  const handleWebSocketOpen = payload => {
+    const consoleId = String(payload?.consoleId || '');
+    const channelId = String(payload?.channelId || '');
+    const path = String(payload?.path || '');
+    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedWebSocketPath(path)) {
+      sendError(consoleId, channelId, 'console-websocket-route-not-allowed', 'ws-error');
+      return;
+    }
+    if (localSockets.size >= MAX_CHANNELS) {
+      sendError(consoleId, channelId, 'console-websocket-capacity-reached', 'ws-error');
+      return;
+    }
+    const key = channelKey(consoleId, channelId);
+    closeLocalSocket(key, 1000, 'console-channel-replaced');
+    const localUrl = new URL(path, httpBaseUrl);
+    localUrl.protocol = localUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+    let socket;
+    try {
+      socket = new WebSocketImpl(localUrl, { perMessageDeflate: false });
+    } catch (error) {
+      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
+      return;
+    }
+    localSockets.set(key, socket);
+    socket.once('open', () => {
+      if (localSockets.get(key) !== socket) return;
+      sendRelay({ type: 'ws-opened', consoleId, channelId });
+    });
+    socket.on('message', (data, isBinary) => {
+      if (localSockets.get(key) !== socket) return;
+      if (isBinary) {
+        if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN
+          || Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) {
+          droppedBinaryMessages += 1;
+          return;
+        }
+        const header = Buffer.from(`B${consoleId}${channelId}`, 'ascii');
+        if (header.byteLength !== BINARY_HEADER_BYTES) {
+          closeLocalSocket(key, 1008, 'invalid-relay-channel-id');
+          return;
+        }
+        relaySocket.send(Buffer.concat([header, Buffer.from(data)]));
+        return;
+      }
+      sendRelay({ type: 'ws-message', consoleId, channelId, data: String(data), binary: false });
+    });
+    socket.once('close', (code, reason) => {
+      if (localSockets.get(key) === socket) localSockets.delete(key);
+      sendRelay({ type: 'ws-closed', consoleId, channelId, code, reason: String(reason || '').slice(0, 120) });
+    });
+    socket.once('error', error => {
+      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
+    });
+  };
+
+  const handleMessage = raw => {
+    const payload = parseMessage(raw);
+    if (!payload?.type) return;
+    if (payload.type === 'relay-ready') {
+      state = 'connected';
+      lastConnectedAt = new Date().toISOString();
+      lastError = '';
+      return;
+    }
+    if (payload.type === 'console-detached') {
+      closeConsoleChannels(String(payload.consoleId || ''));
+      return;
+    }
+    if (payload.type === 'http-request') {
+      void handleHttpRequest(payload);
+      return;
+    }
+    if (payload.type === 'ws-open') {
+      handleWebSocketOpen(payload);
+      return;
+    }
+    const key = channelKey(String(payload.consoleId || ''), String(payload.channelId || ''));
+    const socket = localSockets.get(key);
+    if (!socket) return;
+    if (payload.type === 'ws-send' && socket.readyState === WebSocketImpl.OPEN) {
+      const data = String(payload.data || '');
+      if (Buffer.byteLength(data) <= MAX_HTTP_REQUEST_BYTES) socket.send(data);
+    } else if (payload.type === 'ws-close') {
+      closeLocalSocket(key, Number(payload.code || 1000), String(payload.reason || 'console-request').slice(0, 120));
+    }
+  };
+
+  const scheduleReconnect = connect => {
+    if (stopped || retryTimer || !(relayUrl instanceof URL)) return;
+    const delayMs = retryDelaysMs[Math.min(retryAttempt, retryDelaysMs.length - 1)];
+    retryAttempt += 1;
+    state = 'waiting-retry';
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void connect();
+    }, delayMs);
+    retryTimer.unref?.();
+  };
+
+  const connect = async () => {
+    if (stopped || !(relayUrl instanceof URL) || !deviceId) return;
+    const ownerGeneration = ++generation;
+    state = 'connecting';
+    let accessToken = '';
+    try {
+      accessToken = String(await getAccessToken() || '').trim();
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+    if (stopped || ownerGeneration !== generation) return;
+    if (!accessToken) {
+      lastError = 'hub-session-required';
+      scheduleReconnect(connect);
+      return;
+    }
+    const url = new URL(relayUrl);
+    url.searchParams.set('deviceId', deviceId);
+    let socket;
+    try {
+      socket = new WebSocketImpl(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        perMessageDeflate: false
+      });
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      scheduleReconnect(connect);
+      return;
+    }
+    if (stopped || ownerGeneration !== generation) {
+      try { socket.terminate?.(); } catch { /* stale connect is already gone */ }
+      return;
+    }
+    relaySocket = socket;
+    socket.once('open', () => {
+      if (relaySocket !== socket || ownerGeneration !== generation || stopped) return;
+      retryAttempt = 0;
+      state = 'authenticating';
+    });
+    socket.on('message', raw => {
+      if (relaySocket === socket && ownerGeneration === generation && !stopped) handleMessage(raw);
+    });
+    socket.once('close', () => {
+      if (relaySocket === socket) relaySocket = null;
+      if (ownerGeneration !== generation || stopped) return;
+      state = 'disconnected';
+      closeAllLocalSockets('relay-disconnected');
+      scheduleReconnect(connect);
+    });
+    socket.once('error', error => {
+      lastError = error instanceof Error ? error.message : String(error);
+      try { socket.terminate?.(); } catch { /* close handler owns retry */ }
+    });
+  };
+
+  const start = () => {
+    if (!stopped || !(relayUrl instanceof URL) || !deviceId) return;
+    stopped = false;
+    void connect();
+  };
+
+  const refresh = () => {
+    if (stopped) {
+      start();
+      return;
+    }
+    generation += 1;
+    if (retryTimer) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+    const socket = relaySocket;
+    relaySocket = null;
+    try { socket?.terminate?.(); } catch { /* refresh owns the exact socket */ }
+    closeAllLocalSockets('relay-refresh');
+    void connect();
+  };
+
+  const close = () => {
+    if (stopped) return;
+    stopped = true;
+    generation += 1;
+    if (retryTimer) clearTimeout(retryTimer);
+    retryTimer = null;
+    closeAllLocalSockets('hub-shutdown');
+    const socket = relaySocket;
+    relaySocket = null;
+    try { socket?.close(1001, 'hub-shutdown'); } catch { /* exact socket is already closed */ }
+    try { socket?.terminate?.(); } catch { /* exact socket is already closed */ }
+    state = relayUrl ? 'closed' : 'disabled';
+  };
+
+  return {
+    start,
+    refresh,
+    close,
+    inspect: () => ({
+      enabled: relayUrl instanceof URL && Boolean(deviceId),
+      state,
+      connected: state === 'connected',
+      localWebSocketChannels: localSockets.size,
+      pendingHttpRequests: pendingHttp.size,
+      droppedBinaryMessages,
+      lastConnectedAt,
+      lastError
+    })
+  };
+}
+
+export const consoleRelayContract = Object.freeze({
+  maxChannels: MAX_CHANNELS,
+  maxHttpRequestBytes: MAX_HTTP_REQUEST_BYTES,
+  maxHttpResponseBytes: MAX_HTTP_RESPONSE_BYTES,
+  maxBufferedBytes: MAX_RELAY_BUFFERED_BYTES,
+  binaryHeaderBytes: BINARY_HEADER_BYTES
+});

package/src/server.js

@@ -7,8 +7,9 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, wri
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import os from 'node:os';
-import { WebSocketServer } from 'ws';
-import { createRemoteHub } from './remote-hub.js';
+import { WebSocketServer } from 'ws';
+import { createRemoteHub } from './remote-hub.js';
+import { createHubConsoleRelay } from './console-relay.js';
 import {
   buildImmutableRemoteFramePacket,
   createRemoteFramePacketMetrics,
@@ -39,8 +40,9 @@ import { createAgentDeviceScope, resolveAgentTargetIds } from './agents/agent-de
 import { AgentRuntimeError } from './agents/agent-runtime-error.js';
 import { AGENT_PERMISSION_MODES, createAgentPermissionPolicy, evaluateAgentToolPermission, hashAgentPermissionPolicy } from './agents/agent-permissions.js';
 import { createAgentPermissionStore } from './agents/agent-permission-store.js';
-import { createAgentAuditStore } from './agents/agent-audit-store.js';
-import { getAgentToolDefinition } from './agents/agent-tool-registry.js';
+import { createAgentAuditStore } from './agents/agent-audit-store.js';
+import { getAgentToolDefinition } from './agents/agent-tool-registry.js';
+import { enrichAgentTaskResults } from './agents/agent-result-enrichment.js';
 import { LiveDeskSettingsStore, SettingsConflictError } from './settings/settings-store.js';
 import { effectiveDevicePolicy } from './settings/settings-schema.js';
 import { buildEffectiveDevicePolicy } from './settings/effective-device-policy.js';
@@ -202,15 +204,22 @@ let verifiedLicense = {
 let frameClientSeq = 0;
 let inputClientSeq = 0;
 let audioClientSeq = 0;
-let liveDeskUpdateManager = null;
-let hubTransferJobs = null;
+let liveDeskUpdateManager = null;
+let hubTransferJobs = null;
+let hubConsoleRelay = null;
 const HUB_HOST_TARGET_LEASE_MS = Math.max(5000, readPositiveIntegerEnv('LIVEDESK_HOST_TARGET_LEASE_MS', 60_000));
 const HUB_HOST_TARGET_RENEW_MS = Math.max(1000, Math.min(
   readPositiveIntegerEnv('LIVEDESK_HOST_TARGET_RENEW_MS', 20_000),
   Math.max(1000, HUB_HOST_TARGET_LEASE_MS - 1000)
 ));
-const HUB_ACCESS_TOKEN_REFRESH_SKEW_MS = 90_000;
-const hubWakeBaseUrl = String(process.env.LIVEDESK_WAKE_URL || 'https://livedesk-wake.lovecrdm.workers.dev').trim();
+const HUB_ACCESS_TOKEN_REFRESH_SKEW_MS = 90_000;
+const hubWakeBaseUrl = String(process.env.LIVEDESK_WAKE_URL || 'https://livedesk-wake.lovecrdm.workers.dev').trim();
+const hubConsoleRelayBaseUrl = String(
+  process.env.LIVEDESK_CONSOLE_RELAY_URL
+  || (process.env.LIVEDESK_TEST_MODE === '1' || process.env.LIVEDESK_AUTH_TEST_MODE === '1'
+    ? 'off'
+    : 'https://livedesk-wake.lovecrdm.workers.dev')
+).trim();
 const HUB_WAKE_NOTIFY_RETRY_MS = 60_000;
 let hubHostTargetRenewTimer = null;
 let hubHostTargetRenewInFlight = false;
@@ -1261,10 +1270,16 @@ async function dispatchAgentMcpTool(session, name, args = {}) {
       remoteHub.cancelTaskBatch(result.batchId);
       return { ok: false, error: 'cancelled-by-user', batchId: result.batchId };
     }
-    const batch = remoteHub.getTaskBatch(result.batchId);
-    if (!batch) return { ok: false, error: 'task-not-found', batchId: result.batchId };
-    if (!['queued', 'running'].includes(batch.status)) {
-      return {
+    const batch = remoteHub.getTaskBatch(result.batchId);
+    if (!batch) return { ok: false, error: 'task-not-found', batchId: result.batchId };
+    if (!['queued', 'running'].includes(batch.status)) {
+      const taskResults = enrichAgentTaskResults({
+        operation,
+        results: batch.results,
+        devices: remoteHub.listDevices({ includeDataUrl: false })
+          .filter(device => targetIds.includes(device.deviceId))
+      });
+      return {
         ok: true,
         batchId: result.batchId,
         operation,
@@ -1272,8 +1287,8 @@ async function dispatchAgentMcpTool(session, name, args = {}) {
         total: batch.total,
         completed: batch.completed,
         failed: batch.failed,
-        results: batch.results.map(item => ({ deviceId: item.deviceId, deviceName: item.deviceName, status: item.status, stage: item.stage, result: String(item.result || '').slice(0, 3000), data: item.data, error: String(item.error || '').slice(0, 500) }))
-      };
+        results: taskResults.map(item => ({ deviceId: item.deviceId, deviceName: item.deviceName, status: item.status, stage: item.stage, result: String(item.result || '').slice(0, 3000), data: item.data, error: String(item.error || '').slice(0, 500) }))
+      };
     }
     await delayAgentMcp(200);
   }
@@ -1333,9 +1348,16 @@ const hubSharedFolders = createHubSharedFolders({
   dataDir: agentDataDir
 });
 
-const app = express();
-const httpServer = createServer(app);
-const httpConnections = new Set();
+const app = express();
+const httpServer = createServer(app);
+hubConsoleRelay = createHubConsoleRelay({
+  url: runtimeRole === 'hub' ? hubConsoleRelayBaseUrl : 'off',
+  deviceId: runtimeDeviceId,
+  httpBaseUrl: `http://127.0.0.1:${httpPort}`,
+  getAccessToken: () => getRuntimeAccessToken(),
+  logger: console
+});
+const httpConnections = new Set();
 const frameWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
 const atlasWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
 const inputWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
@@ -4219,9 +4241,10 @@ app.get('/api/remote/status', (_req, res) => {
     runtimeRole,
     deviceId: runtimeDeviceId,
     deviceName: runtimeDeviceName,
-    roleSource: runtimeRoleSource,
-    agentPackage: '@livedesk/client',
-    frameLanes: snapshotFrameLaneResourceHealth(),
+    roleSource: runtimeRoleSource,
+    agentPackage: '@livedesk/client',
+    consoleRelay: hubConsoleRelay?.inspect() || { enabled: false, state: 'starting' },
+    frameLanes: snapshotFrameLaneResourceHealth(),
     update: getLiveDeskUpdateStatus()
   });
 });
@@ -4453,10 +4476,11 @@ app.post('/api/auth/session', async (req, res) => {
         csrfToken: uiSession.csrfToken,
         expiresAt: uiSession.expiresAt
       }
-    });
-    if (runtimeRole === 'hub') {
-      scheduleAuthenticatedHubHostTargetPublication('session-received');
-    }
+    });
+    if (runtimeRole === 'hub') {
+      hubConsoleRelay?.refresh();
+      scheduleAuthenticatedHubHostTargetPublication('session-received');
+    }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const status = authVerificationHttpStatus(message);
@@ -4476,10 +4500,11 @@ function getHubHostTargetLeaseStatus() {
     ...hubHostTargetLeaseState,
     renewing: hubHostTargetRenewInFlight,
     renewalIntervalMs: HUB_HOST_TARGET_RENEW_MS,
-    leaseDurationMs: HUB_HOST_TARGET_LEASE_MS,
-    authenticated: Boolean(runtimeAccessToken),
-    timerActive: Boolean(hubHostTargetRenewTimer),
-    wake: { ...hubWakeNotificationState }
+    leaseDurationMs: HUB_HOST_TARGET_LEASE_MS,
+    authenticated: Boolean(runtimeAccessToken),
+    timerActive: Boolean(hubHostTargetRenewTimer),
+    wake: { ...hubWakeNotificationState },
+    consoleRelay: hubConsoleRelay?.inspect() || { enabled: false, state: 'starting' }
   };
 }
 
@@ -4783,10 +4808,11 @@ app.get('/api/hub/status', (_req, res) => {
     ...remoteHub.getStatus({ includeSecrets: false }),
     role: 'hub',
     deviceId: runtimeDeviceId,
-    deviceName: runtimeDeviceName,
-    roleSource: runtimeRoleSource,
-    runtimeStarted: true,
-    hostTargetLease: getHubHostTargetLeaseStatus(),
+    deviceName: runtimeDeviceName,
+    roleSource: runtimeRoleSource,
+    runtimeStarted: true,
+    consoleRelay: hubConsoleRelay?.inspect() || { enabled: false, state: 'starting' },
+    hostTargetLease: getHubHostTargetLeaseStatus(),
     update: getLiveDeskUpdateStatus()
   });
 });
@@ -5793,13 +5819,14 @@ hubSharedFolders.startAutoSync(
   () => remoteHub.listDevices({ includeDataUrl: false }).filter(device => device.connected).map(device => device.deviceId),
   () => process.env.LIVEDESK_REMOTE_DIRECTORY || 'Desktop/LiveDeskFiles'
 );
-httpServer.listen(httpPort, httpHost, () => {
+httpServer.listen(httpPort, httpHost, () => {
   const status = remoteHub.getStatus({ includeSecrets: true });
   const managerVersion = String(process.env.LIVEDESK_MANAGER_VERSION || packageInfo.version || 'dev');
   console.log(`[LiveDesk Hub] Version ${managerVersion}`);
-  console.log(`[LiveDesk Hub] HTTP API http://${httpHost}:${httpPort}`);
-  console.log(`[LiveDesk Hub] Client endpoint ${status.agentEndpoint} pair=${status.pairTokenPreview}`);
-});
+  console.log(`[LiveDesk Hub] HTTP API http://${httpHost}:${httpPort}`);
+  console.log(`[LiveDesk Hub] Client endpoint ${status.agentEndpoint} pair=${status.pairTokenPreview}`);
+  hubConsoleRelay?.start();
+});
 
 const roleWatchTimer = runtimeRole === 'hub'
   ? setInterval(() => { void watchAuthoritativeRuntimeRole(); }, 5000)
@@ -5880,9 +5907,10 @@ function shutdownHub(signal) {
     const startedAt = Date.now();
     console.log(`[LiveDesk Hub] Shutdown started signal=${signal} grace=${hubShutdownGraceMs}ms timeout=${hubShutdownTimeoutMs}ms.`);
     if (roleWatchTimer) clearInterval(roleWatchTimer);
-    clearInterval(browserWebSocketHeartbeatTimer);
-    runSynchronousShutdownStep('update manager close', () => liveDeskUpdateManager?.close());
-    atlasClients.clear();
+    clearInterval(browserWebSocketHeartbeatTimer);
+    runSynchronousShutdownStep('update manager close', () => liveDeskUpdateManager?.close());
+    runSynchronousShutdownStep('mobile console relay close', () => hubConsoleRelay?.close());
+    atlasClients.clear();
     runSynchronousShutdownStep('shared folder close', () => hubSharedFolders.close());
 
     const httpClosed = new Promise(resolveClose => {