docs: document gateway session utilities

steipete · steipete · commit fba99cddc1ac · 2026-06-04T17:13:14.000-04:00
diff --git a/src/gateway/server-session-key.ts b/src/gateway/server-session-key.ts
@@ -1,3 +1,5 @@
+// Gateway run-id to session-key resolver.
+// Bridges live agent run context with persisted session stores.
 import {
   asDateTimestampMs,
   resolveExpiresAtMsFromDurationMs,
@@ -53,6 +55,8 @@ function setResolvedSessionKeyCache(
   }
   let expiresAt: number | null = null;
   if (sessionKey === null) {
+    // Negative caching avoids repeated full-store scans while still allowing
+    // a just-created run/session pair to appear shortly after the first lookup.
     const missExpiresAt = resolveExpiresAtMsFromDurationMs(RUN_LOOKUP_MISS_TTL_MS);
     if (missExpiresAt === undefined) {
       return;
@@ -122,6 +126,8 @@ export function resolveSessionKeyForRun(runId: string, opts: { agentId?: string
   );
   const storeKey = resolvePreferredSessionKeyForSessionIdMatches(matches, runId);
   if (storeKey) {
+    // Return caller-facing agent request keys, not raw store keys, because
+    // HTTP/RPC clients reuse this value in later session operations.
     const sessionKey = resolveRunSessionKeyForCaller(storeKey);
     setResolvedSessionKeyCache(runId, cacheAgentId, sessionKey);
     return sessionKey;
diff --git a/src/gateway/server-startup-log.ts b/src/gateway/server-startup-log.ts
@@ -1,3 +1,5 @@
+// Gateway startup logging helpers.
+// Produces the compact ready banner with resolved model and safety state.
 import { normalizeSortedUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import chalk from "chalk";
 import { resolveDefaultAgentId, resolveAgentConfig } from "../agents/agent-scope.js";
diff --git a/src/gateway/server-startup-session-migration.ts b/src/gateway/server-startup-session-migration.ts
@@ -1,3 +1,5 @@
+// Gateway startup session-store migration runner.
+// Keeps old orphaned session keys from surviving process upgrades.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { migrateOrphanedSessionKeys } from "../infra/state-migrations.js";
 
diff --git a/src/gateway/session-patch-hooks.ts b/src/gateway/session-patch-hooks.ts
@@ -1,3 +1,5 @@
+// Session patch hook dispatcher.
+// Publishes internal mutation notifications after Gateway session patch calls.
 import type { SessionsPatchParams } from "../../packages/gateway-protocol/src/index.js";
 import type { SessionEntry } from "../config/sessions.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/gateway/session-reset-service.ts b/src/gateway/session-reset-service.ts
@@ -1,3 +1,5 @@
+// Gateway session reset/delete service.
+// Rotates transcripts and coordinates lifecycle cleanup across runtimes/hooks.
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -80,6 +82,8 @@ function resolveResetSessionFile(params: {
   agentId: string;
 }): string {
   const currentEntry = params.currentEntry;
+  // Preserve explicit session-file placement across reset while swapping the
+  // embedded session id, so linked runtimes keep writing beside old transcripts.
   const rewrittenSessionFile = currentEntry?.sessionId
     ? rewriteSessionFileForNewSessionId({
         sessionFile: currentEntry.sessionFile,
@@ -108,6 +112,8 @@ function stripRuntimeModelState(entry?: SessionEntry): SessionEntry | undefined
   }
   return {
     ...entry,
+    // Reset should keep user selection preferences but drop per-run resolved
+    // model state so the next turn rehydrates from current config.
     model: undefined,
     modelProvider: undefined,
     contextTokens: undefined,
diff --git a/src/gateway/session-subagent-reactivation.ts b/src/gateway/session-subagent-reactivation.ts
@@ -1,3 +1,5 @@
+// Subagent session reactivation helper.
+// Replaces completed subagent run records when a user steers the child session.
 import { getLatestSubagentRunByChildSessionKey } from "../agents/subagent-registry-read.js";
 
 // Completed subagent sessions can be reactivated after a user steer by replacing
diff --git a/src/gateway/session-utils.ts b/src/gateway/session-utils.ts
@@ -1,3 +1,5 @@
+// Gateway session listing and projection helpers.
+// Normalizes persisted session stores into UI/RPC rows without mutating state.
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -173,6 +175,8 @@ function resolveIdentityAvatarUrl(
     return undefined;
   }
   try {
+    // Avatars can be workspace-relative, but projection must keep the file
+    // read inside the agent workspace and cap bytes before encoding.
     const opened = openRootFileSync({
       absolutePath: resolvedCandidate,
       rootPath: workspaceRoot,
@@ -421,6 +425,8 @@ function shouldKeepStoreOnlyChildLink(entry: SessionEntry, now: number): boolean
   if (entry.status === "running" || isFinitePositiveTimestamp(entry.startedAt)) {
     return true;
   }
+  // Store-only child links lack a live subagent registry entry. Keep recent
+  // unknown-state rows visible briefly so reloads do not hide fresh children.
   return (
     isFinitePositiveTimestamp(entry.updatedAt) &&
     now - entry.updatedAt <= STALE_STORE_ONLY_CHILD_LINK_MS
diff --git a/src/gateway/session-utils.types.ts b/src/gateway/session-utils.types.ts
@@ -1,3 +1,5 @@
+// Shared Gateway session projection types.
+// Keeps server methods and Control UI payloads aligned.
 import type { ChatType } from "../channels/chat-type.js";
 import type {
   SessionCompactionCheckpoint,
diff --git a/src/gateway/startup-tasks.ts b/src/gateway/startup-tasks.ts
@@ -1,3 +1,5 @@
+// Ordered Gateway startup task runner.
+// Used for best-effort side effects that should not abort the server.
 import { formatErrorMessage } from "../infra/errors.js";
 
 // Startup tasks run sequentially so logs and side effects stay ordered during

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway startup logging helpers.`
	`2`	`+// Produces the compact ready banner with resolved model and safety state.`
`1`	`3`	`import { normalizeSortedUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";`
`2`	`4`	`import chalk from "chalk";`
`3`	`5`	`import { resolveDefaultAgentId, resolveAgentConfig } from "../agents/agent-scope.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway startup session-store migration runner.`
	`2`	`+// Keeps old orphaned session keys from surviving process upgrades.`
`1`	`3`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`2`	`4`	`import { migrateOrphanedSessionKeys } from "../infra/state-migrations.js";`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Session patch hook dispatcher.`
	`2`	`+// Publishes internal mutation notifications after Gateway session patch calls.`
`1`	`3`	`import type { SessionsPatchParams } from "../../packages/gateway-protocol/src/index.js";`
`2`	`4`	`import type { SessionEntry } from "../config/sessions.js";`
`3`	`5`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Subagent session reactivation helper.`
	`2`	`+// Replaces completed subagent run records when a user steers the child session.`
`1`	`3`	`import { getLatestSubagentRunByChildSessionKey } from "../agents/subagent-registry-read.js";`
`2`	`4`
`3`	`5`	`// Completed subagent sessions can be reactivated after a user steer by replacing`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Shared Gateway session projection types.`
	`2`	`+// Keeps server methods and Control UI payloads aligned.`
`1`	`3`	`import type { ChatType } from "../channels/chat-type.js";`
`2`	`4`	`import type {`
`3`	`5`	`SessionCompactionCheckpoint,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Ordered Gateway startup task runner.`
	`2`	`+// Used for best-effort side effects that should not abort the server.`
`1`	`3`	`import { formatErrorMessage } from "../infra/errors.js";`
`2`	`4`
`3`	`5`	`// Startup tasks run sequentially so logs and side effects stay ordered during`