herdr-remote 0.2.12 → 0.2.14

package/herdr-plugin.toml

@@ -1,7 +1,7 @@
 id = "herdr.remote.web"
 name = "Herdr Remote Web"
-version = "0.2.12"
-min_herdr_version = "0.9.0"
+version = "0.2.14"
+min_herdr_version = "0.9.1"
 description = "Browser access to Herdr workspaces via local or self-hosted relay"
 platforms = ["linux", "macos"]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-remote",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "repository": {

package/src/agent-status.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * What the agents on this workstation are doing, small enough to put in a
+ * status bar.
+ *
+ * The question a phone actually has is "does anything need me?", and the
+ * terminal is a poor way to ask it: finding a blocked agent means navigating
+ * Herdr's sidebar through a viewport the width of a hand. Herdr already knows
+ * the answer — it classifies every pane as idle, working, blocked, done or
+ * unknown — so this turns a session snapshot into the two-line version.
+ *
+ * Deliberately a pure function over a snapshot. The socket, the debounce and
+ * the retry live in the host connector; what counts as "needs me" lives here,
+ * where it can be tested without either.
+ */
+
+/** Herdr's own vocabulary, in the order a person cares about them. */
+const AGENT_STATUSES = ['blocked', 'done', 'working', 'idle', 'unknown'];
+
+/**
+ * How many agents travel with the summary.
+ *
+ * The counts are always exact; this caps only the named list, which exists so a
+ * future screen can say *which* agent is blocked. A workstation with more than
+ * this many live agents is not going to be read off a phone anyway.
+ */
+const MAX_LISTED_AGENTS = 16;
+
+/** Titles come from a remote program; keep them short and printable. */
+const MAX_TITLE_LENGTH = 48;
+
+function cleanText(value, limit = MAX_TITLE_LENGTH) {
+  if (typeof value !== 'string') return null;
+  // eslint-disable-next-line no-control-regex
+  const collapsed = value.replace(/[\u0000-\u001F\u007F-\u009F]/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!collapsed) return null;
+  return collapsed.length > limit ? collapsed.slice(0, limit) : collapsed;
+}
+
+function normalizeStatus(value) {
+  return AGENT_STATUSES.includes(value) ? value : 'unknown';
+}
+
+function emptyCounts() {
+  return Object.fromEntries(AGENT_STATUSES.map((status) => [status, 0]));
+}
+
+/**
+ * Turn `session.snapshot` into the summary the browser receives.
+ *
+ * Sorted by how much each status wants attention, so the capped list keeps the
+ * agents worth naming rather than the first ones Herdr happened to report.
+ * `focusedPaneId` and `focusedAgent` also track the live pane selection,
+ * including shells and panes Herdr has not added to its agent summary.
+ */
+function summarizeAgents(snapshot) {
+  const entries = Array.isArray(snapshot?.agents) ? snapshot.agents : [];
+  const focusedPaneId = typeof snapshot?.focused_pane_id === 'string' ? snapshot.focused_pane_id : null;
+  const focusedPane = focusedPaneId && Array.isArray(snapshot?.panes)
+    ? snapshot.panes.find((pane) => pane?.pane_id === focusedPaneId)
+    : null;
+  const focusedAgentEntry = focusedPaneId
+    ? entries.find((entry) => entry?.pane_id === focusedPaneId)
+    : null;
+  const focusedAgent = typeof focusedPane?.agent === 'string'
+    ? focusedPane.agent
+    : typeof focusedAgentEntry?.agent === 'string'
+      ? focusedAgentEntry.agent
+      : null;
+  const counts = emptyCounts();
+  const ranked = [];
+
+  for (const entry of entries) {
+    if (!entry || typeof entry.pane_id !== 'string') continue;
+    const status = normalizeStatus(entry.agent_status);
+    counts[status] += 1;
+    ranked.push({
+      paneId: entry.pane_id,
+      workspaceId: typeof entry.workspace_id === 'string' ? entry.workspace_id : null,
+      agent: cleanText(entry.display_agent || entry.agent, 24),
+      title: cleanText(entry.terminal_title_stripped || entry.terminal_title),
+      status,
+      focused: entry.focused === true,
+    });
+  }
+
+  ranked.sort((left, right) => AGENT_STATUSES.indexOf(left.status) - AGENT_STATUSES.indexOf(right.status));
+
+  return {
+    focusedPaneId,
+    focusedAgent,
+    counts,
+    // Total rather than a sum the browser has to compute, and the one number a
+    // collapsed chip can show on its own.
+    total: ranked.length,
+    agents: ranked.slice(0, MAX_LISTED_AGENTS),
+  };
+}
+
+/** Whether two summaries say the same thing, so an unchanged one is not sent. */
+function sameSummary(left, right) {
+  if (!left || !right) return left === right;
+  if (left.focusedPaneId !== right.focusedPaneId || left.focusedAgent !== right.focusedAgent) return false;
+  if (left.total !== right.total) return false;
+  for (const status of AGENT_STATUSES) {
+    if ((left.counts?.[status] || 0) !== (right.counts?.[status] || 0)) return false;
+  }
+  if (left.agents.length !== right.agents.length) return false;
+  return left.agents.every((agent, index) => {
+    const other = right.agents[index];
+    return other
+      && agent.paneId === other.paneId
+      && agent.status === other.status
+      && agent.agent === other.agent
+      && agent.title === other.title;
+  });
+}
+
+/** The summary of a workstation with nothing to report, or nothing to ask. */
+function emptySummary() {
+  return { focusedPaneId: null, focusedAgent: null, counts: emptyCounts(), total: 0, agents: [] };
+}
+
+module.exports = {
+  AGENT_STATUSES,
+  MAX_LISTED_AGENTS,
+  emptySummary,
+  sameSummary,
+  summarizeAgents,
+};

