@anusornneal/chat-relay 0.7.1 → 0.8.0

package/README.md

@@ -84,6 +84,13 @@ The published package locates its bundled local agent relative to the package it
 - Recovery after retirement does not require copying tokens: run `chat-relay login --force`, complete browser authorization, then run `chat-relay remote`.
 - A different account cannot reclaim another owner's active or retired agent id; a colliding login receives a separate device identity instead.
 
+
+## Agent protocol and capabilities
+
+Local agents send a lightweight hello handshake when their WebSocket connects. The handshake reports the protocol version, package version, platform/architecture, and the capabilities that are actually enabled on that machine. Feature routing should use the advertised capability list rather than inferring support from the package version alone.
+
+Protocol v1 keeps legacy agents backward compatible: a connected agent that does not send hello metadata can still use the pre-handshake behavior. An agent that explicitly advertises an unsupported protocol is disconnected with a clear incompatibility reason instead of failing later on an unrelated tool call or entering a restart loop.
+
 ## Dashboard administrator sessions
 
 Browser dashboard access uses the same Chat Relay username/password accounts but requires an explicit global administrator entitlement. Successful dashboard login creates a short-lived opaque server-side session; the browser receives an HttpOnly, Secure, SameSite=Strict cookie plus a CSRF token for state-changing requests. `ADMIN_TOKEN` remains an operator/CLI recovery credential and must never be embedded in dashboard JavaScript, browser storage, or URLs.
