docs: document gateway node helpers

steipete · steipete · commit a3f495eb09d5 · 2026-06-04T17:23:48.000-04:00
diff --git a/src/gateway/node-connect-reconcile.ts b/src/gateway/node-connect-reconcile.ts
@@ -1,3 +1,5 @@
+// Gateway node connect reconciliation.
+// Computes approved runtime surfaces and pending pairing upgrades on reconnect.
 import type { ConnectParams } from "../../packages/gateway-protocol/src/index.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/gateway/node-pending-work.ts b/src/gateway/node-pending-work.ts
@@ -1,3 +1,5 @@
+// Gateway pending node-work queue.
+// Stores short-lived per-node prompts until connected nodes drain/ack them.
 import { randomUUID } from "node:crypto";
 import {
   asDateTimestampMs,
@@ -69,6 +71,8 @@ function getOrCreateState(nodeId: string): NodePendingWorkState {
 }
 
 function pruneExpired(state: NodePendingWorkState, nowMs: number): boolean {
+  // Expiry pruning bumps revision so polling nodes can observe that work changed
+  // even when no explicit acknowledge call happened.
   const validNowMs = asDateTimestampMs(nowMs);
   if (validNowMs === undefined) {
     return false;
diff --git a/src/gateway/server-node-events.ts b/src/gateway/server-node-events.ts
@@ -1,3 +1,5 @@
+// Gateway node event dispatcher.
+// Handles device/node-originated events and routes them to sessions/channels.
 import { randomUUID } from "node:crypto";
 import {
   normalizeLowercaseStringOrEmpty,
@@ -117,6 +119,8 @@ function shouldDropDuplicateVoiceTranscript(params: {
   fingerprint: string;
   now: number;
 }): boolean {
+  // Voice providers can replay identical transcript fragments during reconnect.
+  // Keep only a bounded last fingerprint per session to avoid duplicate sends.
   const previous = recentVoiceTranscripts.get(params.sessionKey);
   if (
     previous &&
diff --git a/src/gateway/server-node-session-runtime.ts b/src/gateway/server-node-session-runtime.ts
@@ -1,3 +1,5 @@
+// Gateway node session runtime factory.
+// Creates node registry, subscription, and voice-wake fanout state.
 import { NodeRegistry, type SerializedEventPayload } from "./node-registry.js";
 import {
   createSessionEventSubscriberRegistry,
diff --git a/src/gateway/server-node-subscriptions.ts b/src/gateway/server-node-subscriptions.ts
@@ -1,3 +1,5 @@
+// Gateway node subscription manager.
+// Maintains bidirectional node/session fanout indexes.
 import { serializeEventPayload, type SerializedEventPayload } from "./node-registry.js";
 
 // Node subscription manager keeps bidirectional node/session indexes so gateway
@@ -92,6 +94,8 @@ export function createNodeSubscriptionManager(): NodeSubscriptionManager {
     if (!nodeSet) {
       return;
     }
+    // Remove reverse session indexes before deleting the node index so session
+    // fanout cannot retain disconnected node ids.
     for (const sessionKey of nodeSet) {
       const sessionSet = sessionSubscribers.get(sessionKey);
       sessionSet?.delete(normalizedNodeId);

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway node connect reconciliation.`
	`2`	`+// Computes approved runtime surfaces and pending pairing upgrades on reconnect.`
`1`	`3`	`import type { ConnectParams } from "../../packages/gateway-protocol/src/index.js";`
`2`	`4`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`3`	`5`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway node session runtime factory.`
	`2`	`+// Creates node registry, subscription, and voice-wake fanout state.`
`1`	`3`	`import { NodeRegistry, type SerializedEventPayload } from "./node-registry.js";`
`2`	`4`	`import {`
`3`	`5`	`createSessionEventSubscriberRegistry,`