herdr-remote 0.2.12 → 0.2.14

package/src/host-connector.js

@@ -9,7 +9,13 @@ const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl, stateDir } = require(
 const { ensureDir } = require('./state');
 const { resolveSocketPath, inspectSocket } = require('./socket-discovery');
 const { PtySession } = require('./pty-session');
-const { resolveHerdrCommand, verifyHerdrCommand, herdrNotFoundMessage } = require('./herdr-command');
+const {
+  resolveHerdrCommand,
+  verifyHerdrCommand,
+  herdrNotFoundMessage,
+  herdrOutdatedMessage,
+  herdrVersion,
+} = require('./herdr-command');
 // The wire format lives in the relay package so both ends of the protocol are
 // generated from one definition.
 const {
@@ -20,9 +26,21 @@ const {
   PROTOCOL_VERSION,
 } = require('herdr-remote-relay/protocol');
 const { resolveHostPalette } = require('./terminal-palette');
+const { requestHerdr, subscribeHerdr } = require('./herdr-api');
+const { sameSummary, summarizeAgents } = require('./agent-status');
 const { EXIT_REPLACED, EXIT_AUTH_FAILED } = require('./exit-codes');
 const { savePastedFile, cleanPastedDir } = require('./pasted-files');
 
+/** How often the agent summary is re-read while a browser is watching. */
+const AGENT_STATUS_POLL_MS = 5_000;
+const AGENT_STATUS_EVENT_DEBOUNCE_MS = 150;
+const AGENT_STATUS_SUBSCRIPTIONS = [
+  { type: 'pane.focused' },
+  { type: 'tab.focused' },
+  { type: 'workspace.focused' },
+  { type: 'pane.agent_detected' },
+];
+
 function randomId(prefix) {
   return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
 }
@@ -82,6 +100,8 @@ class HostConnector {
     // real environment unless a caller narrows it.
     this.herdrLookup = options.herdrLookup || {};
     this.herdrCommand = options.herdrCommand || resolveHerdrCommand(this.herdrLookup);
+    this.readHerdrVersion = options.readHerdrVersion || herdrVersion;
+    this.herdrVersionWarned = false;
     this.herdrArgs = options.herdrArgs || config.herdr.args;
     this.cwd = options.cwd || config.herdr.cwd;
     /**
@@ -98,6 +118,14 @@ class HostConnector {
     this.sessions = new Map();
     this.streamIndexToId = new Map();
     this.PtySession = options.PtySession || PtySession;
+    /** The side channel that answers "does anything need me?"; see startAgentStatus. */
+    this.requestHerdr = options.requestHerdr || requestHerdr;
+    this.subscribeHerdr = options.subscribeHerdr || subscribeHerdr;
+    this.agentStatusTimer = null;
+    this.agentStatusDebounceTimer = null;
+    this.agentStatusSubscription = null;
+    this.agentStatusPending = false;
+    this.lastAgentSummary = null;
     this.fastFailures = 0;
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
@@ -169,6 +197,7 @@ class HostConnector {
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
     this.stopKeepalive();
+    this.stopAgentStatus();
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
     sendJson(this.ws, { type: 'host_shutdown' });
@@ -225,6 +254,9 @@ class HostConnector {
       if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
       this.stopKeepalive();
+      // Nothing to report to, so stop asking Herdr. A reconnect brings the
+      // watcher back with the relay's next client count.
+      this.stopAgentStatus();
       this.ready = false;
       this.clientCount = 0;
       this.legacyHeartbeat = false;
@@ -334,11 +366,32 @@ class HostConnector {
     const resolved = verifyHerdrCommand(this.herdrCommand, this.herdrLookup);
     if (resolved.found) {
       this.herdrCommand = resolved.command;
+      this.warnIfHerdrOutdated();
       return null;
     }
     return herdrNotFoundMessage(this.herdrLookup);
   }
 
+  /**
+   * Say once that the installed Herdr is older than this release expects.
+   *
+   * Never a refusal to start. An older Herdr still runs — it just misbehaves in
+   * ways a browser window notices — and the comment on `startSession` explains
+   * what a refused start does to a reconnecting browser.
+   */
+  warnIfHerdrOutdated() {
+    if (this.herdrVersionWarned) return;
+    const installed = this.readHerdrVersion({ command: this.herdrCommand });
+    if (installed.supported) {
+      // A version we could not read is checked again on the next session: the
+      // install may simply not have been finished writing.
+      if (installed.version) this.herdrVersionWarned = true;
+      return;
+    }
+    this.herdrVersionWarned = true;
+    process.stderr.write(`herdr-remote host connector: ${herdrOutdatedMessage(installed.version)}\n`);
+  }
+
   startSession(message) {
     const streamId = typeof message.streamId === 'string' ? message.streamId : message.clientId;
     if (!streamId) return;
@@ -535,6 +588,90 @@ class HostConnector {
       this.heartbeatTimer = null;
       if (wasActive) this.sendHeartbeat(true);
     }
+    // Nobody watching, nothing to ask Herdr about itself.
+    if (next > 0) this.startAgentStatus();
+    else this.stopAgentStatus();
+  }
+
+  /**
+   * Watch what the agents on this workstation are doing.
+   *
+   * A side channel, on its own socket, alive only while a browser is attached.
+   * Herdr's server can be restarted underneath a running herdr-remote — the
+   * PTYs survive it — so every failure here is a retry, never anything a
+   * terminal session notices.
+   *
+   * A long-lived subscription provides fast refreshes on pane and workspace
+   * focus changes; the five-second poll still repairs missed events and a
+   * restarted Herdr server. Both paths only read the side-channel snapshot.
+   */
+  startAgentStatus() {
+    if (this.agentStatusTimer || this.stopping) return;
+    this.agentStatusTimer = setInterval(() => this.readAgentStatus(), AGENT_STATUS_POLL_MS);
+    if (typeof this.agentStatusTimer.unref === 'function') this.agentStatusTimer.unref();
+    try {
+      this.agentStatusSubscription = this.subscribeHerdr(
+        this.socketPath,
+        AGENT_STATUS_SUBSCRIPTIONS,
+        () => this.scheduleAgentStatusRead(),
+      );
+    } catch {
+      // A missing or restarting Herdr server leaves the regular poll in place.
+    }
+    this.readAgentStatus();
+  }
+
+  scheduleAgentStatusRead() {
+    if (!this.agentStatusTimer) return;
+    if (this.agentStatusDebounceTimer) clearTimeout(this.agentStatusDebounceTimer);
+    this.agentStatusDebounceTimer = setTimeout(() => {
+      this.agentStatusDebounceTimer = null;
+      this.readAgentStatus();
+    }, AGENT_STATUS_EVENT_DEBOUNCE_MS);
+    if (typeof this.agentStatusDebounceTimer.unref === 'function') this.agentStatusDebounceTimer.unref();
+  }
+
+  stopAgentStatus() {
+    if (this.agentStatusTimer) {
+      clearInterval(this.agentStatusTimer);
+      this.agentStatusTimer = null;
+    }
+    if (this.agentStatusDebounceTimer) {
+      clearTimeout(this.agentStatusDebounceTimer);
+      this.agentStatusDebounceTimer = null;
+    }
+    if (this.agentStatusSubscription) {
+      this.agentStatusSubscription.close();
+      this.agentStatusSubscription = null;
+    }
+    this.lastAgentSummary = null;
+  }
+
+  /**
+   * Read the summary and forward it if it changed.
+   *
+   * A slow answer must not stack up behind the next tick, and a failed one
+   * leaves the last summary standing rather than blanking the browser's chip:
+   * Herdr's server not running is an ordinary state, not news.
+   */
+  async readAgentStatus() {
+    if (this.agentStatusPending || !this.agentStatusTimer) return;
+    this.agentStatusPending = true;
+    let snapshot;
+    try {
+      const result = await this.requestHerdr(this.socketPath, 'session.snapshot', {});
+      snapshot = result?.snapshot || result;
+    } catch {
+      return;
+    } finally {
+      this.agentStatusPending = false;
+    }
+    // Stopped while the answer was in flight; the browser it was for is gone.
+    if (!this.agentStatusTimer) return;
+    const summary = summarizeAgents(snapshot);
+    if (sameSummary(this.lastAgentSummary, summary)) return;
+    this.lastAgentSummary = summary;
+    sendJson(this.ws, { type: 'agent_status', ...summary });
   }
 
   resizeSession(message) {

package/src/i18n/en.js

@@ -155,6 +155,8 @@ module.exports = {
   'herdr.unregisterDone': 'Plugin unregistered.',
   'herdr.registerFailed': 'Registration failed: {message}',
   'herdr.cliMissing': 'Command herdr not found. Set HERDR_BIN_PATH to its full path.',
+  'herdr.version': 'Herdr version',
+  'herdr.versionOutdated': 'Herdr {version} is older than {minimum}. Run "herdr update": window titles, background machine activation and large pastes misbehave in browser windows before that release.',
 
   'about.title': 'Language & about',
   'about.language': 'Interface language',

package/src/i18n/zh.js

@@ -154,6 +154,8 @@ module.exports = {
   'herdr.unregisterDone': '已取消注册。',
   'herdr.registerFailed': '注册失败：{message}',
   'herdr.cliMissing': '未找到 herdr 命令，可将 HERDR_BIN_PATH 设为其完整路径。',
+  'herdr.version': 'Herdr 版本',
+  'herdr.versionOutdated': 'Herdr {version} 低于 {minimum}，请运行 “herdr update”：在该版本之前，浏览器窗口的标题、后台机器激活与大段粘贴都会出问题。',
 
   'about.title': '语言与关于',
   'about.language': '界面语言',

package/src/service.js

@@ -26,7 +26,7 @@ const {
 } = require('./terminal-palette');
 const { resolveSocketPath } = require('./socket-discovery');
 const { preferredLanAddress } = require('./net-interfaces');
-const { findHerdrCommand, resolveHerdrCommand } = require('./herdr-command');
+const { MIN_HERDR_VERSION, findHerdrCommand, herdrVersion, resolveHerdrCommand } = require('./herdr-command');
 
 const RUNTIME_VERSION = 2;
 
@@ -418,6 +418,9 @@ async function statusServices() {
   // Where Herdr was found, and whether it was found at all: under a service
   // manager this is the first thing to check when sessions will not start.
   const herdr = findHerdrCommand();
+  // Only worth spawning when there is something to spawn; an unresolved command
+  // has already answered the question the version would.
+  const installed = herdr.found ? herdrVersion({ command: herdr.command }) : { version: null, supported: true };
   return {
     ok: true,
     mode: config.relay.mode,
@@ -439,6 +442,9 @@ async function statusServices() {
       herdrCommand: herdr.command,
       herdrCommandFound: herdr.found,
       herdrCommandSource: herdr.source,
+      herdrVersion: installed.version,
+      herdrVersionSupported: installed.supported,
+      herdrVersionMinimum: MIN_HERDR_VERSION,
     },
     publicUrl: resolvePublicUrl(config, lanAddress),
     startedAt: state.startedAt || null,