create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/hub-bridge-box.js

@@ -0,0 +1,409 @@
+'use strict';
+
+// WP-0 (docs/remote-session-hub-bridge-2026-10-30.html §5 R-2/R-7/R-8, §6.1, §6.2, §6.3, §8 WP-0):
+// the BOX side of the box -> hub request lane.
+//
+// The BOX never dials the hub (NAT / corp networks — machine-registry.js:12-13). Instead the hub
+// dials the box's /ws and keeps ONE CONTROL link per machine; the box identifies that link when the
+// hub sends `hub-bridge-hello` (lib/hub-bridge.js `controlHelloFrame`). This module is the box's
+// registry of those links plus the pending-request table:
+//
+//   noteHello(ws, frame)  record { hubInstanceId, hubDisplayName, ws } (dropped on ws 'close')
+//   status({session?})    { role, hubs:[…], poolMembers, self, session? } (R-5; see the fn doc)
+//   call({...})           mint a rid, send `hub-bridge-request` on the chosen hub, await the reply
+//                         (R-3: the session's recorded creator hub is the default target)
+//
+// R-7, the rule this module exists to keep: a failure is a NAMED error — `hub_unreachable`,
+// `hub_ambiguous`, `hub_bridge_disabled` — and NEVER a local fallback. Nothing here runs the op.
+
+const crypto = require('node:crypto');
+const { boolFlag } = require('./env-flags');
+// The single admitted ws-send primitive (lib/ws-send-admission.js `sendFrame`): the peer-control
+// lane carries protocol frames, not browser streaming traffic, so admission is skipped — but the
+// send still goes through the choke point rather than a raw `ws.send(` (see bin/off-protocol-send-lint.js).
+const { sendFrame } = require('./ws-send-admission');
+
+const BRIDGE_VERSION = 1;
+const DEFAULT_DEADLINE_MS = 30000;
+const MAX_DEADLINE_MS = 122000; // R-8: exec 120 s + the Wall-E client's 2 s grace (wall-e/memory/hub-bridge-client.js)
+
+let _deps = null;
+// ws -> { hubInstanceId, hubDisplayName, ws }. One entry per live hub CONTROL link.
+const _hubs = new Map();
+// The sockets we have already bound a 'close' listener to (a hub may re-hello on the same socket).
+const _bound = new WeakSet();
+// rid -> { resolve, timer, ws }.
+const _pending = new Map();
+
+const DEFAULT_DEPS = {
+  randomUUID: () => crypto.randomUUID(),
+  setTimeoutFn: (fn, ms) => setTimeout(fn, ms),
+  clearTimeoutFn: (id) => clearTimeout(id),
+  // R-10: how many OTHER machines share this box's pool. Still REPORTED by status(), but no reader
+  // may gate on it (R-1: a session's `hub_*` visibility comes from `role` or its creator-hub record).
+  // Absent dep (or a roster fault) reports 0.
+  poolMemberCount: () => 0,
+  // R-5: this box's own identity (lib/hub-bridge.js `selfIdentity()`) — the same values the hello
+  // names. Absent dep (or an unready identity) reports empty strings.
+  selfIdentity: () => ({ instanceId: '', displayName: '' }),
+  // R-3/R-5: the authenticated creator-hub record for a CTM session id (`{hubPeerId, ...} | null`,
+  // lib/agent-bundle/store.js `sessionHubRecord`), written before the session spawns
+  // (lib/ws/terminal-attach.js). Absent/unconfigured reads as "no record".
+  sessionHubRecord: async () => null,
+};
+
+function configure(deps = {}) {
+  _deps = { ...DEFAULT_DEPS, ...(deps || {}) };
+  return _deps;
+}
+
+function _d() {
+  return _deps || DEFAULT_DEPS;
+}
+
+/** Flag read at CALL time so a test can flip CTM_HUB_BRIDGE per-process (never at module load). */
+function isEnabled() {
+  return boolFlag('CTM_HUB_BRIDGE', true);
+}
+
+/** A socket counts as connected while it is OPEN (a simple fake with no readyState counts too). */
+function _isOpen(ws) {
+  if (!ws) return false;
+  return ws.readyState === undefined || ws.readyState === null || ws.readyState === 1;
+}
+
+/**
+ * Record a hub CONTROL link from its `hub-bridge-hello`. Idempotent per socket (a re-hello just
+ * refreshes the identity). The entry is dropped when the socket closes, and every pending request
+ * on it is settled with `hub_unreachable` (R-7 — a mid-request close is never retried locally).
+ */
+function noteHello(ws, frame) {
+  if (!ws) return null;
+  const entry = {
+    hubInstanceId: String((frame && frame.hubInstanceId) || ''),
+    hubDisplayName: String((frame && frame.hubDisplayName) || ''),
+    ws,
+  };
+  _hubs.set(ws, entry);
+  // WP-1 (§5 D-1/D-2, §9 S-2): a hub is attached to this box, so hold the box's own power
+  // assertion (lib/box-keep-awake.js) — no hub hello, no assertion. Best-effort and never awaited.
+  try {
+    require('./box-keep-awake').noteHubLinked();
+  } catch {
+    /* expected: keep-awake is best-effort and must never break the hub link */
+  }
+  if (!_bound.has(ws) && typeof ws.on === 'function') {
+    _bound.add(ws);
+    try {
+      ws.on('close', () => {
+        _hubs.delete(ws);
+        _failPendingOn(ws);
+      });
+    } catch {
+      // expected: a socket that cannot be listened to simply keeps its entry until the next status().
+    }
+  }
+  return entry;
+}
+
+/**
+ * R-10: the other pool members this box could ask for a hub session. `rosterMembers()` includes
+ * self, so self is subtracted; a fault is reported as 0. Nothing gates on the value any more (R-1) —
+ * it is reported because Wall-E's status reader still shows it.
+ */
+function _poolMemberCount() {
+  const d = _d();
+  if (typeof d.poolMemberCount !== 'function') return 0;
+  try {
+    const value = Math.trunc(Number(d.poolMemberCount()));
+    return Number.isFinite(value) && value > 0 ? value : 0;
+  } catch {
+    // REPORT via the 0 below: a roster fault reads as "no other members".
+    return 0;
+  }
+}
+
+/** R-5 (§6.1): this box's own identity — `{instanceId, displayName}`, never a throw. */
+function _selfIdentity() {
+  const d = _d();
+  try {
+    const identity = typeof d.selfIdentity === 'function' ? d.selfIdentity() : null;
+    return {
+      instanceId: String((identity && identity.instanceId) || ''),
+      displayName: String((identity && identity.displayName) || ''),
+    };
+  } catch {
+    // REPORT via the empty identity below: an unready identity is simply unnamed, never a fault.
+    return { instanceId: '', displayName: '' };
+  }
+}
+
+/**
+ * R-3 (§6.2): the authenticated creator-hub record for `callerSessionId` (`{hubPeerId}`), or null.
+ * An invalid/absent id is null, and a read fault is REPORTED once and read as null — the caller then
+ * applies today's role/ambiguity rule, so a record fault can never invent a target hub.
+ */
+async function _readSessionHubRecord(callerSessionId) {
+  const d = _d();
+  if (typeof d.sessionHubRecord !== 'function') return null;
+  try {
+    const record = await d.sessionHubRecord(String(callerSessionId == null ? '' : callerSessionId));
+    if (!record || typeof record !== 'object') return null;
+    const hubPeerId = String(record.hubPeerId == null ? '' : record.hubPeerId).trim();
+    return hubPeerId ? { hubPeerId } : null;
+  } catch (error) {
+    // REPORT: a record read fault is "no record" (R-3 keeps the wording rule below); the call still
+    // answers with a named refusal, and an explicit `machine` is untouched.
+    console.warn(`[hub-bridge] sessionHubRecord('${callerSessionId}') failed: ${error?.message || error}`);
+    return null;
+  }
+}
+
+/**
+ * R-5 (§6.1): the `session` field of status(). The record's `hubPeerId` resolved against the hubs
+ * connected right now: `hubDisplayName` is the live hub's hello name, or the raw peer id when that
+ * hub is not connected. `null` when there is no record — never a 4xx (a reader treats null as "no
+ * record", an empty string as "no question").
+ */
+async function _sessionHubView(sessionId) {
+  const record = await _readSessionHubRecord(sessionId);
+  if (!record) return null;
+  const hub = _connectedHubs().find((entry) => String(entry.hubInstanceId || '') === record.hubPeerId) || null;
+  return {
+    hubInstanceId: record.hubPeerId,
+    hubDisplayName: hub ? String(hub.hubDisplayName || '') : record.hubPeerId,
+    connected: !!hub,
+  };
+}
+
+/**
+ * R-5 (§6.1): who this box is, and — when `opts.session` names a CTM session — whether that session's
+ * creator hub is connected. `role`/`hubs`/`poolMembers` keep their names and meaning; `self` is new.
+ * Async because the optional session lookup reads the creator-hub record from disk.
+ *
+ * @param {{ session?: string }} [opts]  a CTM session id (`?session=`); falsy => no `session` key.
+ */
+async function status(opts = {}) {
+  const hubs = [..._hubs.values()].map((entry) => ({
+    hubInstanceId: entry.hubInstanceId,
+    hubDisplayName: entry.hubDisplayName,
+    connected: _isOpen(entry.ws),
+  }));
+  const out = {
+    role: _hubs.size ? 'box' : 'none',
+    hubs,
+    poolMembers: _poolMemberCount(),
+    self: _selfIdentity(),
+    // WP-1 (§9 S-3): additive — whether this box is holding the keep-awake assertion.
+    keepAwake: require('./box-keep-awake').status(),
+  };
+  const sessionId = String((opts && opts.session) || '').trim();
+  if (sessionId) out.session = await _sessionHubView(sessionId);
+  return out;
+}
+
+function _settle(rid, payload) {
+  const pending = _pending.get(rid);
+  if (!pending) return false;
+  _pending.delete(rid);
+  if (pending.timer) {
+    try {
+      _d().clearTimeoutFn(pending.timer);
+    } catch {
+      // expected: the injected timer already fired.
+    }
+  }
+  pending.resolve(payload);
+  return true;
+}
+
+function _failPendingOn(ws) {
+  for (const [rid, pending] of [..._pending.entries()]) {
+    if (pending.ws === ws) _settle(rid, { ok: false, error: { code: 'hub_unreachable', message: 'socket_closed' } });
+  }
+}
+
+/**
+ * Settle the pending request for `frame.rid` from a hub's `hub-bridge-response`. A late reply — one
+ * whose rid was already settled by the deadline or a socket close — is dropped silently (the design
+ * says so explicitly: the box-side deadline owns the outcome once it passes).
+ */
+function noteResponse(frame) {
+  if (!frame || typeof frame !== 'object') return false;
+  const rid = typeof frame.rid === 'string' ? frame.rid : '';
+  if (!rid || !_pending.has(rid)) return false;
+  const payload = frame.ok
+    ? { ok: true, result: frame.result === undefined ? null : frame.result, ...(frame.truncated ? { truncated: true } : {}) }
+    : { ok: false, error: frame.error || { code: 'op_failed', message: '' } };
+  return _settle(rid, payload);
+}
+
+/** A hub link we may send on: one that is registered and still open. */
+function _connectedHubs() {
+  return [..._hubs.values()].filter((entry) => _isOpen(entry.ws));
+}
+
+/** `id (Display Name)`, or just the id — the retry hint a `machine` refusal carries. */
+function _hubLabel(entry) {
+  const name = String((entry && entry.hubDisplayName) || '').trim();
+  return name ? `${entry.hubInstanceId} (${name})` : String((entry && entry.hubInstanceId) || '');
+}
+
+/** Every connected hub, named — what an unreachable/ambiguous refusal must tell the agent. */
+function _hubNames(hubs) {
+  return hubs.map(_hubLabel).join(', ') || '(none)';
+}
+
+/**
+ * WP-5 (R-12): the connected hub a `machine` target names — by instance id first, then by display
+ * name case-insensitively. Null when nothing matches (the caller answers `hub_unreachable` naming
+ * the hubs it DID reach).
+ */
+function _matchHub(hubs, machine) {
+  const wanted = String(machine == null ? '' : machine).trim();
+  if (!wanted) return null;
+  const lower = wanted.toLowerCase();
+  return hubs.find((entry) => String(entry.hubInstanceId || '') === wanted)
+    || hubs.find((entry) => String(entry.hubDisplayName || '').toLowerCase() === lower)
+    || null;
+}
+
+/** R-3: the hub entry whose `hubInstanceId` is `hubInstanceId`, or null. */
+function _hubByInstanceId(hubs, hubInstanceId) {
+  const wanted = String(hubInstanceId == null ? '' : hubInstanceId);
+  return hubs.find((entry) => String(entry.hubInstanceId || '') === wanted) || null;
+}
+
+/**
+ * R-3 (§6.2): pick the hub for one call and put the request frame on it. Every refusal is named and
+ * NOTHING is sent on it (R-7 — no local fallback).
+ *
+ *  - `machine` non-empty: the connected hub it names, else `hub_unreachable` (naming the connected).
+ *  - no `machine`: the session's recorded CREATOR hub — the authenticated peer written to
+ *    `sessions/<id>.json` before the session spawned (`sessionHubRecord`, resolved through the dep
+ *    below). A record whose hub is NOT connected is `hub_unreachable` naming that hub and the hubs
+ *    that ARE connected; it is never silently swapped for another hub.
+ *  - no record at all (or a record read fault): today's rule — exactly one connected hub -> it; more
+ *    than one -> `hub_ambiguous`, naming them.
+ */
+async function _selectAndSend(resolve, { callerSessionId, op, args, machine, deadlineMs = DEFAULT_DEADLINE_MS }) {
+  if (!isEnabled()) {
+    return resolve({ ok: false, error: { code: 'hub_bridge_disabled', message: 'CTM_HUB_BRIDGE=0 on the box' } });
+  }
+  const hubs = _connectedHubs();
+  if (!hubs.length) {
+    return resolve({ ok: false, error: { code: 'hub_unreachable', message: 'no hub control link' } });
+  }
+  const wanted = String(machine == null ? '' : machine).trim();
+  let hub = null;
+  if (wanted) {
+    hub = _matchHub(hubs, wanted);
+    if (!hub) {
+      return resolve({
+        ok: false,
+        error: {
+          code: 'hub_unreachable',
+          message: `no connected hub matches machine '${wanted}' (connected hubs: ${_hubNames(hubs)})`,
+        },
+      });
+    }
+  } else {
+    const record = await _readSessionHubRecord(callerSessionId);
+    if (record) {
+      hub = _hubByInstanceId(hubs, record.hubPeerId);
+      if (!hub) {
+        return resolve({
+          ok: false,
+          error: {
+            code: 'hub_unreachable',
+            message: `creator hub '${record.hubPeerId}' is not connected (connected hubs: ${_hubNames(hubs)})`,
+          },
+        });
+      }
+    } else if (hubs.length > 1) {
+      return resolve({
+        ok: false,
+        error: {
+          code: 'hub_ambiguous',
+          message: `${hubs.length} hubs are connected: ${_hubNames(hubs)} — pass 'machine' (an instance id or name) to choose one`,
+        },
+      });
+    } else {
+      hub = hubs[0];
+    }
+  }
+  _send(hub, resolve, { callerSessionId, op, args, deadlineMs });
+}
+
+/** Mint a rid, arm the deadline, and put the request frame on `hub` (the resolve is settled later). */
+function _send(hub, resolve, { callerSessionId, op, args, deadlineMs }) {
+  const d = _d();
+  const rid = d.randomUUID();
+  const wait = Math.min(Math.max(1, Number(deadlineMs) || DEFAULT_DEADLINE_MS), MAX_DEADLINE_MS);
+  const entry = { resolve, timer: null, ws: hub.ws };
+  _pending.set(rid, entry);
+  entry.timer = d.setTimeoutFn(() => {
+    _settle(rid, { ok: false, error: { code: 'hub_unreachable', message: 'deadline' } });
+  }, wait);
+  if (entry.timer && typeof entry.timer.unref === 'function') entry.timer.unref();
+  const frame = {
+    type: 'hub-bridge-request',
+    v: BRIDGE_VERSION,
+    rid,
+    callerSessionId: String(callerSessionId || ''),
+    op: String(op || ''),
+    args: args === undefined ? {} : args,
+    deadlineMs: wait,
+  };
+  // REPORT: a send failure (or a socket that is already closed) is a named hub_unreachable, settled
+  // through the same table.
+  if (!sendFrame(hub.ws, JSON.stringify(frame))) {
+    _settle(rid, { ok: false, error: { code: 'hub_unreachable', message: 'send_failed' } });
+  }
+}
+
+/**
+ * Ask the hub that dialled us to run `op`. Resolves `{ok:true, result}` or `{ok:false, error}` —
+ * never rejects, and never runs anything locally (R-7). Hub choice is `_selectAndSend` above.
+ */
+function call({ callerSessionId, op, args, machine, deadlineMs = DEFAULT_DEADLINE_MS } = {}) {
+  return new Promise((resolve) => {
+    // The executor is NOT async (an async executor would swallow a mid-flight throw into an unhandled
+    // rejection); the one async step is the creator-hub lookup, and this tail keeps R-7's "never
+    // rejects" contract even if that lookup faults.
+    _selectAndSend(resolve, { callerSessionId, op, args, machine, deadlineMs }).catch((error) => {
+      // REPORT: an unexpected throw still answers as a named refusal, never as a rejection.
+      console.warn(`[hub-bridge] call() failed: ${error?.message || error}`);
+      resolve({ ok: false, error: { code: 'hub_unreachable', message: 'internal_error' } });
+    });
+  });
+}
+
+function listHubs() {
+  return [..._hubs.values()].map((entry) => ({ hubInstanceId: entry.hubInstanceId, hubDisplayName: entry.hubDisplayName }));
+}
+
+function pendingCount() {
+  return _pending.size;
+}
+
+function _resetForTests() {
+  _deps = null;
+  _hubs.clear();
+  _pending.clear();
+}
+
+module.exports = {
+  BRIDGE_VERSION,
+  DEFAULT_DEADLINE_MS,
+  MAX_DEADLINE_MS,
+  configure,
+  isEnabled,
+  noteHello,
+  noteResponse,
+  status,
+  call,
+  listHubs,
+  pendingCount,
+  _resetForTests,
+};