docs: document remaining src helpers

steipete · steipete · commit edb920b857ce · 2026-06-04T20:34:26.000-04:00
diff --git a/src/context-engine/context-engine.test.ts b/src/context-engine/context-engine.test.ts
@@ -1,3 +1,4 @@
+// Context engine tests cover context extraction and prompt context assembly.
 import type { AgentMessage } from "openclaw/plugin-sdk/agent-core";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { MemoryCitationsMode } from "../config/types.memory.js";
diff --git a/src/context-engine/host-compat.test.ts b/src/context-engine/host-compat.test.ts
@@ -1,3 +1,4 @@
+// Context engine host compatibility tests cover host API compatibility behavior.
 import { describe, expect, it } from "vitest";
 import {
   assertContextEngineHostSupport,
diff --git a/src/i18n/registry.test.ts b/src/i18n/registry.test.ts
@@ -1,3 +1,4 @@
+// I18n registry tests cover locale bundle lookup and fallback behavior.
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
diff --git a/src/interactive/payload.test.ts b/src/interactive/payload.test.ts
@@ -1,3 +1,4 @@
+// Interactive payload tests cover validation of interactive response payloads.
 import { describe, expect, it } from "vitest";
 import {
   hasReplyChannelData,
diff --git a/src/interactive/payload.ts b/src/interactive/payload.ts
@@ -1,3 +1,4 @@
+// Interactive payload helpers normalize structured interactive UI payloads.
 import { asOptionalRecord as toRecord } from "@openclaw/normalization-core/record-coerce";
 import {
   normalizeOptionalLowercaseString,
diff --git a/src/memory-host-sdk/dreaming.test.ts b/src/memory-host-sdk/dreaming.test.ts
@@ -1,3 +1,4 @@
+// Memory host dreaming tests cover dreaming artifact persistence and lookup.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/memory-host-sdk/dreaming.ts b/src/memory-host-sdk/dreaming.ts
@@ -1,3 +1,4 @@
+// Memory host dreaming helpers record and load memory dreaming artifacts.
 import path from "node:path";
 import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";
 import {
diff --git a/src/memory-host-sdk/events.ts b/src/memory-host-sdk/events.ts
@@ -1,3 +1,4 @@
+// Memory host event helpers append and read memory host event logs.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { appendRegularFile } from "../infra/fs-safe.js";
diff --git a/src/memory-host-sdk/host/backend-config.test.ts b/src/memory-host-sdk/host/backend-config.test.ts
@@ -1,3 +1,4 @@
+// Memory host backend config tests cover backend configuration normalization.
 import { describe, expect, it } from "vitest";
 import { resolveMemoryBackendConfig as packageResolveMemoryBackendConfig } from "../../../packages/memory-host-sdk/src/host/backend-config.js";
 import { resolveMemoryBackendConfig } from "./backend-config.js";
diff --git a/src/plugin-state/plugin-state-store.e2e.test.ts b/src/plugin-state/plugin-state-store.e2e.test.ts
@@ -1,3 +1,4 @@
+// Plugin state store E2E tests cover persisted plugin state across runtime calls.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
 import {
diff --git a/src/plugin-state/plugin-state-store.runtime.test.ts b/src/plugin-state/plugin-state-store.runtime.test.ts
@@ -1,3 +1,4 @@
+// Plugin state runtime tests cover runtime-backed plugin state storage.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resolveStateDir } from "../config/paths.js";
 import type { PluginRecord } from "../plugins/registry-types.js";
diff --git a/src/plugin-state/plugin-state-store.sqlite.ts b/src/plugin-state/plugin-state-store.sqlite.ts
@@ -1,3 +1,4 @@
+// Plugin state SQLite helpers persist plugin state in the OpenClaw state database.
 import type { DatabaseSync } from "node:sqlite";
 import { resolveExpiresAtMsFromDurationMs } from "@openclaw/normalization-core/number-coercion";
 import type { Insertable, Selectable } from "kysely";
diff --git a/src/plugin-state/plugin-state-store.test-helpers.ts b/src/plugin-state/plugin-state-store.test-helpers.ts
@@ -1,3 +1,4 @@
+// Plugin state test helpers seed SQLite plugin state fixtures.
 import { seedPluginStateDatabaseEntriesForTests } from "./plugin-state-store.sqlite.js";
 
 // Test-only seed helpers for plugin state. Values are serialized through the
diff --git a/src/plugin-state/plugin-state-store.test.ts b/src/plugin-state/plugin-state-store.test.ts
@@ -1,3 +1,4 @@
+// Plugin state store tests cover per-plugin persisted state reads and writes.
 import { rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion";
diff --git a/src/plugin-state/plugin-state-store.ts b/src/plugin-state/plugin-state-store.ts
@@ -1,3 +1,4 @@
+// Plugin state store exposes persisted per-plugin state operations.
 import { closeOpenClawStateDatabaseForTest } from "../state/openclaw-state-db.js";
 import {
   clearPluginStateDatabaseForTests,
diff --git a/src/provider-runtime/operation-retry.test.ts b/src/provider-runtime/operation-retry.test.ts
@@ -1,3 +1,4 @@
+// Provider operation retry tests cover retry timing and abort behavior.
 import { describe, expect, it, vi } from "vitest";
 import {
   executeProviderOperationWithRetry,
diff --git a/src/provider-runtime/operation-retry.ts b/src/provider-runtime/operation-retry.ts
@@ -1,3 +1,4 @@
+// Provider operation retry helpers run retryable provider operations with backoff.
 import { sleepWithAbort } from "../infra/backoff.js";
 import { formatErrorMessage } from "../infra/errors.js";
 
diff --git a/src/realtime-transcription/provider-registry.ts b/src/realtime-transcription/provider-registry.ts
@@ -1,3 +1,4 @@
+// Realtime transcription provider registry stores transcription provider factories.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   resolvePluginCapabilityProvider,
diff --git a/src/realtime-transcription/provider-types.ts b/src/realtime-transcription/provider-types.ts
@@ -1,3 +1,4 @@
+// Realtime transcription provider types describe streaming transcription providers.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
 // Public contracts for realtime transcription provider plugins and sessions.
diff --git a/src/realtime-transcription/websocket-session.test.ts b/src/realtime-transcription/websocket-session.test.ts
@@ -1,3 +1,4 @@
+// Realtime transcription websocket tests cover websocket session lifecycle.
 import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/realtime-transcription/websocket-session.ts b/src/realtime-transcription/websocket-session.ts
@@ -1,3 +1,4 @@
+// Realtime transcription websocket session streams audio to transcription providers.
 import { randomUUID } from "node:crypto";
 import WebSocket, { type RawData } from "ws";
 import { createDebugProxyWebSocketAgent, resolveDebugProxySettings } from "../proxy-capture/env.js";
diff --git a/src/status/agent-runtime-label.ts b/src/status/agent-runtime-label.ts
@@ -1,3 +1,4 @@
+// Agent runtime label helpers format provider, model, and runtime labels.
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
diff --git a/src/status/fallback-notice-state.ts b/src/status/fallback-notice-state.ts
@@ -1,3 +1,4 @@
+// Fallback notice state helpers track fallback notices shown to users.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { areRuntimeModelRefsEquivalent } from "../agents/model-runtime-aliases.js";
 import type { SessionEntry } from "../config/sessions.js";
diff --git a/src/status/status-message.test.ts b/src/status/status-message.test.ts
@@ -1,3 +1,4 @@
+// Status message tests cover status message formatting and persistence.
 import { describe, expect, it } from "vitest";
 import { formatFastModeLabel } from "./status-labels.js";
 
diff --git a/src/status/status-message.ts b/src/status/status-message.ts
@@ -1,3 +1,4 @@
+// Status message helpers read and format stored status messages.
 import fs from "node:fs";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/status/status-text.ts b/src/status/status-text.ts
@@ -1,3 +1,4 @@
+// Status text helpers render runtime status summaries for CLI output.
 import os from "node:os";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import {
diff --git a/src/status/status-text.types.ts b/src/status/status-text.types.ts
@@ -1,3 +1,4 @@
+// Status text types describe runtime status records used by status rendering.
 import type {
   ElevatedLevel,
   ReasoningLevel,
diff --git a/src/web-search/runtime-types.ts b/src/web-search/runtime-types.ts
@@ -1,3 +1,4 @@
+// Web search runtime types describe search provider factories and dependencies.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type {
   PluginWebSearchProviderEntry,
diff --git a/src/web-search/runtime.test.ts b/src/web-search/runtime.test.ts
@@ -1,3 +1,4 @@
+// Web search runtime tests cover provider resolution and search execution.
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/web-search/runtime.ts b/src/web-search/runtime.ts
@@ -1,3 +1,4 @@
+// Web search runtime resolves configured search providers and executes searches.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Context engine tests cover context extraction and prompt context assembly.`
`1`	`2`	`import type { AgentMessage } from "openclaw/plugin-sdk/agent-core";`
`2`	`3`	`import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";`
`3`	`4`	`import type { MemoryCitationsMode } from "../config/types.memory.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Context engine host compatibility tests cover host API compatibility behavior.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`assertContextEngineHostSupport,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// I18n registry tests cover locale bundle lookup and fallback behavior.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import { fileURLToPath } from "node:url";`
`3`	`4`	`import { describe, expect, it } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Interactive payload tests cover validation of interactive response payloads.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`hasReplyChannelData,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Interactive payload helpers normalize structured interactive UI payloads.`
`1`	`2`	`import { asOptionalRecord as toRecord } from "@openclaw/normalization-core/record-coerce";`
`2`	`3`	`import {`
`3`	`4`	`normalizeOptionalLowercaseString,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Memory host dreaming tests cover dreaming artifact persistence and lookup.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/config.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Memory host dreaming helpers record and load memory dreaming artifacts.`
`1`	`2`	`import path from "node:path";`
`2`	`3`	`import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Memory host event helpers append and read memory host event logs.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { appendRegularFile } from "../infra/fs-safe.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Memory host backend config tests cover backend configuration normalization.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { resolveMemoryBackendConfig as packageResolveMemoryBackendConfig } from "../../../packages/memory-host-sdk/src/host/backend-config.js";`
`3`	`4`	`import { resolveMemoryBackendConfig } from "./backend-config.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Plugin state store E2E tests cover persisted plugin state across runtime calls.`
`1`	`2`	`import { afterEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";`
`3`	`4`	`import {`