package/src/herdr-api.js

@@ -0,0 +1,244 @@
+'use strict';
+
+/**
+ * One question for Herdr's local socket API.
+ *
+ * Everything else in this package talks to Herdr by spawning a client into a
+ * PTY and shipping the bytes. That is the terminal. This is the side channel:
+ * the one place that asks Herdr *about* itself rather than drawing it, so a
+ * phone can answer "does anything need me?" without navigating a TUI through a
+ * 40-column viewport.
+ *
+ * The wire format is newline-delimited JSON over the Unix socket:
+ *
+ *   request   {"id":"…","method":"session.snapshot","params":{}}
+ *   response  {"id":"…","result":{…}}  or  {"id":"…","error":{"code","message"}}
+ *
+ * One request per connection, which is why this is a function and not a client.
+ * Herdr closes the socket once it has answered: against 0.9.1 a second request
+ * written to the same connection meets `EPIPE`. A long-lived client that
+ * reconnects on close therefore turns into a connect-answer-close loop about
+ * once a second, busy regardless of how rarely it actually asks anything. The
+ * `herdr` CLI connects per command for the same reason, and so does this.
+ *
+ * Subscriptions are the exception Herdr does keep open — `events.subscribe`
+ * holds the connection. Focus and agent-detection events let the caller refresh
+ * the focused pane immediately, with a slow poll retained as a fallback.
+ *
+ * Nothing here may affect a terminal session. Herdr's server is an ordinary
+ * process that can be restarted under a running herdr-remote, and when it is,
+ * the PTYs keep streaming while this quietly fails and is asked again later.
+ */
+
+const net = require('node:net');
+
+/** How long one question waits, connection included. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/** An answer this long is not an answer. Guards a socket that never newlines. */
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+
+/** A subscription that disappears should recover without keeping a dead socket busy. */
+const SUBSCRIBE_RETRY_BASE_MS = 1_000;
+const SUBSCRIBE_RETRY_MAX_MS = 10_000;
+
+let requestCounter = 0;
+
+/**
+ * Ask Herdr one thing.
+ *
+ * Resolves with the `result` object, rejects for a refused connection, a
+ * timeout, an unparseable answer, or an `error` response — in which case
+ * `error.code` is Herdr's own code.
+ */
+function requestHerdr(socketPath, method, params = {}, options = {}) {
+  const { timeout = REQUEST_TIMEOUT_MS, connect = net.connect } = options;
+  requestCounter += 1;
+  const id = `herdr-remote:${requestCounter}`;
+
+  return new Promise((resolve, reject) => {
+    let socket;
+    let buffer = '';
+    let settled = false;
+
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (socket) {
+        socket.removeAllListeners();
+        socket.destroy();
+      }
+      if (error) reject(error);
+      else resolve(result);
+    };
+
+    const timer = setTimeout(
+      () => finish(new Error(`Herdr API did not answer ${method} in time`)),
+      timeout,
+    );
+    if (typeof timer.unref === 'function') timer.unref();
+
+    try {
+      socket = connect(socketPath);
+    } catch (error) {
+      finish(error);
+      return;
+    }
+
+    socket.setEncoding('utf8');
+    socket.on('connect', () => {
+      socket.write(`${JSON.stringify({ id, method, params })}\n`);
+    });
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      if (buffer.length > MAX_RESPONSE_BYTES) {
+        finish(new Error('Herdr API sent an oversized response'));
+        return;
+      }
+      const newline = buffer.indexOf('\n');
+      if (newline === -1) return;
+      let message;
+      try {
+        message = JSON.parse(buffer.slice(0, newline));
+      } catch {
+        finish(new Error('Herdr API sent a line that is not JSON'));
+        return;
+      }
+      if (message.error) {
+        const error = new Error(message.error.message || 'Herdr API request failed');
+        error.code = message.error.code || 'herdr_api_error';
+        finish(error);
+        return;
+      }
+      finish(null, message.result);
+    });
+    socket.on('error', (error) => finish(error));
+    // Herdr hanging up before it answered is the ordinary shape of "the server
+    // is not running", not something that needs its own diagnosis.
+    socket.on('close', () => finish(new Error(`Herdr API closed before answering ${method}`)));
+  });
+}
+
+/**
+ * Subscribe to Herdr's event stream and reconnect if its local server restarts.
+ *
+ * The initial response is an acknowledgement (`result.type` is
+ * `subscription_started`); later lines are envelopes with `event` and `data`.
+ * They share a socket, but are separate NDJSON messages. A subscription never
+ * starts or writes to a terminal, so an unavailable socket is only a reason to
+ * retry this side channel.
+ */
+function subscribeHerdr(socketPath, subscriptions, onEvent, options = {}) {
+  const {
+    connect = net.connect,
+    retryBaseMs = SUBSCRIBE_RETRY_BASE_MS,
+    retryMaxMs = SUBSCRIBE_RETRY_MAX_MS,
+  } = options;
+  let socket = null;
+  let reconnectTimer = null;
+  let handshakeTimer = null;
+  let retryCount = 0;
+  let closed = false;
+
+  const scheduleReconnect = () => {
+    if (closed || reconnectTimer) return;
+    const delay = Math.min(retryBaseMs * (2 ** retryCount), retryMaxMs);
+    retryCount += 1;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      open();
+    }, delay);
+    if (typeof reconnectTimer.unref === 'function') reconnectTimer.unref();
+  };
+
+  const open = () => {
+    if (closed) return;
+    let current;
+    try {
+      current = connect(socketPath);
+    } catch {
+      scheduleReconnect();
+      return;
+    }
+    socket = current;
+    let buffer = '';
+    let requestId = null;
+    let acknowledged = false;
+    const clearHandshake = () => {
+      if (handshakeTimer) clearTimeout(handshakeTimer);
+      handshakeTimer = null;
+    };
+
+    current.setEncoding('utf8');
+    current.on('connect', () => {
+      requestCounter += 1;
+      requestId = `herdr-remote:subscription:${requestCounter}`;
+      current.write(`${JSON.stringify({
+        id: requestId,
+        method: 'events.subscribe',
+        params: { subscriptions },
+      })}\n`);
+      handshakeTimer = setTimeout(() => current.destroy(), REQUEST_TIMEOUT_MS);
+      if (typeof handshakeTimer.unref === 'function') handshakeTimer.unref();
+    });
+    current.on('data', (chunk) => {
+      buffer += chunk;
+      if (Buffer.byteLength(buffer, 'utf8') > MAX_RESPONSE_BYTES) {
+        current.destroy();
+        return;
+      }
+      let newline;
+      while ((newline = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (!line) continue;
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          current.destroy();
+          return;
+        }
+        if (message?.id === requestId) {
+          clearHandshake();
+          if (message.error) {
+            current.destroy();
+            return;
+          }
+          acknowledged = true;
+          retryCount = 0;
+        } else if (acknowledged && typeof message?.event === 'string' && message.data && typeof message.data === 'object') {
+          try { onEvent(message); } catch {}
+        }
+      }
+    });
+    current.on('error', () => {});
+    current.on('close', () => {
+      clearHandshake();
+      if (socket === current) socket = null;
+      scheduleReconnect();
+    });
+  };
+
+  open();
+  return {
+    close() {
+      if (closed) return;
+      closed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (handshakeTimer) clearTimeout(handshakeTimer);
+      reconnectTimer = null;
+      handshakeTimer = null;
+      const active = socket;
+      socket = null;
+      if (active) active.destroy();
+    },
+  };
+}
+
+module.exports = {
+  REQUEST_TIMEOUT_MS,
+  requestHerdr,
+  subscribeHerdr,
+};

