@rivalis/fleet 8.0.0

package/lib/FleetAgent.js

@@ -0,0 +1,1217 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/agent/FleetAgent.ts
+var FleetAgent_exports = {};
+__export(FleetAgent_exports, {
+  FleetAgent: () => FleetAgent
+});
+module.exports = __toCommonJS(FleetAgent_exports);
+var import_base = require("@toolcase/base");
+
+// src/agent/Snapshot.ts
+var import_node_crypto2 = require("crypto");
+
+// src/util/canonical.ts
+var import_node_crypto = require("crypto");
+function canonicalize(value) {
+  return encode(value);
+}
+function encode(value) {
+  if (value === null) {
+    return "null";
+  }
+  const type = typeof value;
+  if (type === "string") {
+    return JSON.stringify(value);
+  }
+  if (type === "number") {
+    return Number.isFinite(value) ? String(value) : "null";
+  }
+  if (type === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (type === "bigint") {
+    return value.toString();
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => encodeArrayItem(item));
+    return "[" + items.join(",") + "]";
+  }
+  if (type === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of keys) {
+      const child = obj[key];
+      if (isSkippable(child)) {
+        continue;
+      }
+      parts.push(JSON.stringify(key) + ":" + encode(child));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return "null";
+}
+function encodeArrayItem(item) {
+  return isSkippable(item) ? "null" : encode(item);
+}
+function isSkippable(value) {
+  const type = typeof value;
+  return value === void 0 || type === "function" || type === "symbol";
+}
+function hash64(value) {
+  const digest = (0, import_node_crypto.createHash)("sha256").update(canonicalize(value)).digest();
+  return digest.subarray(0, 8).toString("hex");
+}
+
+// src/util/logger.ts
+var NOOP_LOGGER = {
+  error() {
+  },
+  warning() {
+  },
+  info() {
+  },
+  debug() {
+  },
+  verbose() {
+  },
+  log() {
+  }
+};
+
+// src/util/packageVersion.ts
+var import_node_module = require("module");
+var import_meta = {};
+function packageVersion() {
+  try {
+    const metaUrl = import_meta.url;
+    const req = metaUrl ? (0, import_node_module.createRequire)(metaUrl) : require;
+    const pkg = req("../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// src/wire/topics.ts
+var PROTOCOL_VERSION = 3;
+var WS_SUBPROTOCOL = "rivalis-fleet.v1";
+var Topics = {
+  /** orch → agent: assigns id + heartbeat (poll cadence) on join; followed by the first poll. */
+  hello: "fleet/hello",
+  /** orch → agent: state poll. Carries `knownHash` (dedup) + the last recorded `status` (echo). */
+  poll: "fleet/poll",
+  /** agent → orch: poll reply. Full snapshot when the hash differs from `knownHash`, hash-only otherwise. */
+  state: "fleet/state",
+  /** orch → agent: command push. */
+  cmd: "fleet/cmd",
+  /** agent → orch: command result. */
+  ack: "fleet/ack"
+};
+
+// src/wire/serializer.ts
+var import_node_module2 = require("module");
+var import_meta2 = {};
+var WIRE_MAJOR = PROTOCOL_VERSION;
+var WIRE_MINOR = 0;
+var HEADER_BYTES = 2;
+var WireVersionError = class extends Error {
+  /** The major byte read off the incompatible frame (123 for a legacy JSON `{...}` frame). */
+  theirVersion;
+  /** This build's protocol major. */
+  ourVersion;
+  constructor(theirVersion) {
+    super(
+      `fleet wire protocol version mismatch: peer speaks major v${theirVersion}, this build speaks v${PROTOCOL_VERSION} \u2014 agents and orchestrator must run the same @rivalis/fleet major (\xA77). A v1 (JSON) peer against a v${PROTOCOL_VERSION} peer is exactly this case; upgrade both halves in lockstep.`
+    );
+    this.name = "WireVersionError";
+    this.theirVersion = theirVersion;
+    this.ourVersion = PROTOCOL_VERSION;
+  }
+};
+var Type = {
+  Label: "Label",
+  SyncRoom: "SyncRoom",
+  Capacity: "Capacity",
+  AckRoom: "AckRoom",
+  Hello: "Hello",
+  Poll: "Poll",
+  State: "State",
+  Cmd: "Cmd",
+  Ack: "Ack"
+};
+var TOPIC_TYPE = {
+  [Topics.hello]: Type.Hello,
+  [Topics.poll]: Type.Poll,
+  [Topics.state]: Type.State,
+  [Topics.cmd]: Type.Cmd,
+  [Topics.ack]: Type.Ack
+};
+var serializer = null;
+function getSerializer() {
+  if (serializer !== null) {
+    return serializer;
+  }
+  const metaUrl = import_meta2.url;
+  const req = metaUrl ? (0, import_node_module2.createRequire)(metaUrl) : require;
+  const mod = req("@toolcase/serializer");
+  const Serializer = mod.Serializer ?? mod.default;
+  const F = Serializer.FieldType;
+  const s = new Serializer("fleet");
+  s.define(Type.Label, [
+    { key: "key", type: F.STRING, rule: "optional" },
+    { key: "value", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.SyncRoom, [
+    { key: "id", type: F.STRING, rule: "optional" },
+    { key: "type", type: F.STRING, rule: "optional" },
+    { key: "connections", type: F.UINT32, rule: "optional" },
+    { key: "origin", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Capacity, [
+    // null = unlimited (§6). Absent on the wire ⇒ null; an explicit 0 ⇒ 0.
+    { key: "maxConnections", type: F.INT32, rule: "optional", default: null },
+    { key: "maxRooms", type: F.INT32, rule: "optional", default: null }
+  ]);
+  s.define(Type.AckRoom, [
+    { key: "id", type: F.STRING, rule: "optional" },
+    { key: "type", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Hello, [
+    { key: "instanceId", type: F.STRING, rule: "optional" },
+    { key: "protocolVersion", type: F.UINT32, rule: "optional" },
+    { key: "heartbeatMs", type: F.UINT32, rule: "optional" }
+  ]);
+  s.define(Type.Poll, [
+    { key: "reqId", type: F.STRING, rule: "optional" },
+    // Absent ⇒ null (no prior state / forced full, subsumes the old fleet/resync).
+    { key: "knownHash", type: F.STRING, rule: "optional" },
+    { key: "status", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.State, [
+    { key: "reqId", type: F.STRING, rule: "optional" },
+    // full=false is a hash-only liveness reply: the snapshot fields below are
+    // omitted on the wire (preserving the old sync/ping dedup, orch-initiated).
+    { key: "full", type: F.BOOL, rule: "optional" },
+    { key: "seq", type: F.UINT32, rule: "optional" },
+    { key: "hash", type: F.STRING, rule: "optional" },
+    { key: "name", type: F.STRING, rule: "optional" },
+    { key: "processUid", type: F.STRING, rule: "optional" },
+    { key: "agentVersion", type: F.STRING, rule: "optional" },
+    { key: "protocolVersion", type: F.UINT32, rule: "optional" },
+    { key: "endpointUrl", type: F.STRING, rule: "optional" },
+    { key: "labels", type: Type.Label, rule: "repeated" },
+    { key: "capacity", type: Type.Capacity, rule: "optional" },
+    { key: "autoCreate", type: F.BOOL, rule: "optional" },
+    { key: "roomTypes", type: F.STRING, rule: "repeated" },
+    { key: "rooms", type: Type.SyncRoom, rule: "repeated" },
+    { key: "status", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Cmd, [
+    { key: "cmdId", type: F.STRING, rule: "optional" },
+    { key: "op", type: F.STRING, rule: "optional" },
+    { key: "roomId", type: F.STRING, rule: "optional" },
+    { key: "roomType", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Ack, [
+    { key: "cmdId", type: F.STRING, rule: "optional" },
+    { key: "ok", type: F.BOOL, rule: "optional" },
+    { key: "error", type: F.STRING, rule: "optional" },
+    { key: "alreadyGone", type: F.BOOL, rule: "optional" },
+    { key: "room", type: Type.AckRoom, rule: "optional" },
+    // APPEND-ONLY (task 003): the room-already-exists signal must stay LAST so
+    // existing tags are unmoved (see the append-only tag rule in the file header).
+    { key: "exists", type: F.BOOL, rule: "optional" }
+  ]);
+  serializer = s;
+  return s;
+}
+function present(obj, key) {
+  return obj !== null && obj !== void 0 && Object.prototype.hasOwnProperty.call(obj, key);
+}
+function labelsToList(labels) {
+  return Object.entries(labels ?? {}).map(([key, value]) => ({ key, value }));
+}
+function labelsFromList(list) {
+  const labels = {};
+  for (const entry of list ?? []) {
+    labels[entry.key ?? ""] = entry.value ?? "";
+  }
+  return labels;
+}
+function capacityToMessage(capacity) {
+  return {
+    maxConnections: capacity?.maxConnections ?? null,
+    maxRooms: capacity?.maxRooms ?? null
+  };
+}
+function capacityFromMessage(capacity) {
+  return {
+    // Absent ⇒ null (unlimited, §6); an explicit 0 is preserved as 0.
+    maxConnections: present(capacity, "maxConnections") ? capacity.maxConnections : null,
+    maxRooms: present(capacity, "maxRooms") ? capacity.maxRooms : null
+  };
+}
+function stateToMessage(p) {
+  if (!p.full) {
+    return { reqId: p.reqId, full: false, seq: p.seq, hash: p.hash };
+  }
+  return {
+    reqId: p.reqId,
+    full: true,
+    seq: p.seq,
+    hash: p.hash,
+    name: p.name,
+    processUid: p.processUid,
+    agentVersion: p.agentVersion,
+    protocolVersion: p.protocolVersion,
+    endpointUrl: p.endpointUrl,
+    labels: labelsToList(p.labels),
+    capacity: capacityToMessage(p.capacity),
+    autoCreate: p.autoCreate,
+    roomTypes: p.roomTypes ?? [],
+    rooms: (p.rooms ?? []).map((r) => ({
+      id: r.id,
+      type: r.type,
+      connections: r.connections,
+      origin: r.origin
+    })),
+    status: p.status
+  };
+}
+function stateFromMessage(m) {
+  return {
+    reqId: m.reqId ?? "",
+    full: m.full ?? false,
+    seq: m.seq ?? 0,
+    hash: m.hash ?? "",
+    name: m.name ?? "",
+    processUid: m.processUid ?? "",
+    agentVersion: m.agentVersion ?? "",
+    protocolVersion: m.protocolVersion ?? 0,
+    endpointUrl: m.endpointUrl ?? "",
+    labels: labelsFromList(m.labels),
+    capacity: capacityFromMessage(m.capacity),
+    autoCreate: m.autoCreate ?? false,
+    roomTypes: Array.isArray(m.roomTypes) ? m.roomTypes : [],
+    rooms: (Array.isArray(m.rooms) ? m.rooms : []).map((r) => ({
+      id: r.id ?? "",
+      type: r.type ?? "",
+      connections: r.connections ?? 0,
+      origin: r.origin ?? "local"
+    })),
+    status: m.status ?? "active"
+  };
+}
+function toMessage(topic, payload) {
+  switch (topic) {
+    case Topics.state:
+      return stateToMessage(payload);
+    case Topics.poll: {
+      const p = payload;
+      const msg = { reqId: p.reqId, status: p.status };
+      if (p.knownHash !== null && p.knownHash !== void 0) {
+        msg.knownHash = p.knownHash;
+      }
+      return msg;
+    }
+    default:
+      return payload;
+  }
+}
+function fromMessage(topic, m) {
+  switch (topic) {
+    case Topics.hello:
+      return {
+        instanceId: m.instanceId ?? "",
+        protocolVersion: m.protocolVersion ?? 0,
+        heartbeatMs: m.heartbeatMs ?? 0
+      };
+    case Topics.poll:
+      return {
+        reqId: m.reqId ?? "",
+        // Absent knownHash ⇒ null (no prior state / forced full).
+        knownHash: present(m, "knownHash") ? m.knownHash : null,
+        status: m.status ?? "active"
+      };
+    case Topics.state:
+      return stateFromMessage(m);
+    case Topics.cmd: {
+      const cmd = { cmdId: m.cmdId ?? "", op: m.op };
+      if (present(m, "roomId")) {
+        cmd.roomId = m.roomId;
+      }
+      if (present(m, "roomType")) {
+        cmd.roomType = m.roomType;
+      }
+      return cmd;
+    }
+    case Topics.ack: {
+      const ack = { cmdId: m.cmdId ?? "", ok: m.ok ?? false };
+      if (present(m, "error")) {
+        ack.error = m.error;
+      }
+      if (present(m, "alreadyGone")) {
+        ack.alreadyGone = m.alreadyGone;
+      }
+      if (present(m, "exists")) {
+        ack.exists = m.exists;
+      }
+      if (present(m, "room")) {
+        ack.room = { id: m.room.id ?? "", type: m.room.type ?? "" };
+      }
+      return ack;
+    }
+    default:
+      return m;
+  }
+}
+function encodeFrame(topic, payload) {
+  const type = TOPIC_TYPE[topic];
+  if (type === void 0) {
+    throw new Error(`fleet wire: no message type for topic=${topic}`);
+  }
+  const body = getSerializer().encode(type, toMessage(topic, payload));
+  const frame = new Uint8Array(HEADER_BYTES + body.length);
+  frame[0] = WIRE_MAJOR;
+  frame[1] = WIRE_MINOR;
+  frame.set(body, HEADER_BYTES);
+  return frame;
+}
+function decodeFrame(topic, frame) {
+  const type = TOPIC_TYPE[topic];
+  if (type === void 0) {
+    throw new Error(`fleet wire: no message type for topic=${topic}`);
+  }
+  if (frame === null || frame === void 0 || frame.length < HEADER_BYTES) {
+    throw new Error("fleet wire: truncated frame (shorter than the 2-byte version header)");
+  }
+  const major = frame[0];
+  if (major !== WIRE_MAJOR) {
+    throw new WireVersionError(major);
+  }
+  const body = frame.subarray(HEADER_BYTES);
+  const decoded = getSerializer().decode(type, body);
+  return fromMessage(topic, decoded);
+}
+
+// src/agent/Snapshot.ts
+var MAX_SNAPSHOT_BYTES = 4 * 1024 * 1024;
+var WARN_RATIO = 0.5;
+var ERROR_RATIO = 0.9;
+var MIN_CORE_VERSION = "6.1.0";
+function generateProcessUid() {
+  return "p_" + (0, import_node_crypto2.randomBytes)(12).toString("hex");
+}
+var Snapshot = class {
+  /** Stable per-process id (§6) — constant across reconnects. */
+  processUid;
+  rivalis;
+  logger;
+  name;
+  endpointUrl;
+  labels;
+  capacity;
+  autoCreate;
+  agentVersion;
+  protocolVersion;
+  /** Room ids created in response to `fleet/cmd` → stamped `origin: 'fleet'`. */
+  fleetOrigins = /* @__PURE__ */ new Set();
+  /** Agent owns `status` (§7); flipped via `setStatus`. */
+  statusValue;
+  /** Per-connection monotonic frame counter — defensive hardening only (§7). */
+  seq = 0;
+  constructor(rivalis, options, logger) {
+    this.assertCoreSupport(rivalis);
+    this.rivalis = rivalis;
+    this.logger = logger ?? rivalis.logging?.getLogger?.("fleet:agent") ?? NOOP_LOGGER;
+    this.name = options.name;
+    this.endpointUrl = options.endpointUrl;
+    this.labels = options.labels ?? {};
+    this.capacity = {
+      maxConnections: options.capacity?.maxConnections ?? null,
+      maxRooms: options.capacity?.maxRooms ?? null
+    };
+    this.autoCreate = options.autoCreate ?? true;
+    this.agentVersion = options.agentVersion ?? packageVersion();
+    this.protocolVersion = options.protocolVersion ?? PROTOCOL_VERSION;
+    this.processUid = options.processUid ?? generateProcessUid();
+    this.statusValue = options.status ?? "active";
+  }
+  get status() {
+    return this.statusValue;
+  }
+  /** Flip the agent-owned status (§7). The next snapshot carries the new value. */
+  setStatus(status) {
+    this.statusValue = status;
+  }
+  /** Stamp a room as fleet-created (`origin: 'fleet'`). Called on a `fleet/cmd` create. */
+  markFleetOrigin(roomId) {
+    this.fleetOrigins.add(roomId);
+  }
+  /** Drop provenance for a destroyed room so a future id reuse is not mis-stamped. */
+  forgetRoom(roomId) {
+    this.fleetOrigins.delete(roomId);
+  }
+  /**
+   * New connection (reconnect): reset the `seq` counter. The reconnect assigns a
+   * fresh `instanceId`, so the orchestrator holds no prior hash and its first poll
+   * carries `knownHash: null` → the next reply is always a full snapshot (§7).
+   */
+  resetConnection() {
+    this.seq = 0;
+  }
+  /**
+   * Rebuild the full semantic snapshot from live core state and hash it. Pure:
+   * no `seq`, no size guard, no dedup-state mutation — used for hash inspection
+   * and as the basis for {@link pollReply}.
+   */
+  rebuild() {
+    const content = this.buildContent();
+    return { content, hash: hash64(content) };
+  }
+  /**
+   * Build a `fleet/state` reply to an orchestrator `fleet/poll` (§7, task 011).
+   * The orchestrator drives the dedup: a FULL snapshot when the rebuilt hash
+   * differs from the poll's `knownHash` (or `knownHash` is null — no prior state /
+   * forced full), a hash-only reply otherwise. Always advances `seq`.
+   */
+  pollReply(reqId, knownHash) {
+    const { content, hash } = this.rebuild();
+    const seq = this.nextSeq();
+    if (knownHash !== null && hash === knownHash) {
+      const payload2 = { reqId, full: false, seq, hash, ...content };
+      return { kind: "state", full: false, hash, encodedBytes: 0, payload: payload2 };
+    }
+    const payload = { reqId, full: true, seq, hash, ...content };
+    const encodedBytes = encodeFrame(Topics.state, payload).length;
+    this.checkSize(encodedBytes, content.rooms.length);
+    return { kind: "state", full: true, hash, encodedBytes, payload };
+  }
+  nextSeq() {
+    this.seq += 1;
+    return this.seq;
+  }
+  buildContent() {
+    const manager = this.rivalis.rooms;
+    const roomTypes = [...manager.definitions()].sort();
+    const rooms = [];
+    for (const id of manager.keys()) {
+      const room = manager.get(id);
+      if (room === null) {
+        continue;
+      }
+      if (typeof room.type !== "string") {
+        throw new Error(this.coreSupportError(`room id=(${id}) has no string \`type\``));
+      }
+      rooms.push({
+        id,
+        type: room.type,
+        connections: room.actorCount,
+        origin: this.fleetOrigins.has(id) ? "fleet" : "local"
+      });
+    }
+    rooms.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return {
+      name: this.name,
+      processUid: this.processUid,
+      agentVersion: this.agentVersion,
+      protocolVersion: this.protocolVersion,
+      endpointUrl: this.endpointUrl,
+      labels: this.labels,
+      capacity: this.capacity,
+      autoCreate: this.autoCreate,
+      roomTypes,
+      rooms,
+      status: this.statusValue
+    };
+  }
+  checkSize(bytes, roomCount) {
+    const pct = Math.round(bytes / MAX_SNAPSHOT_BYTES * 100);
+    if (bytes >= MAX_SNAPSHOT_BYTES * ERROR_RATIO) {
+      this.logger.error(
+        `fleet snapshot at ${pct}% of the 4 MiB transport frame limit (${bytes} bytes, ${roomCount} rooms). An oversized snapshot is terminated by the transport, which causes a permanent reconnect loop. Remediation: host fewer rooms per instance, raise the orchestrator's WSTransport.maxPayload, or split the fleet across more instances (chunked sync is roadmap \xA716).`
+      );
+    } else if (bytes >= MAX_SNAPSHOT_BYTES * WARN_RATIO) {
+      this.logger.warning(
+        `fleet snapshot at ${pct}% of the 4 MiB transport frame limit (${bytes} bytes, ${roomCount} rooms) \u2014 approaching the size guard.`
+      );
+    }
+  }
+  /**
+   * Feature-detect the §4 core additions and throw an actionable, version-naming
+   * error when they are absent — a clean failure at startup instead of
+   * `undefined` types in snapshots at runtime. `Room.type` can only be checked
+   * against rooms that already exist; with zero rooms the `definitions()` gate
+   * is the primary guard (and `buildContent` re-checks each room defensively).
+   */
+  assertCoreSupport(rivalis) {
+    const manager = rivalis?.rooms;
+    if (manager === void 0 || manager === null) {
+      throw new Error(this.coreSupportError("rivalis.rooms is not available"));
+    }
+    if (typeof manager.definitions !== "function") {
+      throw new Error(this.coreSupportError("rivalis.rooms.definitions() is not available"));
+    }
+    if (typeof manager.keys !== "function" || typeof manager.get !== "function") {
+      throw new Error(this.coreSupportError("rivalis.rooms.keys()/get() are not available"));
+    }
+    for (const id of manager.keys()) {
+      const room = manager.get(id);
+      if (room !== null && typeof room.type !== "string") {
+        throw new Error(this.coreSupportError(`Room.type is not available (room id=(${id}) has no string \`type\`)`));
+      }
+    }
+  }
+  coreSupportError(detail) {
+    return `@rivalis/fleet requires @rivalis/core >= ${MIN_CORE_VERSION}: ${detail}. Upgrade @rivalis/core to >= ${MIN_CORE_VERSION} (the \xA74 additions: Room.type, RoomManager.definitions()).`;
+  }
+};
+
+// src/util/errors.ts
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/agent/FleetAgent.ts
+var import_node = require("@rivalis/node");
+
+// src/util/scheduler.ts
+var defaultScheduler = {
+  setTimeout: (fn, ms) => {
+    const t = setTimeout(fn, ms);
+    t.unref?.();
+    return t;
+  },
+  clearTimeout: (h) => clearTimeout(h),
+  setInterval: (fn, ms) => {
+    const t = setInterval(fn, ms);
+    t.unref?.();
+    return t;
+  },
+  clearInterval: (h) => clearInterval(h)
+};
+
+// src/agent/FleetAgent.ts
+var DEFAULT_BACKOFF_BASE_MS = 500;
+var DEFAULT_BACKOFF_CAP_MS = 3e4;
+var DEFAULT_AWAIT_EMPTY_POLL_MS = 200;
+function defaultCreateClient(url) {
+  return new import_node.WSClient(url, {
+    ticketSource: "protocol",
+    subprotocols: [WS_SUBPROTOCOL]
+  });
+}
+var FleetAgent = class extends import_base.Broadcast {
+  rivalis;
+  logger;
+  snapshot;
+  url;
+  key;
+  autoCreate;
+  maxRooms;
+  connectTimeoutMs;
+  client;
+  scheduler;
+  random;
+  backoffBaseMs;
+  backoffCapMs;
+  awaitEmptyPollMs;
+  installSignalHandlers;
+  lifecycle = "closed";
+  instanceId = null;
+  /** Set once `connect()`/reconnects should stop (intentional `disconnect()` or fatal error). */
+  closed = false;
+  /** Distinguishes an operator-driven close from a transport drop that should reconnect. */
+  intentionalClose = false;
+  reconnectTimer = null;
+  connectDeadline = null;
+  reconnectAttempt = 0;
+  connectResolve = null;
+  connectReject = null;
+  /**
+   * Pending `drain()` / `undrain()` promises (task 011): each waits for a
+   * `fleet/poll` echoing its target status — the orchestrator's acknowledged
+   * confirmation that it recorded the agent-owned status flip. No unsolicited frame.
+   */
+  pendingStatus = [];
+  uninstallSignals = null;
+  /**
+   * Whether the room/transport listeners are currently attached (task 008). The
+   * subscription lifecycle tracks the connection lifecycle: attached on construct
+   * and on every `connect()`, detached on the terminal paths (`disconnect()`,
+   * `failConnect()`) so a discarded/replaced agent stops reacting to room events
+   * and the host can drop it (otherwise `RoomManager`'s broadcast retains it).
+   */
+  listenersAttached = false;
+  /**
+   * Drop provenance when a room is destroyed so a future id reuse is not mis-stamped
+   * (§7). Room create/destroy/define no longer trigger a push — changes surface at
+   * the next orchestrator poll (task 011).
+   */
+  onRoomDestroy = (roomId) => {
+    this.snapshot.forgetRoom(roomId);
+  };
+  constructor(rivalis, options, internals = {}) {
+    super();
+    this.rivalis = rivalis;
+    this.logger = rivalis.logging?.getLogger?.("fleet:agent") ?? NOOP_LOGGER;
+    const snapshotOptions = {
+      name: options.name,
+      endpointUrl: options.endpointUrl,
+      agentVersion: packageVersion()
+    };
+    if (options.labels !== void 0) {
+      snapshotOptions.labels = options.labels;
+    }
+    if (options.capacity !== void 0) {
+      snapshotOptions.capacity = options.capacity;
+    }
+    if (options.autoCreate !== void 0) {
+      snapshotOptions.autoCreate = options.autoCreate;
+    }
+    this.snapshot = new Snapshot(rivalis, snapshotOptions, this.logger);
+    this.url = options.url;
+    this.key = options.key;
+    this.autoCreate = options.autoCreate ?? true;
+    this.maxRooms = options.capacity?.maxRooms ?? null;
+    this.connectTimeoutMs = options.connectTimeoutMs;
+    this.scheduler = internals.scheduler ?? defaultScheduler;
+    this.random = internals.random ?? Math.random;
+    this.backoffBaseMs = internals.backoff?.baseMs ?? DEFAULT_BACKOFF_BASE_MS;
+    this.backoffCapMs = internals.backoff?.capMs ?? DEFAULT_BACKOFF_CAP_MS;
+    this.awaitEmptyPollMs = internals.awaitEmptyPollMs ?? DEFAULT_AWAIT_EMPTY_POLL_MS;
+    this.installSignalHandlers = internals.installSignalHandlers;
+    this.client = (internals.createClient ?? defaultCreateClient)(this.url);
+    this.attachListeners();
+  }
+  /** Lifecycle status (§8): `'connecting' | 'connected' | 'draining' | 'closed'`. */
+  get status() {
+    return this.lifecycle;
+  }
+  /** Stable per-process id (§6), constant across reconnects. */
+  get processUid() {
+    return this.snapshot.processUid;
+  }
+  /**
+   * Connect to the orchestrator; resolves on the first `fleet/hello`. Default:
+   * retries forever (backoff per §7) — the promise stays pending while the
+   * orchestrator is unreachable. With `connectTimeoutMs` set, rejects after the
+   * deadline and transitions to `'closed'` with no background retry loop (§8).
+   */
+  connect() {
+    if (this.lifecycle === "connected" || this.lifecycle === "draining") {
+      return Promise.resolve();
+    }
+    if (this.connectResolve !== null) {
+      return new Promise((resolve, reject) => {
+        const prevResolve = this.connectResolve;
+        const prevReject = this.connectReject;
+        this.connectResolve = () => {
+          prevResolve();
+          resolve();
+        };
+        this.connectReject = (e) => {
+          prevReject(e);
+          reject(e);
+        };
+      });
+    }
+    this.closed = false;
+    this.intentionalClose = false;
+    this.lifecycle = "connecting";
+    this.reconnectAttempt = 0;
+    this.attachListeners();
+    return new Promise((resolve, reject) => {
+      this.connectResolve = resolve;
+      this.connectReject = reject;
+      if (this.connectTimeoutMs !== void 0) {
+        this.connectDeadline = this.scheduler.setTimeout(
+          () => this.failConnect(new Error("fleet:agent connect timeout exceeded")),
+          this.connectTimeoutMs
+        );
+      }
+      this.openConnection();
+    });
+  }
+  /**
+   * Mark this instance draining (§7, task 011): flips the agent-owned status
+   * immediately (so the next `fleet/state` reply carries it) and resolves only when
+   * a subsequent `fleet/poll` echoes `status: 'draining'` — the orchestrator's
+   * acknowledged confirmation that it recorded the flip. No unsolicited frame.
+   */
+  drain() {
+    return this.requestStatus("draining");
+  }
+  /** Reverse of `drain()` — restore the instance to `active`; resolves on the poll echo (§7). */
+  undrain() {
+    return this.requestStatus("active");
+  }
+  /** Resolve once every local room is empty (zero connections), or reject on `timeoutMs` (§8). */
+  awaitEmpty({ timeoutMs } = {}) {
+    const empty = () => {
+      for (const id of this.rivalis.rooms.keys()) {
+        const room = this.rivalis.rooms.get(id);
+        if (room !== null && room.actorCount > 0) {
+          return false;
+        }
+      }
+      return true;
+    };
+    if (empty()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      let poll = null;
+      let deadline = null;
+      const cleanup = () => {
+        if (poll !== null) {
+          this.scheduler.clearInterval(poll);
+          poll = null;
+        }
+        if (deadline !== null) {
+          this.scheduler.clearTimeout(deadline);
+          deadline = null;
+        }
+      };
+      poll = this.scheduler.setInterval(() => {
+        if (empty()) {
+          cleanup();
+          resolve();
+        }
+      }, this.awaitEmptyPollMs);
+      if (timeoutMs !== void 0) {
+        deadline = this.scheduler.setTimeout(() => {
+          cleanup();
+          reject(new Error("fleet:agent awaitEmpty timeout exceeded"));
+        }, timeoutMs);
+      }
+    });
+  }
+  /** Detach cleanly: stop all timers, close the transport, no further reconnects (§8). */
+  async disconnect() {
+    this.intentionalClose = true;
+    this.closed = true;
+    this.clearAllTimers();
+    this.rejectPendingStatus(new Error("fleet:agent disconnected"));
+    try {
+      this.client.disconnect();
+    } catch (error) {
+      this.logger.warning(`fleet:agent transport disconnect error: ${describe(error)}`);
+    }
+    this.detachListeners();
+    this.lifecycle = "closed";
+    if (this.connectReject !== null) {
+      const reject = this.connectReject;
+      this.connectResolve = null;
+      this.connectReject = null;
+      reject(new Error("fleet:agent disconnected before connect resolved"));
+    }
+    this.emit("disconnect", Buffer.from("closed"));
+  }
+  /**
+   * Wire `SIGTERM`/`SIGINT` to the graceful sequence (§8):
+   * drain → awaitEmpty → disconnect → `rivalis.shutdown()`.
+   */
+  enableGracefulShutdown({ emptyTimeoutMs = 6e4 } = {}) {
+    if (this.uninstallSignals !== null) {
+      this.uninstallSignals();
+      this.uninstallSignals = null;
+    }
+    const handler = () => {
+      void this.gracefulShutdown(emptyTimeoutMs);
+    };
+    if (this.installSignalHandlers !== void 0) {
+      this.uninstallSignals = this.installSignalHandlers(handler);
+      return;
+    }
+    process.once("SIGTERM", handler);
+    process.once("SIGINT", handler);
+    this.uninstallSignals = () => {
+      process.removeListener("SIGTERM", handler);
+      process.removeListener("SIGINT", handler);
+    };
+  }
+  async gracefulShutdown(emptyTimeoutMs) {
+    try {
+      await this.drain();
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful drain failed: ${describe(error)}`);
+    }
+    try {
+      await this.awaitEmpty({ timeoutMs: emptyTimeoutMs });
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful awaitEmpty: ${describe(error)}`);
+    }
+    try {
+      await this.disconnect();
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful disconnect failed: ${describe(error)}`);
+    }
+    try {
+      await this.rivalis.shutdown();
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful rivalis.shutdown failed: ${describe(error)}`);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Transport wiring
+  // -----------------------------------------------------------------------
+  /**
+   * Attach the room-provenance and transport listeners (task 008). Idempotent —
+   * re-`connect()` after a `disconnect()` calls this again but it no-ops while
+   * already attached, so listeners are never doubled.
+   */
+  attachListeners() {
+    if (this.listenersAttached) {
+      return;
+    }
+    this.wireClient();
+    this.subscribeRooms();
+    this.listenersAttached = true;
+  }
+  /**
+   * Detach every listener on the terminal paths (task 008): the rooms broadcast
+   * stops retaining this agent (no more `forgetRoom` on room destroy) and the
+   * transport handlers are removed. Without this a discarded agent leaks — the
+   * `RoomManager` broadcast keeps it alive for the host process's lifetime.
+   */
+  detachListeners() {
+    if (!this.listenersAttached) {
+      return;
+    }
+    this.unsubscribeRooms();
+    try {
+      this.client.removeAllListeners();
+    } catch (error) {
+      this.logger.warning(`fleet:agent transport removeAllListeners error: ${describe(error)}`);
+    }
+    this.listenersAttached = false;
+  }
+  wireClient() {
+    this.client.on("client:connect", () => this.guard("transport open", () => this.onTransportOpen()));
+    this.client.on("client:disconnect", (reason) => this.guard("transport close", () => this.onTransportClose(reason)));
+    this.client.on("client:error", (error) => this.guard("transport error", () => this.onTransportError(error)));
+    this.client.on(Topics.hello, (payload) => this.guard("hello", () => this.onHello(payload)));
+    this.client.on(Topics.poll, (payload) => this.guard("poll", () => this.onPoll(payload)));
+    this.client.on(Topics.cmd, (payload) => this.guard("cmd", () => this.onCmd(payload)));
+  }
+  subscribeRooms() {
+    this.rivalis.rooms.on("destroy", this.onRoomDestroy);
+  }
+  unsubscribeRooms() {
+    this.rivalis.rooms.off("destroy", this.onRoomDestroy);
+  }
+  openConnection() {
+    if (this.closed) {
+      return;
+    }
+    try {
+      this.client.connect(this.key);
+    } catch (error) {
+      this.logger.warning(`fleet:agent connect attempt threw: ${describe(error)}`);
+      this.scheduleReconnect();
+    }
+  }
+  onTransportOpen() {
+    this.logger.debug?.("fleet:agent transport open \u2014 awaiting fleet/hello");
+  }
+  onTransportClose(reason) {
+    if (this.closed || this.intentionalClose) {
+      return;
+    }
+    this.rejectPendingStatus(new Error("fleet:agent connection lost"));
+    this.lifecycle = "connecting";
+    this.emit("disconnect", reason);
+    this.scheduleReconnect();
+  }
+  onTransportError(error) {
+    this.logger.warning(`fleet:agent transport error: ${describe(error)}`);
+    this.emit("error", error);
+  }
+  scheduleReconnect() {
+    if (this.closed || this.intentionalClose || this.reconnectTimer !== null) {
+      return;
+    }
+    const delay = this.backoffDelay();
+    this.reconnectAttempt += 1;
+    this.reconnectTimer = this.scheduler.setTimeout(() => {
+      this.reconnectTimer = null;
+      this.openConnection();
+    }, delay);
+  }
+  /** Full-jitter exponential backoff: random in `[0, min(cap, base·2^attempt)]` (§7). */
+  backoffDelay() {
+    const ceiling = Math.min(this.backoffCapMs, this.backoffBaseMs * Math.pow(2, this.reconnectAttempt));
+    return Math.floor(this.random() * ceiling);
+  }
+  // -----------------------------------------------------------------------
+  // Protocol handlers (orch → agent)
+  // -----------------------------------------------------------------------
+  onHello(raw) {
+    let hello;
+    try {
+      hello = decodeFrame(Topics.hello, toBytes(raw));
+    } catch (error) {
+      if (error instanceof WireVersionError) {
+        this.logger.error(error.message);
+        this.emit("error", error);
+        this.failConnect(error);
+        return;
+      }
+      this.logger.warning(`fleet:agent failed to decode fleet/hello: ${describe(error)}`);
+      return;
+    }
+    if (hello.protocolVersion !== PROTOCOL_VERSION) {
+      const error = new Error(
+        `fleet protocol major mismatch: orchestrator=${hello.protocolVersion}, agent=${PROTOCOL_VERSION} \u2014 upgrade so both speak the same major (\xA77)`
+      );
+      this.logger.error(error.message);
+      this.emit("error", error);
+      this.failConnect(error);
+      return;
+    }
+    this.instanceId = hello.instanceId;
+    this.reconnectAttempt = 0;
+    this.clearReconnect();
+    this.clearConnectDeadline();
+    this.snapshot.resetConnection();
+    this.lifecycle = this.snapshot.status === "draining" ? "draining" : "connected";
+    if (this.connectResolve !== null) {
+      const resolve = this.connectResolve;
+      this.connectResolve = null;
+      this.connectReject = null;
+      resolve();
+    }
+    this.emit("connect", { instanceId: this.instanceId, processUid: this.snapshot.processUid });
+  }
+  /**
+   * Answer an orchestrator `fleet/poll` with a `fleet/state` reply (§7, task 011):
+   * full snapshot when our hash differs from the poll's `knownHash`, hash-only
+   * otherwise. A poll echoing a pending `drain()`/`undrain()` target status also
+   * resolves that promise (the acknowledged confirmation, no unsolicited frame).
+   */
+  onPoll(raw) {
+    const poll = this.decodeInbound(Topics.poll, raw);
+    if (poll === null) {
+      return;
+    }
+    this.resolveStatusOnEcho(poll.status);
+    if (this.client.connected) {
+      this.sendState(this.snapshot.pollReply(poll.reqId, poll.knownHash));
+    }
+  }
+  onCmd(raw) {
+    const cmd = this.decodeInbound(Topics.cmd, raw);
+    if (cmd === null) {
+      return;
+    }
+    this.emit("command", cmd);
+    switch (cmd.op) {
+      case "create":
+        return this.execCreate(cmd);
+      case "destroy":
+        return this.execDestroy(cmd);
+      case "drain":
+        return this.execStatusCmd(cmd, "draining");
+      case "undrain":
+        return this.execStatusCmd(cmd, "active");
+      default:
+        this.sendAck({ cmdId: cmd.cmdId, ok: false, error: `unknown op: ${String(cmd.op)}` });
+    }
+  }
+  execCreate(cmd) {
+    if (!this.autoCreate) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: "autoCreate is disabled on this instance" });
+      return;
+    }
+    if (typeof cmd.roomType !== "string") {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: "create requires roomType" });
+      return;
+    }
+    if (this.maxRooms !== null && this.rivalis.rooms.count >= this.maxRooms) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: `capacity exhausted: maxRooms=${this.maxRooms}` });
+      return;
+    }
+    if (typeof cmd.roomId === "string" && this.rivalis.rooms.get(cmd.roomId) !== null) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, exists: true, error: "room id already exists" });
+      return;
+    }
+    try {
+      const room = this.rivalis.rooms.create(cmd.roomType, cmd.roomId ?? null);
+      this.snapshot.markFleetOrigin(room.id);
+      this.sendAck({ cmdId: cmd.cmdId, ok: true, room: { id: room.id, type: room.type } });
+    } catch (error) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: describe(error) });
+    }
+  }
+  execDestroy(cmd) {
+    if (typeof cmd.roomId !== "string") {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: "destroy requires roomId" });
+      return;
+    }
+    if (this.rivalis.rooms.get(cmd.roomId) === null) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: true, alreadyGone: true });
+      return;
+    }
+    try {
+      this.rivalis.rooms.destroy(cmd.roomId);
+      this.snapshot.forgetRoom(cmd.roomId);
+      this.sendAck({ cmdId: cmd.cmdId, ok: true });
+    } catch (error) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: describe(error) });
+    }
+  }
+  execStatusCmd(cmd, status) {
+    this.snapshot.setStatus(status);
+    this.lifecycle = status === "draining" ? "draining" : "connected";
+    this.sendAck({ cmdId: cmd.cmdId, ok: true });
+  }
+  // -----------------------------------------------------------------------
+  // Outbound (agent → orch) — replies only (task 011)
+  // -----------------------------------------------------------------------
+  requestStatus(target) {
+    this.snapshot.setStatus(target);
+    this.lifecycle = target === "draining" ? "draining" : "connected";
+    return new Promise((resolve, reject) => {
+      this.pendingStatus.push({ target, resolve, reject });
+    });
+  }
+  /** Resolve every pending drain()/undrain() whose target matches the poll-echoed status. */
+  resolveStatusOnEcho(echoed) {
+    if (this.pendingStatus.length === 0) {
+      return;
+    }
+    const remaining = [];
+    for (const pending of this.pendingStatus) {
+      if (pending.target === echoed) {
+        pending.resolve();
+      } else {
+        remaining.push(pending);
+      }
+    }
+    this.pendingStatus = remaining;
+  }
+  sendState(frame) {
+    this.send(Topics.state, frame.payload);
+  }
+  sendAck(ack) {
+    this.send(Topics.ack, ack);
+  }
+  send(topic, payload) {
+    try {
+      this.client.send(topic, encodeFrame(topic, payload));
+    } catch (error) {
+      this.logger.warning(`fleet:agent send failed topic=${topic}: ${describe(error)}`);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Teardown helpers
+  // -----------------------------------------------------------------------
+  /** Fatal connect failure (timeout or protocol mismatch): reject, close, stop retrying (§8). */
+  failConnect(error) {
+    this.closed = true;
+    this.intentionalClose = true;
+    this.clearAllTimers();
+    this.rejectPendingStatus(error);
+    try {
+      this.client.disconnect();
+    } catch (disconnectError) {
+      this.logger.warning(`fleet:agent disconnect during failConnect: ${describe(disconnectError)}`);
+    }
+    this.detachListeners();
+    this.lifecycle = "closed";
+    if (this.connectReject !== null) {
+      const reject = this.connectReject;
+      this.connectResolve = null;
+      this.connectReject = null;
+      reject(error);
+    }
+  }
+  rejectPendingStatus(error) {
+    const pending = this.pendingStatus;
+    this.pendingStatus = [];
+    for (const entry of pending) {
+      entry.reject(error);
+    }
+  }
+  clearReconnect() {
+    if (this.reconnectTimer !== null) {
+      this.scheduler.clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+  clearConnectDeadline() {
+    if (this.connectDeadline !== null) {
+      this.scheduler.clearTimeout(this.connectDeadline);
+      this.connectDeadline = null;
+    }
+  }
+  clearAllTimers() {
+    this.clearReconnect();
+    this.clearConnectDeadline();
+    if (this.uninstallSignals !== null) {
+      this.uninstallSignals();
+      this.uninstallSignals = null;
+    }
+  }
+  /** Run a transport/timer callback, swallowing+logging any throw (§8 host-safety contract). */
+  guard(label, fn) {
+    try {
+      fn();
+    } catch (error) {
+      this.logger.error(`fleet:agent ${label} handler error: ${describe(error)}`);
+      this.emit("error", error instanceof Error ? error : new Error(describe(error)));
+    }
+  }
+  /**
+   * Decode an inbound binary frame for a non-hello topic (§7, task 005). Logs +
+   * returns `null` on any failure — never throws into the host (§8). A
+   * protocol-incompatible frame is logged as a version mismatch; a
+   * malformed/truncated frame is logged and dropped. (`fleet/hello` handles a
+   * version mismatch itself — a loud connect failure — so it does not use this.)
+   */
+  decodeInbound(topic, raw) {
+    try {
+      return decodeFrame(topic, toBytes(raw));
+    } catch (error) {
+      if (error instanceof WireVersionError) {
+        this.logger.warning(`fleet:agent dropped protocol-incompatible ${topic} frame (peer major=${error.theirVersion}, agent=${PROTOCOL_VERSION})`);
+      } else {
+        this.logger.warning(`fleet:agent failed to decode ${topic}: ${describe(error)}`);
+      }
+      return null;
+    }
+  }
+};
+function toBytes(raw) {
+  if (raw instanceof Uint8Array) {
+    return raw;
+  }
+  if (typeof raw === "string") {
+    return Buffer.from(raw, "utf-8");
+  }
+  return new Uint8Array(0);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FleetAgent
+});