dshost-plugin 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-remote plugin bundle patch.
+#
+# Intentionally EMPTY: the agent entry (id: dsh-remote-agent) must be declared
+# by the USER's profile cordis.patch.yml, NOT here.
+#
+# Why: cordis applies this file (dsh.bundle.patch) on `dsh plugin add`, and the
+# user profile patch is merged on top. If both declared `- id: dsh-remote-agent`
+# via `- insert:`, the loader saw the same id twice -> duplicate loader entry
+# id -> dsh crashed on startup (systemd restart loop).
+#
+# The plugin is still loaded by cordis because the user profile entry references
+# it by name ('@noeljude/dsh-remote-plugin'); this file only needs to exist for
+# the bundle mechanism.
+[]

package/lib/core.js

@@ -0,0 +1,442 @@
+// Shared agent core used by both the standalone agent (src/agent/dsh-remote.js)
+// and the dsh plugin (src/plugin/lib/index.js). Keeps the two entry points
+// thin so the forwarding/robustness logic cannot drift between them.
+
+import http from 'http';
+import os from 'os';
+import fs from 'fs';
+import { execFileSync } from 'child_process';
+import WebSocket from 'ws';
+import { send, b64, un64, sanitizeCloseCode } from './protocol.js';
+
+// ── Backpressure / robustness limits ─────────────────────────────────
+const MAX_WS_BUFFERED_BYTES = parseInt(process.env.MAX_WS_BUFFERED_BYTES || String(16 * 1024 * 1024), 10);
+const MAX_PENDING_FRAMES = 1024;      // frames buffered while local WS connects
+const LOCAL_WS_CONNECT_TIMEOUT_MS = 15000; // give up if local dsh WS never opens
+const WS_SEND_HIGH_WATER = parseInt(process.env.WS_SEND_HIGH_WATER || String(8 * 1024 * 1024), 10);
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 60000;
+
+/** First non-internal IPv4 of this host (for the dashboard), or null. */
+function localIPv4() {
+  try {
+    for (const addrs of Object.values(os.networkInterfaces())) {
+      for (const a of addrs || []) {
+        if (a.family === 'IPv4' && !a.internal) return a.address;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+// Stable per-process instance id. MUST NOT change across reconnects: the
+// relay binds sessions/tickets to an instanceId, and a random id per
+// registration made the binding go stale the moment the agent reconnected
+// (user saw an offline page for an online host).
+let cachedInstanceId = null;
+function getInstanceId() {
+  if (!cachedInstanceId) {
+    cachedInstanceId = os.hostname() + '-' + Math.random().toString(36).slice(2, 6);
+  }
+  return cachedInstanceId;
+}
+
+/**
+ * Collect every real disk partition (df -kPT), not just the root filesystem.
+ * Filters to physical filesystems (/dev/* or common on-disk types), excludes
+ * tmpfs/proc/sys/overlay etc. Falls back to statfsSync('/') if df is missing
+ * or yields nothing (e.g. minimal containers).
+ */
+function collectDisks() {
+  let disks = [];
+  try {
+    const out = execFileSync('df', ['-kPT'], { encoding: 'utf8' });
+    const lines = out.trim().split('\n');
+    for (let i = 1; i < lines.length; i++) {
+      const parts = lines[i].trim().split(/\s+/);
+      const [dev, type, blocks, used, avail, , mount] = parts;
+      if (!dev || !type || !mount) continue;
+      const isReal = (dev.startsWith('/dev/') && !dev.startsWith('/dev/loop'))
+        || /^(ext[234]|xfs|btrfs|zfs|vfat|ntfs|exfat|hfsplus|apfs|f2fs|jfs|reiserfs)$/.test(type);
+      if (!isReal) continue;
+      disks.push({
+        mount,
+        total: parseInt(blocks || 0) * 1024,
+        used: parseInt(used || 0) * 1024,
+        free: parseInt(avail || 0) * 1024,
+      });
+    }
+  } catch {}
+  // Fallback: single root partition via statfs
+  if (disks.length === 0) {
+    try {
+      const s = fs.statfsSync('/');
+      const total = Number(s.blocks) * Number(s.bsize);
+      const free = Number(s.bavail) * Number(s.bsize);
+      disks = [{ mount: '/', total, used: total - free, free }];
+    } catch {}
+  }
+  return disks;
+}
+
+/** Automatically detect local DSH runtime metadata (version + installed profile plugins with exact versions) */
+function detectDshMetadata() {
+  let dshVersion = '0.1.0-rc.7';
+  let plugins = [];
+  try {
+    const pkg = JSON.parse(fs.readFileSync('/usr/lib/node_modules/@deepseek-ai/dsh/package.json', 'utf8'));
+    if (pkg.version) dshVersion = pkg.version;
+  } catch {}
+  try {
+    const profileDir = os.homedir() + '/.dsh/profiles/web';
+    const profilePkgPath = profileDir + '/package.json';
+    if (fs.existsSync(profilePkgPath)) {
+      const profilePkg = JSON.parse(fs.readFileSync(profilePkgPath, 'utf8'));
+      const deps = Object.keys(profilePkg.dependencies || {});
+      const bundles = profilePkg.dsh?.profile?.bundles || [];
+      const allNames = Array.from(new Set([...bundles, ...deps]));
+
+      plugins = allNames.map(name => {
+        let ver = '';
+        // 1. Check profile node_modules
+        try {
+          const p1 = profileDir + '/node_modules/' + name + '/package.json';
+          if (fs.existsSync(p1)) ver = JSON.parse(fs.readFileSync(p1, 'utf8')).version || '';
+        } catch {}
+        // 2. Check dsh embedded node_modules (for dsh bundles)
+        if (!ver) {
+          try {
+            const p2 = '/usr/lib/node_modules/@deepseek-ai/dsh/node_modules/' + name + '/package.json';
+            if (fs.existsSync(p2)) ver = JSON.parse(fs.readFileSync(p2, 'utf8')).version || '';
+          } catch {}
+        }
+        // 3. Check global node_modules
+        if (!ver) {
+          try {
+            const p3 = '/usr/lib/node_modules/' + name + '/package.json';
+            if (fs.existsSync(p3)) ver = JSON.parse(fs.readFileSync(p3, 'utf8')).version || '';
+          } catch {}
+        }
+        // 4. Fallback to package.json dependency declaration
+        if (!ver && profilePkg.dependencies && profilePkg.dependencies[name]) {
+          ver = String(profilePkg.dependencies[name]).replace(/^[\^~>=<]/, '');
+        }
+        return { name, version: ver ? 'v' + ver : '' };
+      });
+    }
+  } catch {}
+  return { dshVersion, plugins };
+}
+
+/** Collect local system info for the relay dashboard. */
+export function collectSystemInfo(defaultVersion) {
+  const disks = collectDisks();
+  const diskTotal = disks.reduce((a, d) => a + d.total, 0);
+  const diskUsed = disks.reduce((a, d) => a + d.used, 0);
+  const diskFree = disks.reduce((a, d) => a + d.free, 0);
+  const cpus = os.cpus();
+  const meta = detectDshMetadata();
+  return {
+    instanceId: getInstanceId(),
+    hostname: os.hostname(),
+    platform: os.platform(),
+    release: os.release(),
+    arch: os.arch(),
+    ip: localIPv4(),
+    cpuModel: cpus[0]?.model || '',
+    cpuCores: cpus.length,
+    loadAvg: os.loadavg(),
+    totalMem: os.totalmem(),
+    freeMem: os.freemem(),
+    disks,
+    diskTotal,
+    diskUsed,
+    diskFree,
+    dshVersion: defaultVersion || meta.dshVersion,
+    plugins: meta.plugins,
+  };
+}
+
+/**
+ * Start the agent connection loop.
+ * @param {object} opts
+ * @param {string} opts.token        agent registration token
+ * @param {string} opts.relayUrl     relay WebSocket URL (wss:// in production)
+ * @param {string} [opts.version]    agent version reported at registration
+ * @param {string} [opts.dshHost]    local dsh host (default 127.0.0.1)
+ * @param {number} [opts.dshPort]    local dsh port (default 3080)
+ * @param {object} [opts.log]        logger with log/warn/error (default console)
+ * @param {string} [opts.dshVersion] reported dsh version (default rc.6)
+ * @returns {{ stop: () => void }}
+ */
+export function startAgent(opts) {
+  const {
+    token,
+    relayUrl,
+    version = '0.1.0',
+    dshHost = '127.0.0.1',
+    dshPort = 3080,
+    log = console,
+    dshVersion,
+  } = opts;
+
+  if (!token) {
+    log.error?.('[agent] No token configured.');
+    return { stop() {} };
+  }
+  if (process.env.NODE_ENV === 'production' && !relayUrl.startsWith('wss://')) {
+    log.error?.('[agent] FATAL: NODE_ENV=production requires a wss:// relayUrl (got ' + relayUrl + ')');
+    return { stop() {} };
+  }
+
+  const streams = new Map();
+  let registered = false;
+  let reconnectTimer = null;
+  let heartbeatInterval = null;
+  let reconnectAttempt = 0;
+
+  function connect() {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+
+    log.log?.(`[agent] Connecting to ${relayUrl} ...`);
+    const ws = new WebSocket(relayUrl);
+
+    ws.on('open', () => {
+      log.log?.('[agent] Connected to relay');
+      send(ws, { type: 'register', token, version });
+    });
+
+    ws.on('message', (raw) => {
+      let msg;
+      try { msg = JSON.parse(raw.toString()); } catch { return; }
+
+      if (msg.type === 'registered') {
+        registered = true;
+        reconnectAttempt = 0;
+        log.log?.(`[agent] Registered as ${msg.username} (session ${msg.sessionId || ''})`);
+        send(ws, { type: 'system-info', info: collectSystemInfo(dshVersion) });
+        startHeartbeat(ws);
+        return;
+      }
+
+      if (msg.type === 'heartbeat') return;
+
+      if (msg.type === 'http:request') {
+        handleHttpRequest(ws, msg);
+      } else if (msg.type === 'http:body') {
+        const stream = streams.get(msg.streamId);
+        if (stream && stream.dshReq) stream.dshReq.write(un64(msg.data));
+      } else if (msg.type === 'http:end') {
+        const stream = streams.get(msg.streamId);
+        if (stream && stream.dshReq) stream.dshReq.end();
+      } else if (msg.type === 'ws:open') {
+        handleWsOpen(ws, msg);
+      } else if (msg.type === 'ws:frame') {
+        const stream = streams.get(msg.streamId);
+        if (stream && stream.dshWs) {
+          if (stream.dshWs.readyState === WebSocket.OPEN) {
+            if (stream.dshWs.bufferedAmount > MAX_WS_BUFFERED_BYTES) {
+              log.warn?.(`[agent] ws stream ${msg.streamId} slow local consumer, closing`);
+              stream.dshWs.close(1013, 'Slow consumer');
+              send(ws, { type: 'ws:close', streamId, code: 1013, reason: 'Slow consumer' });
+              streams.delete(msg.streamId);
+              return;
+            }
+            if (msg.binary) {
+              stream.dshWs.send(un64(msg.data), { binary: true });
+            } else {
+              stream.dshWs.send(msg.data);
+            }
+          } else if (stream.dshWs.readyState === WebSocket.CONNECTING && stream.pending) {
+            if (stream.pending.length >= MAX_PENDING_FRAMES) {
+              log.warn?.(`[agent] ws stream ${msg.streamId} pending buffer overflow, closing`);
+              stream.dshWs.terminate();
+              send(ws, { type: 'ws:close', streamId, code: 1013, reason: 'Pending overflow' });
+              streams.delete(msg.streamId);
+              return;
+            }
+            stream.pending.push({ data: msg.data, binary: msg.binary });
+          }
+        }
+      } else if (msg.type === 'ws:close') {
+        const stream = streams.get(msg.streamId);
+        if (stream && stream.dshWs) {
+          stream.dshWs.close(sanitizeCloseCode(msg.code), typeof msg.reason === 'string' ? msg.reason : '');
+        }
+        streams.delete(msg.streamId);
+      }
+    });
+
+    ws.on('close', (code, reason) => {
+      log.log?.(`[agent] Disconnected (${code}): ${reason}`);
+      registered = false;
+      for (const [, stream] of streams) {
+        if (stream.dshReq) stream.dshReq.destroy();
+        if (stream.dshWs) stream.dshWs.close();
+      }
+      streams.clear();
+      // Exponential backoff 1s -> 60s with jitter
+      const delay = Math.min(RECONNECT_BASE_MS * Math.pow(2, reconnectAttempt), RECONNECT_MAX_MS) + Math.random() * 1000;
+      reconnectAttempt += 1;
+      log.log?.(`[agent] Reconnecting in ${Math.round(delay / 1000)}s (attempt ${reconnectAttempt}) ...`);
+      reconnectTimer = setTimeout(connect, delay);
+    });
+
+    ws.on('error', (err) => {
+      log.error?.(`[agent] WS Error: ${err.message}`);
+      ws.close();
+    });
+  }
+
+  function startHeartbeat(ws) {
+    if (heartbeatInterval) clearInterval(heartbeatInterval);
+    heartbeatInterval = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN) {
+        send(ws, { type: 'heartbeat', ts: Date.now() });
+      }
+    }, 15000);
+  }
+
+  function handleHttpRequest(ws, msg) {
+    const { streamId, method, path, headers } = msg;
+
+    const dshHeaders = {
+      ...headers,
+      host: `${dshHost}:${dshPort}`,
+      origin: `http://${dshHost}:${dshPort}`,
+    };
+    delete dshHeaders['content-length'];
+
+    const dshReq = http.request({
+      hostname: dshHost,
+      port: dshPort,
+      path,
+      method,
+      headers: dshHeaders,
+    }, (dshRes) => {
+      send(ws, {
+        type: 'http:response',
+        streamId,
+        status: dshRes.statusCode,
+        headers: dshRes.headers,
+      });
+
+      // Backpressure: pause reading from dsh when the relay link is slow.
+      // NOTE: the ws library does NOT emit 'drain' (verified), so resume is
+      // driven by polling bufferedAmount down below the high-water mark —
+      // a once('drain') here would never fire and would deadlock (truncated
+      // responses, hanging browsers).
+      dshRes.on('data', (chunk) => {
+        if (ws.bufferedAmount > WS_SEND_HIGH_WATER) {
+          dshRes.pause();
+          const resumeWhenDrained = () => {
+            if (ws.readyState !== WebSocket.OPEN) return;
+            if (ws.bufferedAmount < WS_SEND_HIGH_WATER / 2) {
+              dshRes.resume();
+            } else {
+              setTimeout(resumeWhenDrained, 50);
+            }
+          };
+          setTimeout(resumeWhenDrained, 50);
+        }
+        send(ws, { type: 'http:data', streamId, data: b64(chunk) });
+      });
+      dshRes.on('end', () => {
+        send(ws, { type: 'http:end-response', streamId });
+        streams.delete(streamId);
+      });
+      dshRes.on('error', () => {
+        send(ws, { type: 'error', streamId, message: 'Local dsh response error' });
+        streams.delete(streamId);
+      });
+    });
+
+    dshReq.on('error', (err) => {
+      log.error?.(`[agent] HTTP Error: ${err.message}`);
+      send(ws, { type: 'error', streamId, message: err.message });
+      streams.delete(streamId);
+    });
+
+    streams.set(streamId, { dshReq, dshRes: null, chunks: [] });
+  }
+
+  function handleWsOpen(ws, msg) {
+    const { streamId, path, headers } = msg;
+    const dshWsUrl = `ws://${dshHost}:${dshPort}${path || '/'}`;
+    log.log?.(`[agent] WS OPEN stream ${streamId} -> ${dshWsUrl}`);
+
+    const options = {
+      headers: {
+        ...headers,
+        host: `${dshHost}:${dshPort}`,
+        origin: `https://${dshHost}:${dshPort}`,
+      },
+      rejectUnauthorized: false,
+    };
+
+    const dshWs = new WebSocket(dshWsUrl, undefined, options);
+    const pending = [];
+
+    const openTimeout = setTimeout(() => {
+      if (dshWs.readyState === WebSocket.CONNECTING) {
+        log.warn?.(`[agent] ws stream ${streamId} local connect timeout`);
+        dshWs.terminate();
+        send(ws, { type: 'error', streamId, message: 'Local websocket connect timeout' });
+        streams.delete(streamId);
+      }
+    }, LOCAL_WS_CONNECT_TIMEOUT_MS);
+
+    dshWs.on('open', () => {
+      clearTimeout(openTimeout);
+      log.log?.(`[agent] WS OPENED stream ${streamId}`);
+      for (const item of pending) {
+        if (item.binary) {
+          dshWs.send(un64(item.data), { binary: true });
+        } else {
+          dshWs.send(item.data);
+        }
+      }
+      pending.length = 0;
+    });
+
+    dshWs.on('message', (data, isBinary) => {
+      if (ws.bufferedAmount > WS_SEND_HIGH_WATER) {
+        log.warn?.(`[agent] relay link slow on stream ${streamId}, dropping frame to protect memory`);
+        return;
+      }
+      send(ws, {
+        type: 'ws:frame',
+        streamId,
+        data: isBinary ? b64(Buffer.from(data)) : data.toString(),
+        binary: isBinary,
+      });
+    });
+
+    dshWs.on('close', (code, reason) => {
+      clearTimeout(openTimeout);
+      send(ws, { type: 'ws:close', streamId, code: sanitizeCloseCode(code), reason: reason?.toString() || '' });
+      streams.delete(streamId);
+    });
+
+    dshWs.on('error', (err) => {
+      clearTimeout(openTimeout);
+      log.error?.(`[agent] WS Error: ${err.message}`);
+      send(ws, { type: 'error', streamId, message: err.message });
+      streams.delete(streamId);
+    });
+
+    streams.set(streamId, { dshWs, pending });
+  }
+
+  connect();
+
+  return {
+    stop() {
+      if (heartbeatInterval) clearInterval(heartbeatInterval);
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+    },
+  };
+}

package/lib/index.js

@@ -0,0 +1,41 @@
+// dsh-remote Plugin for DeepSeek Harness
+// Runs alongside dsh and provides remote access via a relay server.
+// The agent engine lives in ./core.js, generated at pack time from
+// ../../agent/core.js (single source shared with the standalone agent).
+// See scripts/prepack.mjs.
+
+import { startAgent } from './core.js';
+
+// Local dsh instance this plugin proxies (dsh web runs on loopback 3080).
+const DSH_HOST = '127.0.0.1';
+const DSH_PORT = 3080;
+
+// Apply function - called when the plugin is loaded
+export function apply(ctx, config) {
+  const token = config.token || '';
+  const relayUrl = config.relayUrl || process.env.DSH_RELAY_URL || 'wss://relay.example.com/agent';
+  const autoConnect = config.autoConnect !== false;
+  // Local dsh instance this plugin proxies (config-overridable for tests/dev)
+  const dshHost = config.dshHost || process.env.DSH_HOST || '127.0.0.1';
+  const dshPort = parseInt(config.dshPort || process.env.DSH_PORT || '3080', 10);
+
+  console.log('[dsh-remote] Plugin loaded, token:', token ? '***' : 'none');
+
+  if (!token) {
+    console.warn('[dsh-remote] No token configured. Please set token in settings.');
+    return;
+  }
+
+  if (!autoConnect) {
+    console.log('[dsh-remote] Auto-connect disabled.');
+    return;
+  }
+
+  // Start the agent connection (wss enforcement lives in core.js)
+  startAgent({
+    token,
+    relayUrl,
+    dshHost,
+    dshPort,
+  });
+}

package/lib/protocol.js

@@ -0,0 +1,55 @@
+// Shared helpers for the dsh-remote MVP wire protocol.
+//
+// All messages are JSON strings sent over a WebSocket connection.
+// Binary payloads are base64-encoded inside JSON.
+
+export function send(ws, obj) {
+  if (ws.readyState === ws.OPEN) {
+    ws.send(JSON.stringify(obj));
+    return true;
+  }
+  return false;
+}
+
+export function b64(buf) {
+  return Buffer.from(buf).toString('base64');
+}
+
+export function un64(str) {
+  return Buffer.from(str, 'base64');
+}
+
+/**
+ * Normalize a WebSocket close code before passing it to ws.close().
+ * ws throws TypeError on reserved/invalid codes (e.g. 1005 "no status"),
+ * which would crash the process if forwarded unchecked.
+ * Valid: 1000-1014 except 1004/1005/1006, or 3000-4999.
+ */
+export function sanitizeCloseCode(code) {
+  if (typeof code === 'number') {
+    if ((code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006) ||
+        (code >= 3000 && code <= 4999)) {
+      return code;
+    }
+  }
+  return 1000;
+}
+
+// Relay -> Agent
+export const HTTP_REQUEST = 'http:request'; // { streamId, method, path, headers }
+export const HTTP_BODY = 'http:body';        // { streamId, data }
+export const HTTP_END = 'http:end';          // { streamId }
+export const WS_OPEN = 'ws:open';            // { streamId, path, headers }
+export const WS_FRAME = 'ws:frame';          // { streamId, data, binary }
+export const WS_CLOSE = 'ws:close';          // { streamId, code, reason }
+
+// Agent -> Relay
+export const HTTP_RESPONSE = 'http:response'; // { streamId, status, headers }
+export const HTTP_DATA = 'http:data';         // { streamId, data }
+export const HTTP_END_RESPONSE = 'http:end-response'; // { streamId }
+export const ERROR = 'error';                 // { streamId?, message }
+
+// Both
+export const REGISTER = 'register';    // Agent -> Relay: { token, version }
+export const REGISTERED = 'registered'; // Relay -> Agent: { username, sessionId }
+export const HEARTBEAT = 'heartbeat';  // { ts }

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "dshost-plugin",
+  "version": "0.1.0",
+  "description": "Official remote cloud relay plugin for DSHost (dshost.me): securely access your dsh Web UI from anywhere",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "scripts"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack.mjs"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/scripts/prepack.mjs

@@ -0,0 +1,27 @@
+// Prepack build for the dsh-remote plugin package.
+//
+// The plugin and the standalone agent share one engine (src/agent/core.js).
+// npm packages cannot reference files outside the package directory, so this
+// script materializes self-contained copies inside the package at pack time:
+//   lib/core.js     <- src/agent/core.js     (import rewritten to ./protocol.js)
+//   lib/protocol.js <- src/common/protocol.js
+// Run automatically via `npm pack` / `npm publish` (package.json "prepack").
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(here, '..');
+const repoRoot = path.resolve(pkgRoot, '..', '..');
+
+const coreSrc = path.join(repoRoot, 'src', 'agent', 'core.js');
+const protocolSrc = path.join(repoRoot, 'src', 'common', 'protocol.js');
+const coreDest = path.join(pkgRoot, 'lib', 'core.js');
+const protocolDest = path.join(pkgRoot, 'lib', 'protocol.js');
+
+let core = fs.readFileSync(coreSrc, 'utf8');
+// Keep the import inside the package after copying.
+core = core.replace("from '../common/protocol.js'", "from './protocol.js'");
+fs.writeFileSync(coreDest, core);
+fs.copyFileSync(protocolSrc, protocolDest);
+console.log('[prepack] wrote lib/core.js and lib/protocol.js');