ds-harness-remote 0.3.16 → 0.3.18

package/dist/index.js

@@ -4083,7 +4083,8 @@ var rpcMethods = [
   "harness.api.call",
   "harness.api.respond",
   "harness.api.stream.open",
-  "harness.api.stream.close"
+  "harness.api.stream.close",
+  "fileviewer.call"
 ];
 var rpcMethodSchema = external_exports.enum(rpcMethods);
 var messageTypeSchema = external_exports.enum(messageTypes);
@@ -4803,6 +4804,7 @@ var RtcDataChannelTransport = class {
   bytesSent = 0;
   bytesReceived = 0;
   selected;
+  selectedMode;
   lastBufferedAmount = 0;
   constructor(options) {
     this.role = options.role;
@@ -4879,10 +4881,27 @@ var RtcDataChannelTransport = class {
   selectedTransport() {
     return this.selected;
   }
+  selectedPathMode() {
+    return this.selectedMode;
+  }
+  async connectionDetails() {
+    let statsDetails = {};
+    try {
+      statsDetails = inspectSelectedPath(await this.pc.getStats());
+    } catch {
+    }
+    return {
+      ...statsDetails,
+      mode: statsDetails.mode ?? this.selectedMode,
+      connectionState: this.pc.connectionState,
+      iceConnectionState: this.pc.iceConnectionState,
+      dataChannelState: this.channel?.readyState
+    };
+  }
   getStats() {
     const connected = this.channel?.readyState === "open";
     return {
-      mode: !connected ? "Disconnected" : this.selected === "turn" ? "TURN" : "P2P",
+      mode: !connected ? "Disconnected" : this.selectedMode ?? (this.selected === "turn" ? "TURN" : "P2P"),
       connected,
       bytesSent: this.bytesSent,
       bytesReceived: this.bytesReceived
@@ -5043,9 +5062,12 @@ var RtcDataChannelTransport = class {
   }
   async resolveSelectedTransport() {
     try {
-      this.selected = detectSelectedTransport(await this.pc.getStats());
+      const selected = inspectSelectedPath(await this.pc.getStats());
+      this.selected = selected?.transport;
+      this.selectedMode = selected?.mode;
     } catch {
       this.selected = void 0;
+      this.selectedMode = void 0;
     }
   }
   checkConnectionState() {
@@ -5119,28 +5141,73 @@ var RtcConnectError = class extends Error {
     this.code = code;
   }
 };
-function detectSelectedTransport(stats) {
-  const candidateTypes = /* @__PURE__ */ new Map();
+function inspectSelectedPath(stats) {
+  const candidates = /* @__PURE__ */ new Map();
+  const candidatePairs = /* @__PURE__ */ new Map();
   const selectedPairs = [];
-  for (const [, entry] of stats) {
+  const selectedPairIds = /* @__PURE__ */ new Set();
+  for (const [reportId, entry] of stats) {
     if (entry.type === "local-candidate" || entry.type === "remote-candidate") {
       if (typeof entry.candidateType === "string" && entry.id !== void 0) {
-        candidateTypes.set(String(entry.id), entry.candidateType);
+        candidates.set(String(entry.id), entry);
       }
-    } else if (entry.type === "candidate-pair" || entry.type === "transport") {
+    } else if (entry.type === "candidate-pair") {
+      candidatePairs.set(String(entry.id ?? reportId), entry);
       if (entry.selected === true || entry.nominated === true)
         selectedPairs.push(entry);
-    }
-  }
-  for (const pair of selectedPairs) {
-    const local = candidateTypes.get(String(pair.localCandidateId));
-    const remote = candidateTypes.get(String(pair.remoteCandidateId));
-    if (local === "relay" || remote === "relay")
-      return "turn";
-    if (local !== void 0 || remote !== void 0)
-      return "p2p";
+    } else if (entry.type === "transport" && typeof entry.selectedCandidatePairId === "string") {
+      selectedPairIds.add(entry.selectedCandidatePairId);
+    }
+  }
+  const pairs = [
+    ...[...selectedPairIds].map((id) => candidatePairs.get(id)).filter((pair) => pair !== void 0),
+    ...selectedPairs
+  ];
+  for (const pair of pairs) {
+    const local = candidates.get(String(pair.localCandidateId));
+    const remote = candidates.get(String(pair.remoteCandidateId));
+    const localType = local?.candidateType;
+    const remoteType = remote?.candidateType;
+    let selected;
+    if (localType === "relay" || remoteType === "relay")
+      selected = { transport: "turn", mode: "TURN" };
+    if (local === void 0 && remote === void 0)
+      continue;
+    selected ??= {
+      transport: "p2p",
+      mode: localType === "host" && remoteType === "host" ? "LAN" : "P2P"
+    };
+    const currentRoundTripTime = numberStat(pair, "currentRoundTripTime");
+    return {
+      ...selected,
+      localCandidateType: stringStat(local, "candidateType"),
+      remoteCandidateType: stringStat(remote, "candidateType"),
+      localAddress: candidateAddress(local),
+      remoteAddress: candidateAddress(remote),
+      protocol: stringStat(local, "protocol") ?? stringStat(remote, "protocol"),
+      relayProtocol: stringStat(local, "relayProtocol") ?? stringStat(remote, "relayProtocol"),
+      currentRoundTripTimeMs: currentRoundTripTime === void 0 ? void 0 : Math.round(currentRoundTripTime * 1e3),
+      availableOutgoingBitrate: numberStat(pair, "availableOutgoingBitrate"),
+      bytesSent: numberStat(pair, "bytesSent"),
+      bytesReceived: numberStat(pair, "bytesReceived")
+    };
   }
-  return void 0;
+  return {};
+}
+function candidateAddress(candidate) {
+  const address = stringStat(candidate, "address") ?? stringStat(candidate, "ip");
+  if (address === void 0)
+    return void 0;
+  const port = numberStat(candidate, "port");
+  return port === void 0 ? address : `${address}:${port}`;
+}
+function stringStat(entry, key) {
+  const value = entry?.[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function numberStat(entry, key) {
+  const value = entry?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 function requireSdp(description) {
   if (typeof description.sdp !== "string" || description.sdp.length === 0) {
@@ -5159,7 +5226,7 @@ function asError(error) {
 
 // ../webrtc/dist/adaptive-transport.js
 var DEFAULT_CAPABILITIES = ["transport.p2p", "transport.turn", "transport.relay", "harness.api.v1"];
-var DEFAULT_PREFERRED_TRANSPORTS = ["p2p", "turn", "relay"];
+var DEFAULT_PREFERRED_TRANSPORTS = ["lan", "p2p", "turn", "relay"];
 var AdaptiveTransport = class extends BaseTransport {
   url;
   options;
@@ -5177,6 +5244,7 @@ var AdaptiveTransport = class extends BaseTransport {
   handshakeTimer;
   webrtcEnabled = true;
   serverNegotiateTimeoutMs;
+  connectedAt;
   constructor(url, options) {
     super();
     this.url = url;
@@ -5246,6 +5314,16 @@ var AdaptiveTransport = class extends BaseTransport {
       remoteDeviceId: this.options.targetDeviceId
     };
   }
+  async connectionDetails() {
+    return {
+      ...this.connectionId === void 0 ? {} : { connectionId: this.connectionId },
+      ...this.connectedAt === void 0 ? {} : { connectedAt: this.connectedAt },
+      controlChannelUrl: this.url,
+      controlChannelState: socketState(this.socket?.readyState),
+      preferredTransports: this.options.forceRelay === true ? ["relay"] : [...this.options.preferredTransports ?? DEFAULT_PREFERRED_TRANSPORTS],
+      ...this.rtc === void 0 ? {} : { webRtc: await this.rtc.connectionDetails() }
+    };
+  }
   async sendHandshake(step, data) {
     if (this.socket?.readyState !== WebSocket.OPEN || this.connectionId === void 0) {
       throw new Error("adaptive transport has not been authorized");
@@ -5276,10 +5354,9 @@ var AdaptiveTransport = class extends BaseTransport {
     let mode = "Disconnected";
     if (this.selected === "relay")
       mode = relayConnected ? "Relay" : "Disconnected";
-    else if (this.selected === "turn")
-      mode = webrtcConnected ? "TURN" : "Disconnected";
-    else if (this.selected === "p2p")
-      mode = webrtcConnected ? "P2P" : "Disconnected";
+    else if (this.selected === "turn" || this.selected === "p2p") {
+      mode = webrtcConnected ? this.rtc.getStats().mode : "Disconnected";
+    }
     return { mode, connected, bytesSent: this.bytesSent, bytesReceived: this.bytesReceived };
   }
   async handleSocketMessage(raw) {
@@ -5365,14 +5442,19 @@ var AdaptiveTransport = class extends BaseTransport {
     if (this.connectionId === void 0)
       return;
     const preferred = this.options.preferredTransports ?? [...DEFAULT_PREFERRED_TRANSPORTS];
-    const wantWebRtc = !this.options.forceRelay && this.webrtcEnabled && (preferred.includes("p2p") || preferred.includes("turn"));
+    const wantWebRtc = !this.options.forceRelay && this.webrtcEnabled && (preferred.includes("lan") || preferred.includes("p2p") || preferred.includes("turn"));
     let selected = "relay";
     if (wantWebRtc) {
       try {
         const rtcSelected = await this.tryWebRtc();
         this.dataMode = "webrtc";
         selected = rtcSelected;
-      } catch {
+      } catch (error) {
+        const reason = error instanceof Error ? error : new Error("WebRTC negotiation failed.");
+        try {
+          this.options.onWebRtcFallback?.(reason);
+        } catch {
+        }
         await this.rtc?.close();
         this.rtc = void 0;
         this.dataMode = "relay";
@@ -5457,6 +5539,7 @@ var AdaptiveTransport = class extends BaseTransport {
   }
   finishConnection() {
     this.clearHandshake();
+    this.connectedAt ??= Date.now();
     this.readyResolve?.();
     this.readyResolve = void 0;
     this.readyReject = void 0;
@@ -5487,6 +5570,15 @@ function adaptiveControlCloseError(event) {
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function socketState(readyState) {
+  if (readyState === 0)
+    return "connecting";
+  if (readyState === 1)
+    return "open";
+  if (readyState === 2)
+    return "closing";
+  return "closed";
+}
 
 // src/api-proxy-switch.ts
 var SWITCHED_DOMAINS = [
@@ -12973,7 +13065,7 @@ function normalizeServerUrl(value) {
 }
 
 // src/version.ts
-var PLUGIN_VERSION = "0.3.16";
+var PLUGIN_VERSION = "0.3.18";
 
 // src/server-api.ts
 var HostServerApi = class {
@@ -13359,6 +13451,7 @@ function requireRecord(value, name2) {
 
 // src/typert-gateway-switch.ts
 var REMOTE_COMMAND_METHODS = ["execute", "list"];
+var ALL_REMOTE_COMMANDS = { execute: true, list: true };
 var TypertGatewaySwitch = class {
   constructor(gateway) {
     this.gateway = gateway;
@@ -13368,6 +13461,7 @@ var TypertGatewaySwitch = class {
   originalInvoke;
   localInvoke;
   remoteInvoke;
+  remoteSupport = { execute: false, list: false };
   installed = false;
   /** A facade that always invokes the original local gateway. */
   local() {
@@ -13375,15 +13469,24 @@ var TypertGatewaySwitch = class {
   }
   install() {
     if (this.installed) return;
-    this.gateway.invoke = (request) => request.namespace === "commands" && isRemoteCommandMethod(request.method) ? (this.remoteInvoke ?? this.localInvoke)(request) : this.localInvoke(request);
+    this.gateway.invoke = (request) => {
+      if (request.namespace !== "commands" || !isRemoteCommandMethod(request.method) || this.remoteInvoke === void 0) {
+        return this.localInvoke(request);
+      }
+      if (this.remoteSupport[request.method]) return this.remoteInvoke(request);
+      if (request.method === "list") return Promise.resolve([]);
+      return this.localInvoke(request);
+    };
     this.installed = true;
   }
-  selectRemote(invoke) {
+  selectRemote(invoke, support = ALL_REMOTE_COMMANDS) {
     if (!this.installed) throw new Error("The Typert gateway switch is not installed.");
     this.remoteInvoke = invoke;
+    this.remoteSupport = { ...support };
   }
   selectLocal() {
     this.remoteInvoke = void 0;
+    this.remoteSupport = { execute: false, list: false };
   }
   restore() {
     if (!this.installed) return;
@@ -13396,14 +13499,210 @@ function isRemoteCommandMethod(method) {
   return REMOTE_COMMAND_METHODS.includes(method);
 }
 
+// src/werift-rtc.ts
+import { networkInterfaces } from "node:os";
+var cachedFactory;
+async function loadWeriftFactory() {
+  if (cachedFactory !== void 0) return cachedFactory;
+  try {
+    const werift = await import("werift");
+    cachedFactory = buildWeriftFactory(werift);
+    return cachedFactory;
+  } catch {
+    return void 0;
+  }
+}
+function buildWeriftFactory(werift) {
+  return {
+    create(configuration) {
+      const hostIpv4 = detectHostIpv4();
+      const raw = new werift.RTCPeerConnection({
+        iceServers: configuration.iceServers ?? [],
+        iceUseIpv6: false,
+        iceUseLinkLocalAddress: false,
+        ...hostIpv4 === void 0 ? {} : { iceInterfaceAddresses: { udp4: hostIpv4 } }
+      });
+      let onIceCandidate = null;
+      let onDataChannel = null;
+      raw.onicecandidate = (event) => {
+        if (onIceCandidate === null) return;
+        onIceCandidate({ candidate: event.candidate === void 0 ? null : event.candidate.toJSON() });
+      };
+      raw.ondatachannel = (event) => {
+        if (onDataChannel === null) return;
+        onDataChannel({ channel: adaptDataChannel2(event.channel) });
+      };
+      const pc = {
+        get connectionState() {
+          return raw.connectionState;
+        },
+        get iceConnectionState() {
+          return raw.iceConnectionState;
+        },
+        get iceGatheringState() {
+          return raw.iceGatheringState;
+        },
+        get signalingState() {
+          return raw.signalingState;
+        },
+        set onconnectionstatechange(value) {
+          raw.onconnectionstatechange = value;
+        },
+        get onconnectionstatechange() {
+          return raw.onconnectionstatechange;
+        },
+        set oniceconnectionstatechange(value) {
+          raw.oniceconnectionstatechange = value;
+        },
+        get oniceconnectionstatechange() {
+          return raw.oniceconnectionstatechange;
+        },
+        set onicegatheringstatechange(value) {
+          raw.onicegatheringstatechange = value;
+        },
+        get onicegatheringstatechange() {
+          return raw.onicegatheringstatechange;
+        },
+        set onicecandidate(value) {
+          onIceCandidate = value;
+        },
+        get onicecandidate() {
+          return onIceCandidate;
+        },
+        set ondatachannel(value) {
+          onDataChannel = value;
+        },
+        get ondatachannel() {
+          return onDataChannel;
+        },
+        createDataChannel(label, options) {
+          return adaptDataChannel2(raw.createDataChannel(label, { ordered: options?.ordered ?? true }));
+        },
+        createOffer() {
+          return raw.createOffer();
+        },
+        createAnswer() {
+          return raw.createAnswer();
+        },
+        setLocalDescription(description) {
+          return raw.setLocalDescription(description).then(() => void 0);
+        },
+        setRemoteDescription(description) {
+          return raw.setRemoteDescription(description);
+        },
+        addIceCandidate(candidate) {
+          return raw.addIceCandidate(candidate);
+        },
+        getStats() {
+          return raw.getStats();
+        },
+        close() {
+          void raw.close().catch(() => void 0);
+        }
+      };
+      return pc;
+    }
+  };
+}
+function adaptDataChannel2(raw) {
+  return {
+    get label() {
+      return raw.label;
+    },
+    get ordered() {
+      return raw.ordered;
+    },
+    get readyState() {
+      return raw.readyState;
+    },
+    get bufferedAmount() {
+      return raw.bufferedAmount;
+    },
+    binaryType: "arraybuffer",
+    set onopen(value) {
+      raw.onopen = value;
+    },
+    get onopen() {
+      return raw.onopen;
+    },
+    set onmessage(value) {
+      raw.onmessage = value === null ? null : (event) => value({ data: toArrayBuffer2(event.data) });
+    },
+    get onmessage() {
+      return null;
+    },
+    set onclose(value) {
+      raw.onclose = value;
+    },
+    get onclose() {
+      return raw.onclose;
+    },
+    set onerror(value) {
+      raw.onerror = value;
+    },
+    get onerror() {
+      return raw.onerror;
+    },
+    onbufferedamountlow: null,
+    send(data) {
+      const bytes = typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
+      try {
+        raw.send(typeof data === "string" ? data : Buffer.from(data));
+      } catch (error) {
+        console.error("[werift-send-error] bytes=" + bytes, error instanceof Error ? error.message : error);
+        throw error;
+      }
+    },
+    close() {
+      raw.close();
+    }
+  };
+}
+function toArrayBuffer2(data) {
+  if (typeof data === "string") return data;
+  return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+}
+function detectHostIpv4() {
+  const preferred = [];
+  const fallback = [];
+  for (const [name2, addresses] of Object.entries(networkInterfaces())) {
+    if (isVirtualInterface(name2)) continue;
+    for (const address of addresses ?? []) {
+      if (address.internal || address.family !== "IPv4") continue;
+      const ip = address.address;
+      if (ip.startsWith("127.") || ip.startsWith("169.254.") || isCgnat(ip)) continue;
+      if (isPrivate(ip)) preferred.push(ip);
+      else fallback.push(ip);
+    }
+  }
+  return preferred[0] ?? fallback[0];
+}
+function isVirtualInterface(name2) {
+  return /^(utun|ppp|bridge|awdl|llw|gif|stf|anpi|ap\d|en[1-9]\d*$)/i.test(name2);
+}
+function isCgnat(ip) {
+  const parts = ip.split(".").map(Number);
+  return parts.length === 4 && parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127;
+}
+function isPrivate(ip) {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4) return false;
+  if (parts[0] === 10) return true;
+  if (parts[0] === 192 && parts[1] === 168) return true;
+  return parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31;
+}
+
 // src/client-runtime.ts
+var REMOTE_COMMAND_LIST_MIN_VERSION = [0, 3, 16];
+var REMOTE_FILE_VIEWER_MIN_VERSION = [0, 3, 17];
 var ClientModeRuntime = class {
-  constructor(config, identities, server, apiProxy, typertGateway, logger, host) {
+  constructor(config, identities, server, apiProxy, typertGateway, logger, host, rtcFactoryProvider = loadWeriftFactory) {
     this.config = config;
     this.identities = identities;
     this.server = server;
     this.logger = logger;
     this.host = host;
+    this.rtcFactoryProvider = rtcFactoryProvider;
     this.proxySwitch = new ApiProxySwitch(apiProxy);
     this.gatewaySwitch = new TypertGatewaySwitch(typertGateway);
   }
@@ -13437,10 +13736,33 @@ var ClientModeRuntime = class {
       ...this.proxySwitch.status(),
       connected: this.connected !== void 0,
       transport: this.connected?.client.getStats().mode ?? "Disconnected",
+      remoteFeatures: this.connected?.features ?? remoteHostFeatures(),
       hostAuthorizationAvailable: this.host !== void 0,
       ...this.host === void 0 ? {} : { host: this.host.hostStatus() }
     };
   }
+  async detailedStatus() {
+    const connected = this.connected;
+    if (connected === void 0 || this.identity === void 0) return this.status();
+    const details = await connected.transport.connectionDetails();
+    if (this.connected !== connected) return this.status();
+    return {
+      ...this.status(),
+      network: {
+        ...details,
+        local: {
+          deviceId: this.identity.deviceId,
+          name: this.identity.name,
+          platform: process.platform
+        },
+        remote: {
+          deviceId: connected.target.deviceId,
+          name: connected.target.name,
+          platform: connected.target.platform
+        }
+      }
+    };
+  }
   async devices() {
     this.requireIdentity();
     const serverDevices = await this.server.listDevices();
@@ -13518,7 +13840,7 @@ var ClientModeRuntime = class {
     this.connected = next;
     const remoteApi = new RemoteHarnessApiProxy(next.client).api;
     this.proxySwitch.selectRemote(remoteApi, { deviceId: next.target.deviceId, name: next.target.name });
-    this.gatewaySwitch.selectRemote((request) => invokeRemoteCommand(next.client, request));
+    this.selectRemoteCommands(next);
     await previous?.client.close().catch(() => void 0);
     this.logger.info("Harness target switched", { mode: "remote", targetDeviceId: shortId(next.target.deviceId) });
     return this.status();
@@ -13552,7 +13874,7 @@ var ClientModeRuntime = class {
     });
     const workspace = unwrapNativeResult(response);
     this.proxySwitch.selectRemote(api, { deviceId: remote.target.deviceId, name: remote.target.name });
-    this.gatewaySwitch.selectRemote((request) => invokeRemoteCommand(remote.client, request));
+    this.selectRemoteCommands(remote);
     this.logger.info("Remote workspace opened", { targetDeviceId: shortId(remote.target.deviceId) });
     return { ...this.status(), workspace };
   }
@@ -13566,6 +13888,22 @@ var ClientModeRuntime = class {
     this.proxySwitch.restore();
     this.gatewaySwitch.restore();
   }
+  async callRemoteFileViewer(endpoint, payload, signal) {
+    const remote = this.connected;
+    if (remote === void 0 || this.proxySwitch.status().mode !== "remote") {
+      throw new ClientModeError("REMOTE_NOT_CONNECTED", "No Remote Host is selected.", true);
+    }
+    if (!remote.features.fileViewer) {
+      throw new ClientModeError("FEATURE_NOT_SUPPORTED", "The selected Remote Host does not support remote file viewing.");
+    }
+    return remote.client.rpc("fileviewer.call", { endpoint, payload }, signal);
+  }
+  selectRemoteCommands(remote) {
+    this.gatewaySwitch.selectRemote((request) => invokeRemoteCommand(remote.client, request), {
+      execute: true,
+      list: remote.features.commandList
+    });
+  }
   async connect(targetDeviceId, signal) {
     signal?.throwIfAborted();
     const identity = this.requireIdentity();
@@ -13577,19 +13915,43 @@ var ClientModeRuntime = class {
     const presence = await this.server.presenceFor(targetDeviceId);
     if (!presence.online) throw new ClientModeError("HOST_OFFLINE", "The selected Host is offline.", true);
     const credentials = await this.server.authenticate(identity);
-    const transport = new AdaptiveTransport(websocketUrl(this.server.baseUrl), {
-      role: "client",
-      deviceId: identity.deviceId,
-      accessToken: credentials.accessToken,
-      targetDeviceId,
-      forceRelay: this.config.forceRelay,
-      preferredTransports: this.config.forceRelay ? ["relay"] : ["p2p", "turn", "relay"],
-      fetchIceServers: async (connectionId) => this.server.turnCredentials(connectionId)
-    });
-    const client = new RemoteClientCore(new ClientSecureTransport(transport, identity, target), 6e4);
+    const rtcFactory = this.config.forceRelay ? void 0 : await this.rtcFactoryProvider().catch(() => void 0);
+    let webRtcFallback = false;
+    const createTransport = (relayOnly) => new AdaptiveTransport(
+      websocketUrl(this.server.baseUrl),
+      {
+        role: "client",
+        deviceId: identity.deviceId,
+        accessToken: credentials.accessToken,
+        targetDeviceId,
+        forceRelay: this.config.forceRelay || relayOnly,
+        preferredTransports: this.config.forceRelay || relayOnly ? ["relay"] : ["lan", "p2p", "turn", "relay"],
+        ...rtcFactory === void 0 || relayOnly ? {} : { rtcFactory },
+        fetchIceServers: async (connectionId) => this.server.turnCredentials(connectionId),
+        onWebRtcFallback: (error) => {
+          webRtcFallback = true;
+          this.logger.warn("remote Harness WebRTC failed; using relay", {
+            targetDeviceId: shortId(target.deviceId),
+            reason: diagnosticReason(error)
+          });
+        }
+      }
+    );
+    let transport = createTransport(false);
+    let client = new RemoteClientCore(new ClientSecureTransport(transport, identity, target), 6e4);
     try {
       await client.connect();
       signal?.throwIfAborted();
+      if (webRtcFallback) {
+        await client.close();
+        transport = createTransport(true);
+        client = new RemoteClientCore(new ClientSecureTransport(transport, identity, target), 6e4);
+        await client.connect();
+        signal?.throwIfAborted();
+        this.logger.info("remote Harness relay fallback re-established", {
+          targetDeviceId: shortId(target.deviceId)
+        });
+      }
       client.onClose(() => {
         if (this.connected?.client !== client) return;
         this.connected = void 0;
@@ -13600,7 +13962,11 @@ var ClientModeRuntime = class {
           targetDeviceId: shortId(target.deviceId)
         });
       });
-      return { client, target };
+      this.logger.info("remote Harness transport ready", {
+        targetDeviceId: shortId(target.deviceId),
+        transport: client.getStats().mode
+      });
+      return { client, target, transport, features: remoteHostFeatures(serverDevice.clientVersion) };
     } catch (error) {
       await client.close().catch(() => void 0);
       throw error;
@@ -13616,7 +13982,7 @@ var ClientModeRuntime = class {
   }
   async handleControl(endpoint, payload, signal) {
     try {
-      if (endpoint === "status") return ok(this.status());
+      if (endpoint === "status") return ok(await this.detailedStatus());
       if (endpoint === "devices") return ok(await this.devices());
       if (endpoint === "client.account.login") {
         const value = record(payload);
@@ -13654,6 +14020,10 @@ var ClientModeRuntime = class {
         }
         return ok(await this.openRemoteWorkspace(value.targetDeviceId, value.path, signal));
       }
+      if (endpoint === "fileviewer.stat" || endpoint === "fileviewer.readRange" || endpoint === "fileviewer.list") {
+        const method = endpoint === "fileviewer.stat" ? "stat" : endpoint === "fileviewer.readRange" ? "readRange" : "list";
+        return ok(await this.callRemoteFileViewer(method, payload, signal));
+      }
       if (endpoint === "host.account.login") {
         if (this.host === void 0) throw new ClientModeError("METHOD_NOT_ALLOWED", "This plugin is not running as a Host.");
         const value = record(payload);
@@ -13776,6 +14146,29 @@ function fail(error) {
 function shortId(value) {
   return value.length <= 12 ? value : `${value.slice(0, 8)}\u2026${value.slice(-4)}`;
 }
+function remoteHostFeatures(clientVersion) {
+  return {
+    commandList: isVersionAtLeast(clientVersion, REMOTE_COMMAND_LIST_MIN_VERSION),
+    fileViewer: isVersionAtLeast(clientVersion, REMOTE_FILE_VIEWER_MIN_VERSION)
+  };
+}
+function isVersionAtLeast(value, minimum) {
+  const match = value?.match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (match === void 0 || match === null) return false;
+  const version = match.slice(1, 4).map((part) => Number(part));
+  for (let index = 0; index < minimum.length; index += 1) {
+    const part = version[index] ?? 0;
+    const expected = minimum[index] ?? 0;
+    if (part > expected) return true;
+    if (part < expected) return false;
+  }
+  return true;
+}
+function diagnosticReason(error) {
+  const code = "code" in error && typeof error.code === "string" ? error.code : void 0;
+  const message = error.message.replace(/[\r\n\t]+/g, " ").slice(0, 240);
+  return code === void 0 ? message : `${code}: ${message}`;
+}
 
 // src/control-runtime.ts
 import { hostname as hostname2 } from "node:os";
@@ -14396,7 +14789,7 @@ var ConnectionController = class {
     } catch (error) {
       this.logger?.warn("peer message handling failed; disconnecting", {
         peerDeviceId: shortId2(connection.channel.peerDeviceId),
-        reason: diagnosticReason(error)
+        reason: diagnosticReason2(error)
       });
       await this.disconnect(connection);
     }
@@ -14414,7 +14807,7 @@ var ConnectionController = class {
       this.logger?.warn("peer send failed; disconnecting", {
         peerDeviceId: shortId2(connection.channel.peerDeviceId),
         messageType: message.type,
-        reason: diagnosticReason(error)
+        reason: diagnosticReason2(error)
       });
       await this.disconnect(connection);
     }
@@ -14444,7 +14837,7 @@ var ConnectionRejectedError = class extends Error {
     this.code = code;
   }
 };
-function diagnosticReason(error) {
+function diagnosticReason2(error) {
   const message = error instanceof Error ? error.message : String(error);
   return message.replace(/[\r\n]+/g, " ").slice(0, 160) || "Unknown peer connection failure.";
 }
@@ -14458,14 +14851,16 @@ var apiMethods = /* @__PURE__ */ new Set([
   "harness.api.call",
   "harness.api.respond",
   "harness.api.stream.open",
-  "harness.api.stream.close"
+  "harness.api.stream.close",
+  "fileviewer.call"
 ]);
-var HOST_CAPABILITIES = ["harness.api.v1"];
+var HOST_CAPABILITIES = ["harness.api.v1", "fileviewer.read.v1"];
 var RpcRouter = class {
-  constructor(harnessApi, maxPending = 128, logger) {
+  constructor(harnessApi, maxPending = 128, logger, fileViewer) {
     this.harnessApi = harnessApi;
     this.maxPending = maxPending;
     this.logger = logger;
+    this.fileViewer = fileViewer;
   }
   active = 0;
   closePeerStreams() {
@@ -14500,7 +14895,7 @@ var RpcRouter = class {
         durationMs: Math.round(performance.now() - startedAt),
         code: response.payload.code,
         retryable: response.payload.retryable,
-        reason: diagnosticReason2(error)
+        reason: diagnosticReason3(error)
       });
       return response;
     } finally {
@@ -14517,6 +14912,12 @@ var RpcRouter = class {
         return this.harnessApi.openStream(params);
       case "harness.api.stream.close":
         return this.harnessApi.closeStream(params);
+      case "fileviewer.call": {
+        if (this.fileViewer === void 0) {
+          throw new RpcError("FILE_VIEWER_UNAVAILABLE", "The Remote Host does not have DSH File Viewer available.");
+        }
+        return this.fileViewer.call(params);
+      }
       default:
         throw new RpcError("METHOD_NOT_FOUND", "The requested method does not exist.");
     }
@@ -14535,15 +14936,135 @@ function errorResponse(requestId, error) {
   if (error instanceof external_exports.ZodError) return createRpcError(requestId, "INVALID_MESSAGE", "The RPC parameters are invalid.");
   return createRpcError(requestId, "INTERNAL_ERROR", "The Host could not complete the request.");
 }
-function diagnosticReason2(error) {
+function diagnosticReason3(error) {
   const message = error instanceof Error ? error.message : String(error);
   return message.replace(/[\r\n]+/g, " ").slice(0, 160) || "Unknown Host request failure.";
 }
 
+// src/file-viewer-contract.ts
+var REMOTE_FILE_CHUNK_BYTES = 512 * 1024;
+var MAX_REMOTE_FILE_LOCATOR_CHARS = 4096;
+var MAX_REMOTE_DIRECTORY_ENTRIES = 1e3;
+
+// src/file-viewer-bridge.ts
+var locatorSchema = external_exports.string().min(1).max(MAX_REMOTE_FILE_LOCATOR_CHARS);
+var callSchema = external_exports.discriminatedUnion("endpoint", [
+  external_exports.object({
+    endpoint: external_exports.literal("stat"),
+    payload: external_exports.object({ path: locatorSchema }).strict()
+  }).strict(),
+  external_exports.object({
+    endpoint: external_exports.literal("readRange"),
+    payload: external_exports.object({
+      path: locatorSchema,
+      offset: external_exports.number().int().nonnegative().safe(),
+      length: external_exports.number().int().positive().max(REMOTE_FILE_CHUNK_BYTES)
+    }).strict()
+  }).strict(),
+  external_exports.object({
+    endpoint: external_exports.literal("list"),
+    payload: external_exports.object({ path: locatorSchema }).strict()
+  }).strict()
+]);
+var statResultSchema = external_exports.object({
+  path: locatorSchema,
+  name: external_exports.string().min(1).max(1024),
+  ext: external_exports.string().max(128),
+  mime: external_exports.string().min(1).max(256),
+  size: external_exports.number().int().nonnegative().safe(),
+  mtimeMs: external_exports.number().nonnegative().optional(),
+  isDirectory: external_exports.boolean(),
+  exists: external_exports.boolean()
+}).strict();
+var rangeResultSchema = external_exports.object({
+  data: external_exports.string().max(Math.ceil(REMOTE_FILE_CHUNK_BYTES / 3) * 4 + 4),
+  offset: external_exports.number().int().nonnegative().safe(),
+  size: external_exports.number().int().nonnegative().safe(),
+  eof: external_exports.boolean()
+}).strict();
+var directoryEntrySchema = external_exports.object({
+  name: external_exports.string().min(1).max(1024),
+  path: locatorSchema,
+  isDirectory: external_exports.boolean(),
+  size: external_exports.number().int().nonnegative().safe().optional(),
+  mtimeMs: external_exports.number().nonnegative().optional()
+}).strict();
+var listResultSchema = external_exports.object({
+  path: locatorSchema,
+  entries: external_exports.array(directoryEntrySchema).max(MAX_REMOTE_DIRECTORY_ENTRIES)
+}).strict();
+var RemoteFileViewerBridge = class {
+  constructor(service, logger) {
+    this.service = service;
+    this.logger = logger;
+  }
+  async call(input) {
+    const params = callSchema.parse(input);
+    const service = this.service();
+    if (service === void 0) {
+      throw new RpcError("FILE_VIEWER_UNAVAILABLE", "The Remote Host does not have DSH File Viewer available.");
+    }
+    const startedAt = performance.now();
+    const signal = AbortSignal.timeout(3e4);
+    let raw;
+    try {
+      raw = await service.handle(params.endpoint, params.payload, signal);
+    } catch {
+      this.logger?.warn("remote file viewer service failed", { endpoint: params.endpoint });
+      throw new RpcError("FILE_VIEWER_ERROR", "The Remote File Viewer could not complete the request.");
+    }
+    const result = parseHostResult(raw);
+    if (!result.ok) throw hostFailure(result);
+    try {
+      const value = params.endpoint === "stat" ? statResultSchema.parse(result.value) : params.endpoint === "readRange" ? rangeResultSchema.parse(result.value) : listResultSchema.parse(result.value);
+      this.logger?.debug("remote file viewer call ok", {
+        endpoint: params.endpoint,
+        durationMs: Math.round(performance.now() - startedAt)
+      });
+      return value;
+    } catch (error) {
+      if (error instanceof external_exports.ZodError && params.endpoint === "list" && isOversizedListing(result.value)) {
+        throw new RpcError(
+          "RESPONSE_TOO_LARGE",
+          `The remote directory contains more than ${MAX_REMOTE_DIRECTORY_ENTRIES} entries.`,
+          { maxEntries: MAX_REMOTE_DIRECTORY_ENTRIES },
+          true
+        );
+      }
+      throw error;
+    }
+  }
+};
+function parseHostResult(input) {
+  if (typeof input !== "object" || input === null || !("ok" in input) || typeof input.ok !== "boolean") {
+    throw new RpcError("FILE_VIEWER_INVALID_RESPONSE", "The Remote Host File Viewer returned an invalid response.");
+  }
+  return input;
+}
+function hostFailure(result) {
+  const message = result.error?.message ?? "";
+  if (/access denied/i.test(message)) {
+    return new RpcError("ACCESS_DENIED", "The Remote File Viewer denied access to this locator.");
+  }
+  if (/does not exist|not exist|not found/i.test(message)) {
+    return new RpcError("NOT_FOUND", "The requested remote file does not exist.");
+  }
+  if (result.error?.code === "cancelled") {
+    return new RpcError("CANCELLED", "The Remote File Viewer request was cancelled.", void 0, true);
+  }
+  if (result.error?.code === "bad-request") {
+    return new RpcError("INVALID_MESSAGE", "The Remote File Viewer request is invalid.");
+  }
+  return new RpcError("FILE_VIEWER_ERROR", "The Remote File Viewer could not complete the request.");
+}
+function isOversizedListing(value) {
+  return typeof value === "object" && value !== null && "entries" in value && Array.isArray(value.entries) && value.entries.length > MAX_REMOTE_DIRECTORY_ENTRIES;
+}
+
 // src/server-connection.ts
 var DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS = 8e3;
 var HostServerConnection = class {
-  constructor(config, identity, identities, api, connections, logger, createWebSocket = (url) => new WebSocket(url), rtcFactoryProvider) {
+  constructor(config, identity, identities, api, connections, logger, createWebSocket = (url) => new WebSocket(url), rtcFactoryProvider, hostCapabilities = () => ["harness.api.v1"]) {
     this.config = config;
     this.identity = identity;
     this.identities = identities;
@@ -14552,6 +15073,7 @@ var HostServerConnection = class {
     this.logger = logger;
     this.createWebSocket = createWebSocket;
     this.rtcFactoryProvider = rtcFactoryProvider;
+    this.hostCapabilities = hostCapabilities;
   }
   socket;
   running;
@@ -14675,7 +15197,7 @@ var HostServerConnection = class {
           accessToken: credentials.accessToken,
           protocols: [PROTOCOL_VERSION],
           clientVersion: PLUGIN_VERSION,
-          capabilities: this.rtcFactoryProvider === void 0 || this.config.forceRelay ? ["transport.relay", "harness.api.v1"] : ["transport.p2p", "transport.turn", "transport.relay", "harness.api.v1"]
+          capabilities: this.rtcFactoryProvider === void 0 || this.config.forceRelay ? ["transport.relay", ...this.hostCapabilities()] : ["transport.p2p", "transport.turn", "transport.relay", ...this.hostCapabilities()]
         });
       };
       socket.onmessage = (event) => {
@@ -14701,7 +15223,7 @@ var HostServerConnection = class {
           this.terminalError = code;
           this.logger.error("server control frame failed", {
             code,
-            reason: diagnosticReason3(error)
+            reason: diagnosticReason4(error)
           });
           socket.close(4008, "invalid control frame");
         });
@@ -14850,7 +15372,7 @@ var HostServerConnection = class {
     if (!tunnel.noise.complete) throw new ControlConnectionError("SECURE_CHANNEL_FAILED", "Noise IK handshake did not complete.");
     const viaWebRtc = tunnel.rtc !== void 0 && (tunnel.transport === "p2p" || tunnel.transport === "turn");
     if (!viaWebRtc && tunnel.transport === "negotiating") tunnel.transport = "relay";
-    const mode = viaWebRtc ? tunnel.transport === "turn" ? "TURN" : "P2P" : "Relay";
+    const mode = viaWebRtc ? tunnel.transportMode ?? (tunnel.transport === "turn" ? "TURN" : "P2P") : "Relay";
     const transmit = viaWebRtc ? (ciphertext) => tunnel.rtc.send(ciphertext) : (ciphertext) => this.sendRelay(tunnel, ciphertext);
     const channel = new ServerNoiseChannel(tunnel, transmit, () => {
       if (this.tunnels.get(tunnel.connectionId) === tunnel) this.tunnels.delete(tunnel.connectionId);
@@ -14960,19 +15482,20 @@ var HostServerConnection = class {
   handleRtcOpened(tunnel, selected) {
     if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.rtc === void 0) return;
     tunnel.transport = selected;
+    tunnel.transportMode = tunnel.rtc.selectedPathMode();
     this.sendTransportSelected(tunnel, selected);
     this.logger.info("webrtc data channel ready", {
       connectionId: shortId3(tunnel.connectionId),
       peerDeviceId: shortId3(tunnel.peer.deviceId),
-      transport: selected
+      transport: tunnel.transportMode ?? selected
     });
   }
   async handleRtcFailed(tunnel, rtc, error) {
     if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.rtc !== rtc) return;
-    if (tunnel.channel !== void 0 || tunnel.transport === "p2p" || tunnel.transport === "turn") {
+    if (tunnel.transport === "p2p" || tunnel.transport === "turn") {
       this.logger.warn("webrtc data channel failed; disconnecting peer", {
         connectionId: shortId3(tunnel.connectionId),
-        reason: diagnosticReason3(error)
+        reason: diagnosticReason4(error)
       });
       await this.dropTunnel(tunnel.connectionId, "CONNECTION_FAILED");
       return;
@@ -14982,7 +15505,7 @@ var HostServerConnection = class {
     await rtc.close();
     this.logger.warn("webrtc negotiation failed; falling back to relay", {
       connectionId: shortId3(tunnel.connectionId),
-      reason: diagnosticReason3(error)
+      reason: diagnosticReason4(error)
     });
   }
   sendTransportSelected(tunnel, transport) {
@@ -15026,7 +15549,7 @@ var HostServerConnection = class {
     } catch (error) {
       this.logger.warn("remote connection RTC cleanup failed", {
         connectionId: shortId3(connectionId),
-        reason: diagnosticReason3(error)
+        reason: diagnosticReason4(error)
       });
     }
     if (tunnel.channel !== void 0) {
@@ -15037,7 +15560,7 @@ var HostServerConnection = class {
         await tunnel.channel.close(code).catch(() => void 0);
         this.logger.warn("remote connection channel cleanup failed", {
           connectionId: shortId3(connectionId),
-          reason: diagnosticReason3(error)
+          reason: diagnosticReason4(error)
         });
       }
     } else {
@@ -15205,7 +15728,7 @@ function shortId3(value) {
 function asError2(error) {
   return error instanceof Error ? error : new Error("Unknown Server connection error.");
 }
-function diagnosticReason3(error) {
+function diagnosticReason4(error) {
   const message = asError2(error).message.replace(/[\r\n]+/g, " ").slice(0, 160);
   return message || "Unknown Server connection error.";
 }
@@ -15269,7 +15792,7 @@ function crumbs(path) {
 }
 
 // src/harness-api-bridge.ts
-var callSchema = external_exports.object({
+var callSchema2 = external_exports.object({
   method: external_exports.string().min(1).max(80),
   rpcId: external_exports.string().min(1).max(128),
   payload: external_exports.unknown()
@@ -15361,7 +15884,7 @@ var HarnessApiBridge = class {
   host;
   answer;
   async call(input) {
-    const params = callSchema.parse(input);
+    const params = callSchema2.parse(input);
     const method = this.methods.get(params.method);
     if (method === void 0) throw deniedMethod(params.method);
     const startedAt = performance.now();
@@ -15395,7 +15918,7 @@ var HarnessApiBridge = class {
         method: params.method,
         durationMs,
         timedOut: signal.aborted,
-        reason: diagnosticReason4(error)
+        reason: diagnosticReason5(error)
       });
       throw error;
     }
@@ -15539,7 +16062,7 @@ function domainProperty(wireDomain) {
 function deniedMethod(method) {
   return new RpcError("METHOD_NOT_ALLOWED", `Harness API method ${JSON.stringify(method)} is not available in remote mode.`);
 }
-function diagnosticReason4(error) {
+function diagnosticReason5(error) {
   const message = error instanceof Error ? error.message : String(error);
   return message.replace(/[\r\n]+/g, " ").slice(0, 160) || "Unknown Harness API failure.";
 }
@@ -15618,205 +16141,13 @@ function shortId4(value) {
   return value.length <= 12 ? value : `${value.slice(0, 8)}\u2026${value.slice(-4)}`;
 }
 
-// src/werift-rtc.ts
-import { networkInterfaces } from "node:os";
-var cachedFactory;
-async function loadWeriftFactory() {
-  if (cachedFactory !== void 0) return cachedFactory;
-  try {
-    const werift = await import("werift");
-    cachedFactory = buildWeriftFactory(werift);
-    return cachedFactory;
-  } catch {
-    return void 0;
-  }
-}
-function buildWeriftFactory(werift) {
-  return {
-    create(configuration) {
-      const hostIpv4 = detectHostIpv4();
-      const raw = new werift.RTCPeerConnection({
-        iceServers: configuration.iceServers ?? [],
-        iceUseIpv6: false,
-        iceUseLinkLocalAddress: false,
-        ...hostIpv4 === void 0 ? {} : { iceInterfaceAddresses: { udp4: hostIpv4 } }
-      });
-      let onIceCandidate = null;
-      let onDataChannel = null;
-      raw.onicecandidate = (event) => {
-        if (onIceCandidate === null) return;
-        onIceCandidate({ candidate: event.candidate === void 0 ? null : event.candidate.toJSON() });
-      };
-      raw.ondatachannel = (event) => {
-        if (onDataChannel === null) return;
-        onDataChannel({ channel: adaptDataChannel2(event.channel) });
-      };
-      const pc = {
-        get connectionState() {
-          return raw.connectionState;
-        },
-        get iceConnectionState() {
-          return raw.iceConnectionState;
-        },
-        get iceGatheringState() {
-          return raw.iceGatheringState;
-        },
-        get signalingState() {
-          return raw.signalingState;
-        },
-        set onconnectionstatechange(value) {
-          raw.onconnectionstatechange = value;
-        },
-        get onconnectionstatechange() {
-          return raw.onconnectionstatechange;
-        },
-        set oniceconnectionstatechange(value) {
-          raw.oniceconnectionstatechange = value;
-        },
-        get oniceconnectionstatechange() {
-          return raw.oniceconnectionstatechange;
-        },
-        set onicegatheringstatechange(value) {
-          raw.onicegatheringstatechange = value;
-        },
-        get onicegatheringstatechange() {
-          return raw.onicegatheringstatechange;
-        },
-        set onicecandidate(value) {
-          onIceCandidate = value;
-        },
-        get onicecandidate() {
-          return onIceCandidate;
-        },
-        set ondatachannel(value) {
-          onDataChannel = value;
-        },
-        get ondatachannel() {
-          return onDataChannel;
-        },
-        createDataChannel(label, options) {
-          return adaptDataChannel2(raw.createDataChannel(label, { ordered: options?.ordered ?? true }));
-        },
-        createOffer() {
-          return raw.createOffer();
-        },
-        createAnswer() {
-          return raw.createAnswer();
-        },
-        setLocalDescription(description) {
-          return raw.setLocalDescription(description).then(() => void 0);
-        },
-        setRemoteDescription(description) {
-          return raw.setRemoteDescription(description);
-        },
-        addIceCandidate(candidate) {
-          return raw.addIceCandidate(candidate);
-        },
-        getStats() {
-          return raw.getStats();
-        },
-        close() {
-          void raw.close().catch(() => void 0);
-        }
-      };
-      return pc;
-    }
-  };
-}
-function adaptDataChannel2(raw) {
-  return {
-    get label() {
-      return raw.label;
-    },
-    get ordered() {
-      return raw.ordered;
-    },
-    get readyState() {
-      return raw.readyState;
-    },
-    get bufferedAmount() {
-      return raw.bufferedAmount;
-    },
-    binaryType: "arraybuffer",
-    set onopen(value) {
-      raw.onopen = value;
-    },
-    get onopen() {
-      return raw.onopen;
-    },
-    set onmessage(value) {
-      raw.onmessage = value === null ? null : (event) => value({ data: toArrayBuffer2(event.data) });
-    },
-    get onmessage() {
-      return null;
-    },
-    set onclose(value) {
-      raw.onclose = value;
-    },
-    get onclose() {
-      return raw.onclose;
-    },
-    set onerror(value) {
-      raw.onerror = value;
-    },
-    get onerror() {
-      return raw.onerror;
-    },
-    onbufferedamountlow: null,
-    send(data) {
-      const bytes = typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
-      try {
-        raw.send(typeof data === "string" ? data : Buffer.from(data));
-      } catch (error) {
-        console.error("[werift-send-error] bytes=" + bytes, error instanceof Error ? error.message : error);
-        throw error;
-      }
-    },
-    close() {
-      raw.close();
-    }
-  };
-}
-function toArrayBuffer2(data) {
-  if (typeof data === "string") return data;
-  return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
-}
-function detectHostIpv4() {
-  const preferred = [];
-  const fallback = [];
-  for (const [name2, addresses] of Object.entries(networkInterfaces())) {
-    if (isVirtualInterface(name2)) continue;
-    for (const address of addresses ?? []) {
-      if (address.internal || address.family !== "IPv4") continue;
-      const ip = address.address;
-      if (ip.startsWith("127.") || ip.startsWith("169.254.") || isCgnat(ip)) continue;
-      if (isPrivate(ip)) preferred.push(ip);
-      else fallback.push(ip);
-    }
-  }
-  return preferred[0] ?? fallback[0];
-}
-function isVirtualInterface(name2) {
-  return /^(utun|ppp|bridge|awdl|llw|gif|stf|anpi|ap\d|en[1-9]\d*$)/i.test(name2);
-}
-function isCgnat(ip) {
-  const parts = ip.split(".").map(Number);
-  return parts.length === 4 && parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127;
-}
-function isPrivate(ip) {
-  const parts = ip.split(".").map(Number);
-  if (parts.length !== 4) return false;
-  if (parts[0] === 10) return true;
-  if (parts[0] === 192 && parts[1] === 168) return true;
-  return parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31;
-}
-
 // src/service.ts
 var HostPluginRuntime = class {
-  constructor(config, identities, apiProxy, logger, typertGateway) {
+  constructor(config, identities, apiProxy, logger, typertGateway, fileViewerHost) {
     this.config = config;
     this.identities = identities;
     this.logger = logger;
+    this.fileViewerHost = fileViewerHost;
     this.connections = new ConnectionController(this.identities, (_context, send) => {
       const harnessApi = new HarnessApiBridge(
         apiProxy,
@@ -15825,7 +16156,11 @@ var HostPluginRuntime = class {
         this.logger,
         typertGateway?.()
       );
-      return new RpcRouter(harnessApi, void 0, this.logger);
+      const fileViewer = new RemoteFileViewerBridge(
+        () => this.fileViewerHost?.(),
+        this.logger
+      );
+      return new RpcRouter(harnessApi, void 0, this.logger, fileViewer);
     }, this.logger);
     if (config.serverUrl !== void 0) {
       this.serverApi = new HostServerApi(config.serverUrl, new ServerCredentialStore(identities.directory));
@@ -15962,7 +16297,8 @@ var HostPluginRuntime = class {
       this.connections,
       this.logger,
       void 0,
-      this.config.forceRelay ? void 0 : loadWeriftFactory
+      this.config.forceRelay ? void 0 : loadWeriftFactory,
+      () => this.fileViewerHost?.() === void 0 ? ["harness.api.v1"] : ["harness.api.v1", "fileviewer.read.v1"]
     );
   }
 };
@@ -15970,6 +16306,67 @@ function shortId5(value) {
   return value.length <= 12 ? value : `${value.slice(0, 8)}\u2026${value.slice(-4)}`;
 }
 
+// src/remote-file-content-provider.ts
+function createRemoteFileContentProvider(call) {
+  return {
+    id: "dsh-remote-files",
+    priority: 1e4,
+    supports: () => true,
+    async stat(locator, signal) {
+      const value = await call("fileviewer.stat", { path: locator }, signal);
+      if (!value.exists) return void 0;
+      return {
+        name: value.name,
+        size: value.isDirectory ? 0 : value.size,
+        mime: value.mime,
+        mtimeMs: value.mtimeMs,
+        isDirectory: value.isDirectory
+      };
+    },
+    async read(locator, request) {
+      if (!Number.isInteger(request.offset) || request.offset < 0) throw new Error("A non-negative integer offset is required.");
+      if (!Number.isInteger(request.length) || request.length <= 0) throw new Error("A positive integer length is required.");
+      const chunks = [];
+      let received = 0;
+      while (received < request.length) {
+        request.signal.throwIfAborted();
+        const length = Math.min(REMOTE_FILE_CHUNK_BYTES, request.length - received);
+        const offset = request.offset + received;
+        const range = await call("fileviewer.readRange", { path: locator, offset, length }, request.signal);
+        if (range.offset !== offset) throw new Error("The Remote Host returned a mismatched file range.");
+        const bytes = decodeBase64(range.data);
+        if (bytes.byteLength > length) throw new Error("The Remote Host returned more file bytes than requested.");
+        chunks.push(bytes);
+        received += bytes.byteLength;
+        if (range.eof || bytes.byteLength === 0) break;
+      }
+      const merged = new Uint8Array(received);
+      let cursor = 0;
+      for (const chunk of chunks) {
+        merged.set(chunk, cursor);
+        cursor += chunk.byteLength;
+      }
+      return merged;
+    },
+    async list(locator, signal) {
+      const value = await call("fileviewer.list", { path: locator }, signal);
+      return value.entries.map((entry) => ({
+        locator: entry.path,
+        name: entry.name,
+        size: entry.isDirectory ? 0 : entry.size ?? 0,
+        mtimeMs: entry.mtimeMs,
+        isDirectory: entry.isDirectory
+      }));
+    }
+  };
+}
+function decodeBase64(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
 // src/index.ts
 var name = "dsh-remote";
 function apply(ctx, input = {}) {
@@ -16012,7 +16409,14 @@ async function activate(ctx, input) {
   const connection = ctx.get("connection");
   const nativeTypertGateway = ctx.get("typertGateway");
   const localTypertGateway = new TypertGatewaySwitch(nativeTypertGateway).local();
-  const runtime = new HostPluginRuntime(config, hostIdentities, apiProxy, logger, () => localTypertGateway);
+  const runtime = new HostPluginRuntime(
+    config,
+    hostIdentities,
+    apiProxy,
+    logger,
+    () => localTypertGateway,
+    () => ctx.get("fileViewerHost")
+  );
   let clientRuntime;
   const hostControl = runtime;
   if (config.serverUrl !== void 0 && apiProxy !== void 0 && connection !== void 0) {
@@ -16076,6 +16480,7 @@ export {
   IdentityInvalidError,
   IdentityStore,
   PluginControlRuntime,
+  RemoteFileViewerBridge,
   RemoteHarnessApiProxy,
   RpcError,
   RpcRouter,
@@ -16084,6 +16489,7 @@ export {
   ServerCredentialsInvalidError,
   TypertGatewaySwitch,
   apply,
+  createRemoteFileContentProvider,
   fingerprint,
   name,
   resolveConfig,