herdr-remote 0.2.17 → 0.2.19

package/dist/cli.js

@@ -0,0 +1,255 @@
+// herdr-remote command line: argument parsing and the subcommands.
+//
+// With no arguments (and a real terminal) this opens the configuration TUI;
+// the subcommands exist for scripting and for the actions declared in
+// herdr-plugin.toml, which Herdr runs without a terminal attached.
+import fs from 'node:fs';
+import path from 'node:path';
+import { LANGUAGES, loadConfig, migrateLegacyConfig } from './config.js';
+import { PACKAGE_ROOT, configPath, stateDir } from './paths.js';
+import { extractPairingCode } from './relay-client.js';
+import { resolvePublicUrl } from './relay-urls.js';
+import { createTranslator, detectLocale } from './i18n/index.js';
+import { preferredLanAddress } from './net-interfaces.js';
+const VERSION = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+const USAGE = `herdr-remote ${VERSION} — browser access to Herdr workspaces
+
+Usage: herdr-remote [command] [options]
+
+Commands:
+  (none)               Open the configuration TUI
+  start                Start relay and host connector
+  stop                 Stop services
+  restart              Restart services
+  status [--json]      Show service status
+  pair [--json]        Create pairing code
+  url                  Print browser access URL
+  run [--daemon]       Run services in foreground (keep-alive)
+  keepalive <action>   install | uninstall | restart | status
+  plugin <action>      link | unlink | status  (Herdr plugin)
+
+Options:
+  --lang <zh|en>       Interface language
+  --json               JSON output
+  -h, --help           Show help
+  -v, --version        Show version
+
+Self-hosting: docs/self-hosted-relay.md
+`;
+function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (arg === '--daemon') {
+            flags.daemon = true;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            flags.help = true;
+            continue;
+        }
+        if (arg === '--version' || arg === '-v') {
+            flags.version = true;
+            continue;
+        }
+        if (arg === '--lang') {
+            flags.lang = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--lang=')) {
+            flags.lang = arg.slice('--lang='.length);
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            flags.unknown = arg;
+            continue;
+        }
+        positional.push(arg);
+    }
+    return { positional, flags };
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function describeStatus(status, t) {
+    const lines = [];
+    lines.push(`${t('overview.mode')}: ${t(`mode.${status.mode}`)}`);
+    if (status.relay.local) {
+        lines.push(`${t('overview.relay')}: ${status.relay.alive ? t('common.running') : t('common.stopped')} (${status.relay.bind}:${status.relay.port})`);
+    }
+    else {
+        lines.push(`${t('overview.relay')}: ${status.relay.remoteUrl}`);
+    }
+    lines.push(`${t('overview.host')}: ${status.host.alive ? t('common.running') : t('common.stopped')}`);
+    lines.push(`${t('overview.socket')}: ${status.host.socketPath}${status.host.socketExists ? '' : ` (${t('overview.socketMissing')})`}`);
+    lines.push(`${t('overview.webUrl')}: ${status.publicUrl}`);
+    if (status.keepalive) {
+        const state = status.keepalive.active
+            ? t('common.running')
+            : status.keepalive.installed
+                ? t('common.installed')
+                : t('common.notInstalled');
+        lines.push(`${t('overview.keepalive')}: ${status.keepalive.manager} — ${state}`);
+    }
+    if (status.relay.health && status.relay.health.ok === false) {
+        lines.push(`${t('overview.relay')}: ${t('overview.unreachable', { message: status.relay.health.message ?? '' })}`);
+    }
+    return lines.join('\n');
+}
+async function runTui(options) {
+    const { startTui } = await import('./tui/index.js');
+    await startTui(options);
+}
+async function main(argv = process.argv.slice(2)) {
+    const { positional, flags } = parseArgs(argv);
+    const command = positional[0] || null;
+    // Answered before anything reads the config or queries the terminal.
+    if (flags.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (flags.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    if (flags.unknown) {
+        process.stderr.write(`herdr-remote: unknown option "${flags.unknown}"\n\n${USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    migrateLegacyConfig();
+    // Ask the terminal for its colors while it is still a plain terminal: the
+    // TUI takes the screen a few lines below, and the services this command
+    // starts usually run detached with nothing to ask. Everything downstream
+    // inherits the answer through the environment.
+    (await import('./terminal-palette.js')).captureTerminalPalette();
+    // The font, likewise, is read while this process still knows which terminal
+    // it runs in: its variables and its parent process are gone once a service
+    // manager or Herdr's detached server starts the connector.
+    (await import('./terminal-font/index.js')).captureTerminalFont();
+    const config = loadConfig();
+    const preference = flags.lang && LANGUAGES.includes(flags.lang)
+        ? flags.lang
+        : config.ui.language;
+    const t = createTranslator(detectLocale({ preference }));
+    // Loaded lazily so that the TUI does not pay for loading the
+    // service layer (which pulls in the relay package and node-pty).
+    const lifecycle = await import('./lifecycle.js');
+    const service = await import('./service.js');
+    switch (command) {
+        case null: {
+            if (process.stdin.isTTY && process.stdout.isTTY) {
+                await runTui({ language: flags.lang || null });
+                return;
+            }
+            // Herdr runs plugin panes and actions without a TTY; emit status instead
+            // of trying to paint an interface into a pipe.
+            printJson(await lifecycle.fullStatus(config));
+            return;
+        }
+        case 'start': {
+            const result = lifecycle.startAll(config);
+            if (flags.json)
+                printJson(result);
+            else
+                process.stdout.write(`${t('services.started')}\n${describeStatus(await lifecycle.fullStatus(config), t)}\n`);
+            return;
+        }
+        case 'stop': {
+            const result = lifecycle.stopAll(config);
+            if (flags.json)
+                printJson(result);
+            else
+                process.stdout.write(`${t('services.stopped')}\n`);
+            return;
+        }
+        case 'restart': {
+            const result = lifecycle.restartAll(config);
+            if (flags.json)
+                printJson(result);
+            else
+                process.stdout.write(`${t('services.restarted')}\n`);
+            return;
+        }
+        case 'status': {
+            const status = await lifecycle.fullStatus(config);
+            if (flags.json)
+                printJson(status);
+            else
+                process.stdout.write(`${describeStatus(status, t)}\n`);
+            return;
+        }
+        case 'pair': {
+            const pairing = await service.pair();
+            if (flags.json) {
+                printJson(pairing);
+                return;
+            }
+            const code = extractPairingCode(pairing);
+            const url = pairing.pairUrl ||
+                `${resolvePublicUrl(config, preferredLanAddress())}/?pairCode=${encodeURIComponent(code)}`;
+            const minutes = `${Math.round((config.auth.pairingTtlMs || 600000) / 60000)}m`;
+            process.stdout.write(`${t('pair.code')}: ${code}\n${t('pair.url')}: ${url}\n${t('pair.expires', { minutes, time: new Date(pairing.expiresAt).toLocaleTimeString() })}\n`);
+            return;
+        }
+        case 'url': {
+            process.stdout.write(`${resolvePublicUrl(config, preferredLanAddress())}\n`);
+            return;
+        }
+        case 'run': {
+            const { runForeground } = await import('./supervisor.js');
+            await runForeground({ logToFiles: Boolean(flags.daemon) });
+            return;
+        }
+        case 'keepalive': {
+            const keepalive = await import('./keepalive/index.js');
+            const action = positional[1] || 'status';
+            if (action === 'install')
+                printJson(keepalive.install(config));
+            else if (action === 'uninstall')
+                printJson(keepalive.uninstall(config));
+            else if (action === 'restart')
+                printJson(keepalive.restart(config));
+            else if (action === 'status')
+                printJson(keepalive.status(config));
+            else
+                throw new Error(`unknown keepalive action: ${action}`);
+            return;
+        }
+        case 'plugin': {
+            const plugin = await import('./herdr-plugin.js');
+            const action = positional[1] || 'status';
+            if (action === 'link')
+                printJson(plugin.register());
+            else if (action === 'unlink')
+                printJson(plugin.unregister());
+            else if (action === 'status')
+                printJson(plugin.registrationStatus());
+            else
+                throw new Error(`unknown plugin action: ${action}`);
+            return;
+        }
+        case 'config': {
+            // Handy when reporting a problem: where does this install read from?
+            printJson({ configPath: configPath(), stateDir: stateDir(), config });
+            return;
+        }
+        default:
+            process.stderr.write(`herdr-remote: unknown command "${command}"\n\n${USAGE}`);
+            process.exitCode = 2;
+    }
+}
+/** Runs the command line and reports a failure as the exit code. */
+function run() {
+    main().catch((error) => {
+        process.stderr.write(`herdr-remote: ${error.message}\n`);
+        process.exitCode = 1;
+    });
+}
+export { run, parseArgs, describeStatus };

package/dist/config.js

@@ -0,0 +1,270 @@
+// The configuration file: its shape, its defaults, and how a file on disk,
+// older schemas and the environment become one validated Config.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULTS as RELAY_DEFAULTS } from 'herdr-remote-relay/config';
+import { configPath, legacyConfigPath } from './paths.js';
+import { isLoopbackHost, isUnspecifiedAddress, isUnspecifiedHost, normalizeUrl, } from './relay-urls.js';
+// Access modes
+//   local  — a relay runs on this machine, reachable only from this machine.
+//   lan    — a relay runs on this machine, bound to every interface so other
+//            devices on the LAN (or on a Tailscale/WireGuard overlay) reach it.
+//   remote — no local relay; the host connector dials an operator-run relay,
+//            which is the only way in from outside the local network.
+const ACCESS_MODES = ['local', 'lan', 'remote'];
+// The relay this project runs for people who do not want to host one. Offered
+// as a one-keystroke choice during setup; it is never selected automatically,
+// because routing a terminal through someone else's server has to be a
+// deliberate decision. It is a plain public relay: no join password, and each
+// workstation stays reachable only through its own host token.
+const OFFICIAL_RELAY_URL = 'wss://herdr-remote.564616.xyz';
+const LANGUAGES = ['auto', 'zh', 'en'];
+const KEEPALIVE_MANAGERS = ['auto', 'systemd', 'launchd', 'supervisor', 'none'];
+function isOneOf(list, value) {
+    return list.includes(value);
+}
+const DEFAULTS = {
+    ui: {
+        language: 'auto',
+    },
+    relay: {
+        mode: 'local',
+        port: 8787,
+        // Address advertised in pairing URLs when mode is "lan". Empty means "pick
+        // the first non-internal IPv4 automatically".
+        lanHost: '',
+        // Manual override for the URL browsers open. Empty means "derive it".
+        publicUrl: '',
+        // Operator-run relay, e.g. wss://herdr.example.com (mode "remote" only).
+        remoteUrl: '',
+        // The CLI starts a relay of its own, so its limits are the relay
+        // package's: a smaller ceiling here would reject an upload the hosted
+        // relay accepts.
+        maxPayloadBytes: RELAY_DEFAULTS.relay.maxPayloadBytes,
+        maxClientsPerHost: RELAY_DEFAULTS.relay.maxClientsPerHost,
+        maxHosts: RELAY_DEFAULTS.relay.maxHosts,
+        maxPendingHandshakes: RELAY_DEFAULTS.relay.maxPendingHandshakes,
+        maxBufferedBytesPerClient: RELAY_DEFAULTS.relay.maxBufferedBytesPerClient,
+        hostReconnectGraceMs: RELAY_DEFAULTS.relay.hostReconnectGraceMs,
+        allowedOrigins: [],
+    },
+    herdr: {
+        socketPath: null,
+        args: [],
+        cwd: os.homedir(),
+        // Start Herdr's server when herdr-remote starts (at boot, under keep-alive).
+        // Off: Herdr starts when the user runs it, or confirms it from the WebUI.
+        autoStart: false,
+    },
+    auth: {
+        pairingTtlMs: RELAY_DEFAULTS.auth.pairingTtlMs,
+        deviceTtlMs: RELAY_DEFAULTS.auth.deviceTtlMs,
+        maxDevices: RELAY_DEFAULTS.auth.maxDevices,
+    },
+    cleanup: { ...RELAY_DEFAULTS.cleanup },
+    keepalive: {
+        manager: 'auto',
+    },
+};
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const { code, message } = error;
+        if (code !== 'ENOENT') {
+            process.stderr.write(`herdr-remote: ignoring invalid JSON at ${filePath}: ${message}\n`);
+        }
+        return {};
+    }
+}
+/**
+ * Copy a config written by an older, plugin-scoped install into the canonical
+ * location. Runs at most once: it never overwrites an existing config.
+ */
+function migrateLegacyConfig() {
+    const target = configPath();
+    if (fs.existsSync(target))
+        return { migrated: false, reason: 'config already exists' };
+    const legacy = legacyConfigPath();
+    if (!legacy || !fs.existsSync(legacy))
+        return { migrated: false, reason: 'no legacy config' };
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+        fs.copyFileSync(legacy, target);
+        return { migrated: true, from: legacy, to: target };
+    }
+    catch (error) {
+        return { migrated: false, reason: error.message };
+    }
+}
+function mergeConfig(fileConfig) {
+    const config = clone(DEFAULTS);
+    const file = (fileConfig ?? {});
+    for (const section of Object.keys(config)) {
+        const values = file[section];
+        if (values && typeof values === 'object')
+            Object.assign(config[section], values);
+    }
+    return config;
+}
+/**
+ * Accept configs written before access modes existed. The 0.1 schema used
+ * `relay.local` (boolean), `relay.host` (bind address) and `relay.url`.
+ */
+function normalizeLegacyFields(config, fileConfig) {
+    const legacy = fileConfig?.relay || {};
+    // The absence of an explicit `mode` — not an invalid one — is what marks a
+    // file as pre-0.2, since merging defaults always leaves a valid mode behind.
+    const hasExplicitMode = isOneOf(ACCESS_MODES, legacy.mode);
+    if (!hasExplicitMode) {
+        if (legacy.local === false && typeof legacy.url === 'string' && legacy.url) {
+            config.relay.mode = 'remote';
+            if (!config.relay.remoteUrl)
+                config.relay.remoteUrl = legacy.url;
+        }
+        else if (typeof legacy.host === 'string' && legacy.host && !isLoopbackHost(legacy.host)) {
+            config.relay.mode = 'lan';
+        }
+        else {
+            config.relay.mode = 'local';
+        }
+    }
+    if (config.relay.mode === 'lan' &&
+        !config.relay.lanHost &&
+        typeof legacy.host === 'string' &&
+        !isLoopbackHost(legacy.host) &&
+        legacy.host !== '0.0.0.0') {
+        config.relay.lanHost = legacy.host;
+    }
+    // Superseded keys copied in by the merge would otherwise reappear in the
+    // in-memory config and confuse anything reading it.
+    delete config.relay.local;
+    delete config.relay.host;
+    delete config.relay.url;
+    // `publicUrl` used to be mandatory and defaulted to the loopback URL; treat
+    // that default as "no override" so derivation can take over.
+    if (typeof config.relay.publicUrl === 'string' &&
+        /^https?:\/\/(127\.0\.0\.1|localhost)(:\d+)?\/?$/.test(config.relay.publicUrl)) {
+        config.relay.publicUrl = '';
+    }
+}
+function parseInteger(value, fallback, min, max) {
+    const numeric = Number(value);
+    if (!Number.isInteger(numeric) || numeric < min || numeric > max)
+        return fallback;
+    return numeric;
+}
+function validate(config) {
+    if (!isOneOf(ACCESS_MODES, config.relay.mode))
+        config.relay.mode = DEFAULTS.relay.mode;
+    if (!isOneOf(LANGUAGES, config.ui.language))
+        config.ui.language = DEFAULTS.ui.language;
+    if (!isOneOf(KEEPALIVE_MANAGERS, config.keepalive.manager))
+        config.keepalive.manager = DEFAULTS.keepalive.manager;
+    config.relay.port = parseInteger(config.relay.port, DEFAULTS.relay.port, 1, 65535);
+    config.relay.maxPayloadBytes = parseInteger(config.relay.maxPayloadBytes, DEFAULTS.relay.maxPayloadBytes, 4096, 16 * 1024 * 1024);
+    config.relay.maxClientsPerHost = parseInteger(config.relay.maxClientsPerHost, DEFAULTS.relay.maxClientsPerHost, 1, 256);
+    config.relay.maxHosts = parseInteger(config.relay.maxHosts, DEFAULTS.relay.maxHosts, 1, 100000);
+    config.relay.maxPendingHandshakes = parseInteger(config.relay.maxPendingHandshakes, DEFAULTS.relay.maxPendingHandshakes, 16, 100000);
+    config.relay.maxBufferedBytesPerClient = parseInteger(config.relay.maxBufferedBytesPerClient, DEFAULTS.relay.maxBufferedBytesPerClient, 64 * 1024, 256 * 1024 * 1024);
+    config.relay.hostReconnectGraceMs = parseInteger(config.relay.hostReconnectGraceMs, DEFAULTS.relay.hostReconnectGraceMs, 1000, 24 * 60 * 60 * 1000);
+    config.auth.pairingTtlMs = parseInteger(config.auth.pairingTtlMs, DEFAULTS.auth.pairingTtlMs, 30 * 1000, 24 * 60 * 60 * 1000);
+    config.auth.deviceTtlMs = parseInteger(config.auth.deviceTtlMs, DEFAULTS.auth.deviceTtlMs, 60 * 1000, 365 * 24 * 60 * 60 * 1000);
+    config.auth.maxDevices = parseInteger(config.auth.maxDevices, DEFAULTS.auth.maxDevices, 1, 10000);
+    config.cleanup.intervalMs = parseInteger(config.cleanup.intervalMs, DEFAULTS.cleanup.intervalMs, 1000, 24 * 60 * 60 * 1000);
+    config.cleanup.heartbeatIntervalMs = parseInteger(config.cleanup.heartbeatIntervalMs, DEFAULTS.cleanup.heartbeatIntervalMs, 1000, 10 * 60 * 1000);
+    config.cleanup.staleAfterMs = parseInteger(config.cleanup.staleAfterMs, DEFAULTS.cleanup.staleAfterMs, config.cleanup.heartbeatIntervalMs * 2, 24 * 60 * 60 * 1000);
+    config.relay.publicUrl = normalizeUrl(config.relay.publicUrl);
+    config.relay.remoteUrl = normalizeUrl(config.relay.remoteUrl);
+    config.relay.lanHost =
+        typeof config.relay.lanHost === 'string' ? config.relay.lanHost.trim() : '';
+    // A LAN relay listens on every interface, but a loopback or wildcard value
+    // cannot be opened by another device. Clear stale values from older TUI
+    // versions so the advertised URL falls back to a real interface address.
+    if (config.relay.mode === 'lan' &&
+        (isLoopbackHost(config.relay.lanHost) || isUnspecifiedAddress(config.relay.lanHost))) {
+        config.relay.lanHost = '';
+    }
+    // 0.0.0.0 is a server-side bind wildcard, never a destination a browser can
+    // open. Treat it like an empty override so LAN mode derives the real address.
+    if (isUnspecifiedHost(config.relay.publicUrl))
+        config.relay.publicUrl = '';
+    if (!Array.isArray(config.relay.allowedOrigins))
+        config.relay.allowedOrigins = [];
+    if (!Array.isArray(config.herdr.args) ||
+        !config.herdr.args.every((arg) => typeof arg === 'string')) {
+        config.herdr.args = [];
+    }
+    const args = config.herdr.args;
+    // Herdr 0.9.0 removed --no-session; retaining it in saved configs causes
+    // session creation to fail. Filter it out if present.
+    if (args.includes('--no-session')) {
+        config.herdr.args = args.filter((arg) => arg !== '--no-session');
+        process.stderr.write('herdr-remote: ignoring removed --no-session argument (removed in Herdr 0.9.0)\n');
+    }
+    if (typeof config.herdr.socketPath !== 'string' || config.herdr.socketPath.length === 0) {
+        config.herdr.socketPath = null;
+    }
+    if (typeof config.herdr.cwd !== 'string' || config.herdr.cwd.length === 0) {
+        config.herdr.cwd = os.homedir();
+    }
+    config.herdr.autoStart = config.herdr.autoStart === true;
+    // A "remote" config without a relay URL cannot reach anything; fall back to
+    // local rather than silently starting a host connector that dials nowhere.
+    if (config.relay.mode === 'remote' && !config.relay.remoteUrl) {
+        config.relay.mode = 'local';
+    }
+    // Every field `Config` promises has been normalised above.
+    return config;
+}
+function applyEnvironment(config) {
+    const env = process.env;
+    if (env.HERDR_REMOTE_LANG && isOneOf(LANGUAGES, env.HERDR_REMOTE_LANG))
+        config.ui.language = env.HERDR_REMOTE_LANG;
+    if (env.HERDR_REMOTE_MODE && isOneOf(ACCESS_MODES, env.HERDR_REMOTE_MODE))
+        config.relay.mode = env.HERDR_REMOTE_MODE;
+    if (env.RELAY_PORT)
+        config.relay.port = env.RELAY_PORT;
+    if (env.RELAY_PUBLIC_URL)
+        config.relay.publicUrl = env.RELAY_PUBLIC_URL;
+    if (env.RELAY_REMOTE_URL)
+        config.relay.remoteUrl = env.RELAY_REMOTE_URL;
+    if (env.RELAY_MAX_HOSTS)
+        config.relay.maxHosts = env.RELAY_MAX_HOSTS;
+    if (env.RELAY_MAX_PENDING_HANDSHAKES)
+        config.relay.maxPendingHandshakes = env.RELAY_MAX_PENDING_HANDSHAKES;
+    if (env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT)
+        config.relay.maxBufferedBytesPerClient = env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT;
+    if (env.RELAY_HOST_RECONNECT_GRACE_MS)
+        config.relay.hostReconnectGraceMs = env.RELAY_HOST_RECONNECT_GRACE_MS;
+    if (env.HERDR_SOCKET_PATH)
+        config.herdr.socketPath = env.HERDR_SOCKET_PATH;
+    if (env.HERDR_CWD)
+        config.herdr.cwd = env.HERDR_CWD;
+    if (env.HERDR_ARGS_JSON) {
+        try {
+            const args = JSON.parse(env.HERDR_ARGS_JSON);
+            if (Array.isArray(args))
+                config.herdr.args = args;
+        }
+        catch (error) {
+            process.stderr.write(`herdr-remote: invalid HERDR_ARGS_JSON: ${error.message}\n`);
+        }
+    }
+}
+function loadConfig() {
+    const fileConfig = readJson(configPath());
+    const draft = mergeConfig(fileConfig);
+    normalizeLegacyFields(draft, fileConfig);
+    applyEnvironment(draft);
+    return validate(draft);
+}
+function configExists() {
+    return fs.existsSync(configPath());
+}
+export { DEFAULTS, ACCESS_MODES, OFFICIAL_RELAY_URL, LANGUAGES, KEEPALIVE_MANAGERS, configExists, migrateLegacyConfig, loadConfig, validate, };

package/dist/connector/agent-watch.js

@@ -0,0 +1,110 @@
+// Watching what the agents on this workstation are doing, for the status bar
+// of every window attached to it.
+import { sameSummary, summarizeAgents, } from '../agent-status.js';
+import { requestHerdr, subscribeHerdr, } from '../herdr-api.js';
+/** 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' },
+];
+/**
+ * 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.
+ */
+export class AgentWatch {
+    socketPath;
+    request;
+    subscribe;
+    send;
+    pollTimer = null;
+    debounceTimer = null;
+    subscription = null;
+    pending = false;
+    lastSummary = null;
+    constructor(options, send) {
+        this.socketPath = options.socketPath;
+        this.request = options.requestHerdr || requestHerdr;
+        this.subscribe = options.subscribeHerdr || subscribeHerdr;
+        this.send = send;
+    }
+    start() {
+        if (this.pollTimer)
+            return;
+        this.pollTimer = setInterval(() => this.read(), AGENT_STATUS_POLL_MS);
+        this.pollTimer.unref?.();
+        try {
+            this.subscription = this.subscribe(this.socketPath, AGENT_STATUS_SUBSCRIPTIONS, () => this.scheduleRead());
+        }
+        catch {
+            // A missing or restarting Herdr server leaves the regular poll in place.
+        }
+        this.read();
+    }
+    stop() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.subscription) {
+            this.subscription.close();
+            this.subscription = null;
+        }
+        this.lastSummary = null;
+    }
+    scheduleRead() {
+        if (!this.pollTimer)
+            return;
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            this.read();
+        }, AGENT_STATUS_EVENT_DEBOUNCE_MS);
+        this.debounceTimer.unref?.();
+    }
+    /**
+     * 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 read() {
+        if (this.pending || !this.pollTimer)
+            return;
+        this.pending = true;
+        let snapshot;
+        try {
+            const result = await this.request(this.socketPath, 'session.snapshot', {});
+            snapshot = result?.snapshot || result;
+        }
+        catch {
+            return;
+        }
+        finally {
+            this.pending = false;
+        }
+        // Stopped while the answer was in flight; the browser it was for is gone.
+        if (!this.pollTimer)
+            return;
+        const summary = summarizeAgents(snapshot);
+        if (sameSummary(this.lastSummary, summary))
+            return;
+        this.lastSummary = summary;
+        this.send({ type: 'agent_status', ...summary });
+    }
+}