create-walle 0.10.2 → 0.10.3

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

@@ -0,0 +1,398 @@
+'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 HUB side of the box -> hub request lane.
+//
+// Every hub<->box channel before this was hub-initiated: the hub dials each pooled box's /ws and
+// keeps one CONTROL link per machine (lib/remote-machine-link.js `openLink`). This module is the
+// far end of a request/response lane that flows the OTHER way over that SAME socket — a process on
+// the BOX asks the HUB that dialled it. There is no new connection, no inbound port, and no
+// fallback: a request that cannot be answered on the link is a NAMED error (R-7), never a local run.
+//
+//   box  --hub-bridge-request{v:1,rid,callerSessionId,op,args,deadlineMs}-->  hub
+//   hub  --hub-bridge-response{v:1,rid,ok,result|error}-->                    box
+//
+// Identity comes from the LINK, not the body (R-2): `link.machineInstanceId` is the id the hub
+// pinned at dial time, and a request naming a session the hub does not mirror from that machine is
+// refused with `caller_session_not_on_machine`. Nothing in the frame is trusted for identity.
+//
+// Bounded (R-8): args <= 256 KiB, result <= 1 MiB (truncated), at most 4 in flight per machine.
+//
+// Everything is injectable for tests; the process singleton is configured once at boot
+// (server.js) with the same identity the instance manifest publishes and the catalog's
+// `getMirrorSessionMachine` ownership resolver.
+
+const { boolFlag, registerFlag } = require('./env-flags');
+
+const BRIDGE_VERSION = 1;
+const RID_MAX = 80;
+const ARGS_MAX_BYTES = 256 * 1024;
+const RESULT_MAX_BYTES = 1024 * 1024;
+const MAX_IN_FLIGHT = 4;
+// WP-5 (R-2 freshness): the refresh budget used when the frame names no deadline, and the ceiling a
+// frame's deadline can never raise the refresh above (a request is answered well inside its own
+// deadline, so the refresh can only ever be a fraction of it).
+const REFRESH_DEFAULT_BUDGET_MS = 5000;
+const REFRESH_MAX_BUDGET_MS = 15000;
+
+// Default ON (design §5 R-8 / §8 "Flag"): `CTM_HUB_BRIDGE=0` turns the lane off on either side and
+// every request answers the named `hub_bridge_disabled`.
+registerFlag('CTM_HUB_BRIDGE', {
+  kind: 'bool',
+  default: true,
+  desc: 'Box->hub request lane over the hub-dialed CONTROL WebSocket (docs/remote-session-hub-bridge-2026-10-30.html §5 R-2/R-8); 0 disables it and answers hub_bridge_disabled',
+});
+
+// name -> { tier, run(args, callCtx) }. WP-0 registers only `ping`; later WPs add ops through
+// `registerOp` (the exported seam the design names).
+const OPS = new Map();
+// machineInstanceId -> in-flight count. A per-process bound, never persisted (R-8).
+const _inFlight = new Map();
+
+let _deps = null;
+
+const DEFAULT_DEPS = {
+  selfIdentity: () => ({ instanceId: '', displayName: '' }),
+  getMirrorSessionMachine: () => null,
+  now: () => Date.now(),
+  // R-9: (entry) => void. Wired to lib/hub-bridge-access.js's `audit` at boot; absent in the unit
+  // tests that drive the dispatcher directly (a missing sink is a no-op, never a crash).
+  audit: null,
+  // R-4/R-11 (WP-2): ({machineId, callerSessionId, tier, op, machineName, args}) => decision. Wired to
+  // lib/hub-bridge-access.js's `decide` at boot. Absent -> a gated op is refused, never run ungated.
+  decide: null,
+  // WP-5 (§5 R-2 freshness): (machineInstanceId) => Promise. Wired to the catalog's fetchCatalog at
+  // boot; the ONE bounded refresh a missed caller-session check is allowed. Absent -> no refresh at
+  // all (the pre-WP-5 behaviour: a miss is refused outright).
+  refreshMachineCatalog: null,
+  setTimeoutFn: (fn, ms) => setTimeout(fn, ms),
+  clearTimeoutFn: (timer) => clearTimeout(timer),
+};
+
+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);
+}
+
+/** This hub's own identity ({instanceId, displayName}); '' when identity is not ready yet. */
+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 {
+    // expected: identity is unready early in boot — the hello is simply not sent (see below).
+    return { instanceId: '', displayName: '' };
+  }
+}
+
+/**
+ * The `hub-bridge-hello` frame the CONTROL link sends right after its client-info (§6.1), or `null`
+ * when this process has no identity to name yet. A hello that names no hub would be worse than no
+ * hello: the box would key a socket to '' and could never route a request back to it.
+ */
+function controlHelloFrame() {
+  const self = selfIdentity();
+  if (!self.instanceId) return null;
+  return {
+    type: 'hub-bridge-hello',
+    v: BRIDGE_VERSION,
+    hubInstanceId: self.instanceId,
+    hubDisplayName: self.displayName,
+  };
+}
+
+/**
+ * Register an op. `def.run(args, callCtx)` is async and its resolved value is the response
+ * `result`; a throw carrying a protocol-shaped `error.code` becomes that named code, and any other
+ * throw becomes `{ok:false, error:{code:'op_failed'}}` (never a crash).
+ */
+function registerOp(name, def) {
+  if (typeof name !== 'string' || !name) throw new TypeError('registerOp: name must be a non-empty string');
+  if (!def || typeof def.run !== 'function') throw new TypeError(`registerOp(${name}): def.run must be a function`);
+  OPS.set(name, { tier: String(def.tier || 'none'), run: def.run });
+}
+
+function listOps() {
+  return [...OPS.keys()].sort();
+}
+
+/** The machine that owns `callerSessionId`, or '' — the R-2 ownership resolver (read off the link). */
+function _ownerMachine(callerSessionId) {
+  const d = _d();
+  if (!callerSessionId || typeof d.getMirrorSessionMachine !== 'function') return '';
+  try {
+    const mirror = d.getMirrorSessionMachine(callerSessionId);
+    if (!mirror) return '';
+    // WP-3's resolver returns `machineInstanceId`; accept `instanceId` too so a caller that
+    // forwards the raw catalog row is not silently refused.
+    return String(mirror.machineInstanceId || mirror.instanceId || '');
+  } catch {
+    // REPORT via the refusal below: a resolver fault is "cannot prove ownership", which is a refusal.
+    return '';
+  }
+}
+
+/** R-8: a result over 1 MiB is truncated, never silently dropped. */
+function _capResult(result) {
+  const value = result === undefined ? null : result;
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    // A result that is not JSON-serialisable can never cross the lane: report it as a truncation
+    // rather than throwing inside the reply.
+    return { ok: true, truncated: true, result: { truncated: true, preview: '' } };
+  }
+  if (Buffer.byteLength(text, 'utf8') <= RESULT_MAX_BYTES) return { ok: true, result: value };
+  const preview = Buffer.from(text, 'utf8').subarray(0, RESULT_MAX_BYTES).toString('utf8');
+  return { ok: true, truncated: true, result: { truncated: true, preview } };
+}
+
+function _audit(entry) {
+  const d = _d();
+  if (typeof d.audit !== 'function') return;
+  try {
+    d.audit(entry);
+  } catch {
+    // expected: the audit sink is best-effort (R-9) — a sink fault must never fail a reply.
+  }
+}
+
+/**
+ * WP-2 (§5 R-4/R-11): the access decision for a gated op. `deps.decide` is lib/hub-bridge-access.js's
+ * `decide` in production; a missing dep FAILS CLOSED (`hub_bridge_denied`) rather than running a
+ * gated op ungated — an unwired bridge must never be an ambient grant.
+ */
+function _decide(request) {
+  const d = _d();
+  if (typeof d.decide !== 'function') return { allow: false, code: 'hub_bridge_denied' };
+  try {
+    const decision = d.decide(request);
+    if (decision && typeof decision === 'object') return decision;
+  } catch {
+    // REPORT via the refusal below: a fault inside the access decider is "cannot prove a grant".
+    return { allow: false, code: 'hub_bridge_denied' };
+  }
+  return { allow: false, code: 'hub_bridge_denied' };
+}
+
+function _decrement(machineInstanceId) {
+  const left = Math.max(0, (Number(_inFlight.get(machineInstanceId)) || 1) - 1);
+  if (left) _inFlight.set(machineInstanceId, left);
+  else _inFlight.delete(machineInstanceId);
+}
+
+/**
+ * WP-5 (§5 R-2 freshness): ONE catalog refresh for the machine behind this request, bounded by the
+ * request's own deadline. A caller session created moments ago may simply be newer than this hub's
+ * copy of that machine's session list, so a miss is worth one refresh — never a loop, and never
+ * unbounded: the refresh races a timer, the timer is cleared either way, and a fault reads as "no
+ * refresh happened" (the caller is then refused exactly as before).
+ *
+ * @returns {Promise<boolean>} true when the refresh finished inside its budget (its own result is
+ *   irrelevant — the caller re-checks ownership, which is the only authority).
+ */
+async function _refreshCatalogOnce(machineInstanceId, deadlineMs) {
+  const d = _d();
+  if (!machineInstanceId || typeof d.refreshMachineCatalog !== 'function') return false;
+  const requested = Number(deadlineMs);
+  const budget = Math.max(
+    1,
+    Math.min(Number.isFinite(requested) && requested > 0 ? requested : REFRESH_DEFAULT_BUDGET_MS, REFRESH_MAX_BUDGET_MS),
+  );
+  let timer = null;
+  const expired = Symbol('refresh_expired');
+  const timeout = new Promise((resolve) => {
+    timer = d.setTimeoutFn(() => resolve(expired), budget);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  });
+  try {
+    const outcome = await Promise.race([
+      Promise.resolve().then(() => d.refreshMachineCatalog(machineInstanceId)),
+      timeout,
+    ]);
+    return outcome !== expired;
+  } catch {
+    // REPORT via the caller's refusal: a refresh fault is "cannot prove ownership", which is a refusal.
+    return false;
+  } finally {
+    if (timer) {
+      try {
+        d.clearTimeoutFn(timer);
+      } catch {
+        // expected: the injected timer already fired.
+      }
+    }
+  }
+}
+
+/**
+ * Handle one `hub-bridge-request` off `link`, writing EXACTLY ONE `hub-bridge-response` through
+ * `send` (wired to the link's upstream send). Never throws and never rejects.
+ *
+ * @param {object} link   the hub's CONTROL link (its `machineInstanceId` is the pinned identity)
+ * @param {object} frame  the box's request frame
+ * @param {(frame: object) => any} send  the upstream send for that link
+ * @returns {Promise<object|null>} the frame that was sent (null when there is nothing to send to)
+ */
+async function handleRequest(link, frame, send) {
+  if (typeof send !== 'function') return null;
+  const rid = frame && typeof frame.rid === 'string' ? frame.rid : '';
+  const reply = (payload) => {
+    const body = { type: 'hub-bridge-response', v: BRIDGE_VERSION, rid, ...payload };
+    try {
+      send(body);
+    } catch {
+      // expected: the CONTROL link died mid-reply; the box's own deadline owns that case (R-7).
+    }
+    return body;
+  };
+  const fail = (code, message, extra) => reply({
+    ok: false,
+    error: { code, message: String(message == null ? code : message), ...(extra || {}) },
+  });
+
+  if (!isEnabled()) return fail('hub_bridge_disabled', 'CTM_HUB_BRIDGE=0 on the hub');
+  if (!frame || typeof frame !== 'object' || frame.v !== BRIDGE_VERSION) {
+    return fail('bad_request', `unsupported bridge version: ${frame && frame.v}`);
+  }
+  if (!rid || rid.length > RID_MAX) {
+    return fail('bad_request', `rid must be a non-empty string of at most ${RID_MAX} characters`);
+  }
+  const op = typeof frame.op === 'string' ? frame.op : '';
+  const def = OPS.get(op);
+  if (!def) return fail('op_unknown', `unknown bridge op: ${op}`);
+  let argsText;
+  try {
+    argsText = JSON.stringify(frame.args === undefined ? null : frame.args);
+  } catch {
+    return fail('bad_request', 'args is not JSON-serialisable');
+  }
+  if (Buffer.byteLength(argsText, 'utf8') > ARGS_MAX_BYTES) {
+    return fail('args_too_large', `args exceeds ${ARGS_MAX_BYTES} bytes`);
+  }
+
+  const machineInstanceId = String((link && link.machineInstanceId) || '');
+  const callerSessionId = typeof frame.callerSessionId === 'string' ? frame.callerSessionId : '';
+  // R-2: identity comes from the LINK, never the body. A session this hub does not mirror from
+  // THIS machine is refused — the caller can act only for its own sessions.
+  let owner = callerSessionId && machineInstanceId ? _ownerMachine(callerSessionId) : '';
+  if (owner !== machineInstanceId && machineInstanceId && callerSessionId) {
+    // WP-5 (§5 R-2 freshness): the caller session may just be newer than this hub's copy of that
+    // machine's session list. ONE bounded refresh of THAT machine, then re-check. No loop: a second
+    // miss is the refusal below, and the refresh never widens the deadline the caller set.
+    await _refreshCatalogOnce(machineInstanceId, frame.deadlineMs);
+    owner = callerSessionId ? _ownerMachine(callerSessionId) : '';
+  }
+  if (!callerSessionId || !machineInstanceId || owner !== machineInstanceId) {
+    return fail('caller_session_not_on_machine', `session ${callerSessionId || '(none)'} is not mirrored from machine ${machineInstanceId || '(unknown)'}`);
+  }
+
+  if ((Number(_inFlight.get(machineInstanceId)) || 0) >= MAX_IN_FLIGHT) {
+    return fail('hub_busy', `${MAX_IN_FLIGHT} requests already in flight for machine ${machineInstanceId}`);
+  }
+
+  // WP-2 (§5 R-4/R-5/R-11): a gated op (tier !== 'none') needs an access decision BEFORE it runs.
+  // A refusal is a NAMED, non-executed outcome — no audit line, and `tier`/`pendingId` ride the
+  // error so the box's tool can tell the user exactly what to approve.
+  let via = 'none';
+  if (def.tier !== 'none') {
+    const decision = _decide({
+      machineId: machineInstanceId,
+      machineName: String((link && link.machineName) || ''),
+      callerSessionId,
+      tier: def.tier,
+      op,
+      args: frame.args === undefined ? {} : frame.args,
+    });
+    if (decision.allow !== true) {
+      const code = typeof decision.code === 'string' && decision.code ? decision.code : 'hub_grant_required';
+      const extra = { tier: def.tier };
+      if (code === 'hub_grant_required') extra.pendingId = String(decision.pendingId || '');
+      return fail(code, `${def.tier} is not granted for session ${callerSessionId} on ${String((link && link.machineName) || machineInstanceId)}`, extra);
+    }
+    via = typeof decision.via === 'string' && decision.via ? decision.via : 'none';
+  }
+
+  const startedAt = _d().now();
+  _inFlight.set(machineInstanceId, (Number(_inFlight.get(machineInstanceId)) || 0) + 1);
+  let outcome;
+  try {
+    const result = await def.run(frame.args === undefined ? {} : frame.args, {
+      link,
+      machineInstanceId,
+      callerSessionId,
+      op,
+      tier: def.tier,
+      now: startedAt,
+      hubInstanceId: selfIdentity().instanceId,
+    });
+    outcome = { ok: true, result };
+  } catch (error) {
+    // §6.3: an op refuses with a NAMED code by throwing `Object.assign(new Error(msg), {code})`
+    // (lib/hub-bridge-ops.js). A throw with no usable code stays `op_failed` — the lane never
+    // invents a code, and never leaks a non-protocol string into the frame.
+    const raw = error && typeof error.code === 'string' ? error.code : '';
+    const code = /^[a-z][a-z0-9_]{0,39}$/.test(raw) ? raw : 'op_failed';
+    outcome = { ok: false, error: { code, message: (error && error.message) || String(error) } };
+  } finally {
+    _decrement(machineInstanceId);
+  }
+
+  // R-9: every EXECUTED op is audited, tier-'none' ones included. The sink digests `args`; the raw
+  // args never leave this process.
+  _audit({
+    at: startedAt,
+    machineId: machineInstanceId,
+    callerSessionId,
+    op,
+    tier: def.tier,
+    via,
+    args: frame.args === undefined ? {} : frame.args,
+    ok: outcome.ok,
+    code: outcome.ok ? '' : outcome.error.code,
+    ms: Math.max(0, _d().now() - startedAt),
+  });
+
+  if (!outcome.ok) return reply({ ok: false, error: outcome.error });
+  return reply(_capResult(outcome.result));
+}
+
+// WP-0 (§8): the ONLY op this package ships. Later WPs register session.read / fs.* / exec / mcp.*.
+registerOp('ping', {
+  tier: 'none',
+  run: async (args, callCtx) => ({ hubInstanceId: callCtx.hubInstanceId, at: callCtx.now }),
+});
+
+function _resetForTests() {
+  _deps = null;
+  _inFlight.clear();
+}
+
+module.exports = {
+  BRIDGE_VERSION,
+  MAX_IN_FLIGHT,
+  ARGS_MAX_BYTES,
+  RESULT_MAX_BYTES,
+  configure,
+  isEnabled,
+  selfIdentity,
+  controlHelloFrame,
+  registerOp,
+  listOps,
+  handleRequest,
+  _resetForTests,
+};