package/src/herdr-command.js

@@ -18,9 +18,25 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+// The same MAJOR.MINOR.PATCH comparison the self-updater uses. A second copy
+// would be a second place for 0.9.10 to sort below 0.9.9.
+const { compareVersions } = require('./updater');
 
 const COMMAND_NAME = 'herdr';
 
+/**
+ * The oldest Herdr this release is written against.
+ *
+ * 0.9.0 gave every client its own view, which is what one PTY per browser
+ * window rests on. 0.9.1 is what makes that model behave: window titles follow
+ * each client's own view instead of another client's selection, activating a
+ * machine in the background stops resizing somebody else's focused pane, and a
+ * large paste no longer disconnects the client — and pasting is how an image
+ * reaches an agent from a phone.
+ */
+const MIN_HERDR_VERSION = '0.9.1';
+
 /** Where a user-level install lands, in the order we trust it. */
 const FALLBACK_DIRECTORIES = [
   '~/.local/bin',
@@ -138,6 +154,57 @@ function verifyHerdrCommand(command, options = {}) {
   return findHerdrCommand(options);
 }
 
+/** `herdr 0.9.1`, `herdr 0.10.0-preview.2` — the three numbers are all we compare. */
+function parseHerdrVersion(output) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(String(output || ''));
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+
+/**
+ * Whether an install is new enough.
+ *
+ * An unreadable version counts as new enough. Not knowing is not evidence of an
+ * old Herdr, and a warning nobody can act on is worse than no warning.
+ */
+function meetsMinimum(version, minimum = MIN_HERDR_VERSION) {
+  if (!version) return true;
+  return compareVersions(version, minimum) >= 0;
+}
+
+/**
+ * Ask an install what it is.
+ *
+ * Deliberately the binary and not the socket: `--version` answers before the
+ * server is up, which is when the TUI and the plugin registration ask.
+ *
+ * `ok` is whether the command ran at all — the presence check registration has
+ * always used. `version` is null whenever the output could not be read, and
+ * `supported` is true in that case for the reason `meetsMinimum` explains.
+ */
+function herdrVersion({ command, timeout = 10_000, ...lookup } = {}) {
+  const resolved = command || resolveHerdrCommand(lookup);
+  const unknown = { command: resolved, version: null, raw: null, supported: true, ok: false };
+  let result;
+  try {
+    result = spawnSync(resolved, ['--version'], { encoding: 'utf8', timeout });
+  } catch {
+    return unknown;
+  }
+  // Status 1 has always counted as present: a binary that answers at all is
+  // installed, whatever it thinks of the flag.
+  if (result.error || (result.status !== 0 && result.status !== 1)) return unknown;
+  const raw = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  const version = parseHerdrVersion(raw);
+  return { command: resolved, version, raw: raw || null, supported: meetsMinimum(version), ok: true };
+}
+
+/** The one line that tells a user why an older Herdr is a problem here. */
+function herdrOutdatedMessage(version) {
+  return `Herdr ${version} is older than ${MIN_HERDR_VERSION}, which herdr-remote is written against. `
+    + 'Run "herdr update" — window titles, background machine activation and large pastes all '
+    + 'misbehave in browser windows before that release.';
+}
+
 /** The one message a user needs to fix a missing install themselves. */
 function herdrNotFoundMessage({ env = process.env, home = os.homedir(), directories = fallbackDirectories(home) } = {}) {
   const override = String(env.HERDR_BIN_PATH || '').trim();
@@ -151,9 +218,14 @@ function herdrNotFoundMessage({ env = process.env, home = os.homedir(), director
 module.exports = {
   COMMAND_NAME,
   FALLBACK_DIRECTORIES,
+  MIN_HERDR_VERSION,
   fallbackDirectories,
   findHerdrCommand,
   herdrNotFoundMessage,
+  herdrOutdatedMessage,
+  herdrVersion,
+  meetsMinimum,
+  parseHerdrVersion,
   resolveHerdrCommand,
   verifyHerdrCommand,
 };

package/src/herdr-plugin.js

@@ -10,7 +10,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { PACKAGE_ROOT } = require('./config');
-const { resolveHerdrCommand } = require('./herdr-command');
+const { herdrVersion, resolveHerdrCommand } = require('./herdr-command');
 
 const PLUGIN_ID = 'herdr.remote.web';
 const MANIFEST_NAME = 'herdr-plugin.toml';
@@ -23,8 +23,7 @@ function manifestPath() {
 // manager, neither of which is guaranteed the PATH the user installed with, so
 // the command is resolved rather than named.
 function herdrAvailable() {
-  const result = spawnSync(resolveHerdrCommand(), ['--version'], { stdio: 'ignore' });
-  return result.status === 0 || result.status === 1;
+  return herdrVersion().ok;
 }
 
 function runHerdr(args, { timeout = 15_000 } = {}) {
@@ -68,6 +67,10 @@ function registrationStatus() {
   if (!fs.existsSync(manifestPath())) {
     return { available: false, registered: false, reason: 'manifest missing' };
   }
+  // Carried on every answer: the screen that shows registration is also the one
+  // that has to say the installed Herdr is too old for this plugin.
+  const { version, supported } = herdrVersion();
+  const installed = { version, versionSupported: supported };
   let result;
   try {
     result = runHerdr(['plugin', 'list']);
@@ -76,11 +79,11 @@ function registrationStatus() {
     throw error;
   }
   if (result.status !== 0) {
-    return { available: true, registered: false, reason: String(result.stderr || '').trim() };
+    return { available: true, registered: false, reason: String(result.stderr || '').trim(), ...installed };
   }
   const plugins = parsePluginList(result.stdout);
   const entry = plugins.find((plugin) => plugin.id === PLUGIN_ID);
-  if (!entry) return { available: true, registered: false, packageRoot: PACKAGE_ROOT };
+  if (!entry) return { available: true, registered: false, packageRoot: PACKAGE_ROOT, ...installed };
   return {
     available: true,
     registered: true,
@@ -90,6 +93,7 @@ function registrationStatus() {
     // switching from a source install to npm.
     stale: Boolean(entry.localPath) && path.resolve(entry.localPath) !== path.resolve(PACKAGE_ROOT),
     packageRoot: PACKAGE_ROOT,
+    ...installed,
   };
 }