@@ -318,3 +325,26 @@ The first registry publish still requires npm authorization for the @anusornneal
 npx @anusornneal/chat-relay@latest status
 npx @anusornneal/chat-relay@latest remote
 ```
+
+
+### Safe local-agent restart
+
+Agent updates remain explicit and user-controlled. Check the current agent version, protocol compatibility, and lifecycle with `chat-relay status`.
+
+Before restarting an active remote, run `chat-relay drain`. Drain mode rejects new long-running work while existing terminal/session control remains available so bounded work can finish or be stopped safely. When `status` reports the lifecycle is ready to restart, run `chat-relay restart`. Use `chat-relay resume` to cancel a drain before restart.
+
+To install a newer package, stop/restart the wrapper with the desired npm version (for example `npx @anusornneal/chat-relay@latest remote --desktop`). The agent does not self-modify or automatically cross an incompatible protocol version.
+
+
+### Trusted-team security baseline
+
+Chat Relay is currently designed for a small trusted internal team, not as an enterprise zero-trust control plane. The intentionally small baseline is:
+
+- Filesystem access is constrained to configured `allowedRoots`; canonical real paths are checked so `..` traversal and symlink/junction escapes are rejected.
+- Agent grants continue to enforce the existing read/write/process/terminal/desktop scopes. User and agent credentials can be revoked or rotated without retaining raw tokens server-side.
+- Persisted usage/audit/dashboard telemetry is metadata-only. Commands, tool arguments, payloads, stdout/stderr, file contents, clipboard contents, screenshots, credentials, and arbitrary remote messages are excluded.
+- Accidental runaway use is bounded by request/response size limits, rate/quota controls, per-capability queues, queue timeouts, terminal batch limits, and bounded history/query windows.
+
+Regression coverage is provided by the filesystem boundary checks in `test/multiuser-smoke.mjs`, credential/scope tests in the device/admin/multi-user smoke suites, telemetry privacy checks in `test/ops-smoke.mjs`, and queue/size tests in the terminal and filesystem smoke suites.
+
+Deferred by design: enterprise role hierarchies, approval workflows, device-attestation/trust frameworks, and a general policy engine. Add those only if the deployment threat model changes.

package/agent/capability-scheduler.mjs

@@ -0,0 +1,121 @@
+const DEFAULT_QUEUE_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_QUEUED = 64;
+
+function boundedInteger(value, fallback, min, max) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(Math.max(Math.trunc(number), min), max);
+}
+
+function queueError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+export class BoundedLane {
+  constructor(options = {}) {
+    this.name = String(options.name || "lane");
+    this.concurrency = boundedInteger(options.concurrency, 1, 1, 64);
+    this.maxQueued = boundedInteger(options.maxQueued, DEFAULT_MAX_QUEUED, 1, 512);
+    this.queueTimeoutMs = boundedInteger(options.queueTimeoutMs, DEFAULT_QUEUE_TIMEOUT_MS, 100, 120_000);
+    this.active = 0;
+    this.queue = [];
+  }
+
+  run(work) {
+    if (typeof work !== "function") return Promise.reject(queueError("invalid_work"));
+    return new Promise((resolve, reject) => {
+      const job = { work, resolve, reject, timer: null, enqueuedAt: Date.now() };
+      if (this.active < this.concurrency) {
+        this.#start(job);
+        return;
+      }
+      if (this.queue.length >= this.maxQueued) {
+        reject(queueError("queue_full"));
+        return;
+      }
+      job.timer = setTimeout(() => {
+        const index = this.queue.indexOf(job);
+        if (index < 0) return;
+        this.queue.splice(index, 1);
+        reject(queueError("queue_timeout"));
+      }, this.queueTimeoutMs);
+      this.queue.push(job);
+    });
+  }
+
+  snapshot() {
+    return {
+      concurrency: this.concurrency,
+      active: this.active,
+      queued: this.queue.length,
+      maxQueued: this.maxQueued,
+      queueTimeoutMs: this.queueTimeoutMs,
+    };
+  }
+
+  #start(job) {
+    if (job.timer) clearTimeout(job.timer);
+    this.active += 1;
+    const queueWaitMs = Math.max(0, Date.now() - job.enqueuedAt);
+    const metadata = {
+      lane: this.name,
+      queueWaitMs,
+      queueDepthAtStart: this.queue.length,
+      activeAtStart: this.active,
+    };
+    Promise.resolve()
+      .then(() => job.work(metadata))
+      .then(job.resolve, job.reject)
+      .finally(() => {
+        this.active -= 1;
+        this.#drain();
+      });
+  }
+
+  #drain() {
+    while (this.active < this.concurrency && this.queue.length > 0) {
+      this.#start(this.queue.shift());
+    }
+  }
+}
+
+export class CapabilityScheduler {
+  constructor(options = {}) {
+    const maxQueued = boundedInteger(options.maxQueued, DEFAULT_MAX_QUEUED, 1, 512);
+    const queueTimeoutMs = boundedInteger(options.queueTimeoutMs, DEFAULT_QUEUE_TIMEOUT_MS, 100, 120_000);
+    const lane = (name, concurrency) => new BoundedLane({ name, concurrency, maxQueued, queueTimeoutMs });
+
+    this.lanes = new Map([
+      ["agent", lane("agent", options.agentConcurrency ?? 4)],
+      ["filesystem", lane("filesystem", options.fileConcurrency ?? 8)],
+      ["process", lane("process", options.processConcurrency ?? 4)],
+      ["terminalExec", lane("terminalExec", options.terminalExecConcurrency ?? 4)],
+      ["terminalControl", lane("terminalControl", options.terminalControlConcurrency ?? 8)],
+      ["desktopRead", lane("desktopRead", options.desktopReadConcurrency ?? 2)],
+    ]);
+  }
+
+  run(action, work) {
+    const lane = this.#laneFor(action);
+    return lane ? lane.run(work) : Promise.resolve().then(work);
+  }
+
+  snapshot() {
+    return Object.fromEntries([...this.lanes.entries()].map(([name, lane]) => [name, lane.snapshot()]));
+  }
+
+  #laneFor(action) {
+    const value = String(action || "unknown");
+    if (value.startsWith("fs.")) return this.lanes.get("filesystem");
+    if (value.startsWith("process.")) return this.lanes.get("process");
+    if (value === "terminal.exec") return this.lanes.get("terminalExec");
+    if (value.startsWith("terminal.")) return this.lanes.get("terminalControl");
+    if (value === "desktop.screenshot") return this.lanes.get("desktopRead");
+    if (value.startsWith("desktop.")) return null;
+    return this.lanes.get("agent");
+  }
+}
+
+export { boundedInteger };

package/agent/connection-state.mjs

@@ -0,0 +1,126 @@
+function boundedInteger(value, fallback, min, max) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(Math.max(Math.trunc(number), min), max);
+}
+
+function isoTime(value) {
+  const number = Number(value);
+  return new Date(Number.isFinite(number) ? number : Date.now()).toISOString();
+}
+
+function cleanReason(value) {
+  const reason = String(value || "").trim();
+  return reason ? reason.slice(0, 160) : null;
+}
+
+export function computeReconnectDelay(attempt, options = {}) {
+  const baseMs = boundedInteger(options.baseMs, 2000, 100, 60_000);
+  const maxMs = boundedInteger(options.maxMs, 30_000, baseMs, 120_000);
+  const jitterRatio = Math.min(Math.max(Number(options.jitterRatio ?? 0.2), 0), 0.5);
+  const random = typeof options.random === "function" ? options.random : Math.random;
+  const exponent = Math.min(Math.max(Math.trunc(Number(attempt) || 1) - 1, 0), 10);
+  const raw = Math.min(maxMs, baseMs * (2 ** exponent));
+  const spread = raw * jitterRatio;
+  const sample = Math.min(Math.max(Number(random()) || 0, 0), 1);
+  return Math.max(100, Math.round(raw - spread + (spread * 2 * sample)));
+}
+
+export class AgentConnectionState {
+  constructor(options = {}) {
+    this.baseReconnectMs = boundedInteger(options.baseReconnectMs, 2000, 100, 60_000);
+    this.maxReconnectMs = boundedInteger(options.maxReconnectMs, 30_000, this.baseReconnectMs, 120_000);
+    this.heartbeatMs = boundedInteger(options.heartbeatMs, 15_000, 5_000, 60_000);
+    this.processStartedAt = new Date().toISOString();
+    this.state = "starting";
+    this.connectedAt = null;
+    this.disconnectedAt = null;
+    this.lastHeartbeatAt = null;
+    this.lastCloseCode = null;
+    this.lastDisconnectReason = null;
+    this.reconnectAttempt = 0;
+    this.reconnectCount = 0;
+    this.nextReconnectAt = null;
+    this.nextReconnectDelayMs = null;
+  }
+
+  markConnecting(now = Date.now()) {
+    this.state = "connecting";
+    this.nextReconnectAt = null;
+    this.nextReconnectDelayMs = null;
+    this.connectingAt = isoTime(now);
+  }
+
+  markConnected(now = Date.now()) {
+    this.state = "connected";
+    this.connectedAt = isoTime(now);
+    this.disconnectedAt = null;
+    this.reconnectAttempt = 0;
+    this.reconnectCount = 0;
+    this.nextReconnectAt = null;
+    this.nextReconnectDelayMs = null;
+  }
+
+  markHeartbeat(now = Date.now()) {
+    this.lastHeartbeatAt = isoTime(now);
+  }
+
+  markDisconnected(code, reason, now = Date.now()) {
+    this.state = "waiting";
+    this.disconnectedAt = isoTime(now);
+    this.lastCloseCode = Number.isFinite(Number(code)) ? Number(code) : null;
+    this.lastDisconnectReason = cleanReason(reason);
+    this.reconnectAttempt += 1;
+    this.reconnectCount += 1;
+  }
+
+  scheduleReconnect(delayMs, now = Date.now()) {
+    const delay = boundedInteger(delayMs, this.baseReconnectMs, 100, this.maxReconnectMs);
+    this.nextReconnectDelayMs = delay;
+    this.nextReconnectAt = isoTime(Number(now) + delay);
+  }
+
+  nextDelay(random = Math.random) {
+    return computeReconnectDelay(this.reconnectAttempt, {
+      baseMs: this.baseReconnectMs,
+      maxMs: this.maxReconnectMs,
+      random,
+    });
+  }
+
+  markReauthorization(reason = "credential_revoked", now = Date.now()) {
+    this.state = "reauthorization-required";
+    this.disconnectedAt = isoTime(now);
+    this.lastDisconnectReason = cleanReason(reason);
+    this.nextReconnectAt = null;
+    this.nextReconnectDelayMs = null;
+  }
+
+  markStopping(reason = "shutdown", now = Date.now()) {
+    this.state = "stopping";
+    this.disconnectedAt = isoTime(now);
+    this.lastDisconnectReason = cleanReason(reason);
+    this.nextReconnectAt = null;
+    this.nextReconnectDelayMs = null;
+  }
+
+  snapshot() {
+    return {
+      state: this.state,
+      processStartedAt: this.processStartedAt,
+      connectingAt: this.connectingAt ?? null,
+      connectedAt: this.connectedAt,
+      disconnectedAt: this.disconnectedAt,
+      lastHeartbeatAt: this.lastHeartbeatAt,
+      lastCloseCode: this.lastCloseCode,
+      lastDisconnectReason: this.lastDisconnectReason,
+      reconnectAttempt: this.reconnectAttempt,
+      reconnectCount: this.reconnectCount,
+      nextReconnectAt: this.nextReconnectAt,
+      nextReconnectDelayMs: this.nextReconnectDelayMs,
+      baseReconnectMs: this.baseReconnectMs,
+      maxReconnectMs: this.maxReconnectMs,
+      heartbeatMs: this.heartbeatMs,
+    };
+  }
+}