docs: document utility helpers

src/utils/account-id.ts

@@ -1,3 +1,4 @@
+// Account id helpers normalize routing account identifiers for utility callers.
 import { normalizeOptionalAccountId } from "../routing/account-id.js";
 
 /**

src/utils/boolean.ts

@@ -1,3 +1,4 @@
+// Boolean utility helpers normalize string-like boolean inputs.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 
 /**

src/utils/cjk-chars.test.ts

@@ -1,3 +1,4 @@
+// CJK character tests cover detection and width handling for CJK text.
 import { describe, expect, it } from "vitest";
 import {
   CHARS_PER_TOKEN_ESTIMATE,

src/utils/delivery-context.shared.ts

@@ -1,3 +1,4 @@
+// Shared delivery context helpers expose route normalization shared by modules.
 import {
   channelRouteCompactKey,
   channelRouteThreadId,

src/utils/delivery-context.test.ts

@@ -1,3 +1,4 @@
+// Delivery context tests cover context normalization for channel delivery.
 import { beforeEach, describe, expect, it } from "vitest";
 import { setActivePluginRegistry } from "../plugins/runtime.js";
 import { createChannelTestPluginBase, createTestRegistry } from "../test-utils/channel-plugins.js";

src/utils/delivery-context.ts

@@ -1,3 +1,4 @@
+// Delivery context helpers normalize target and route metadata for delivery.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { getChannelPlugin, normalizeChannelId } from "../channels/plugins/index.js";
 import { normalizeMessageChannel } from "./message-channel.js";

src/utils/delivery-context.types.ts

@@ -1,3 +1,4 @@
+// Delivery context types describe normalized channel route delivery inputs.
 import type { ChannelRouteRef, ChannelRouteTargetInput } from "../plugin-sdk/channel-route.js";
 
 /** Deferred outbound delivery intent attached to a session or task. */

src/utils/directive-tags.test.ts

@@ -1,3 +1,4 @@
+// Directive tag tests cover parsing and filtering inline directive tags.
 import { describe, expect, test } from "vitest";
 import {
   parseInlineDirectives,

src/utils/directive-tags.ts

@@ -1,3 +1,4 @@
+// Directive tag helpers parse inline directive tags from user text.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 export type InlineDirectiveParseResult = {

src/utils/fetch-timeout.test.ts

@@ -1,3 +1,4 @@
+// Fetch timeout tests cover abort handling and streamed response timeouts.
 import { Stream } from "openai/streaming";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 

src/utils/fetch-timeout.ts

@@ -1,3 +1,4 @@
+// Fetch timeout helpers wrap fetch calls with timeout and abort behavior.
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { resolveSafeTimeoutDelayMs } from "./timer-delay.js";
 

src/utils/mask-api-key.test.ts

@@ -1,3 +1,4 @@
+// API key masking tests cover redaction of provider credential values.
 import { describe, expect, it } from "vitest";
 import { maskApiKey } from "./mask-api-key.js";
 

src/utils/message-channel-constants.ts

@@ -1,3 +1,4 @@
+// Message channel constants define internal channel ids shared across routing.
 export const INTERNAL_MESSAGE_CHANNEL = "webchat" as const;
 export type InternalMessageChannel = typeof INTERNAL_MESSAGE_CHANNEL;
 

src/utils/message-channel-core.ts

@@ -1,3 +1,4 @@
+// Message channel core helpers normalize channel families and internal ids.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeChatChannelId } from "../channels/ids.js";
 import { normalizeAnyChannelId } from "../channels/registry-normalize.js";

src/utils/message-channel-normalize.ts

@@ -1,3 +1,4 @@
+// Message channel normalization helpers canonicalize channel identifiers and aliases.
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { CHANNEL_IDS } from "../channels/ids.js";
 import { listRegisteredChannelPluginIds } from "../channels/registry.js";

src/utils/message-channel.test.ts

@@ -1,3 +1,4 @@
+// Message channel tests cover channel id normalization and routing helpers.
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";

src/utils/message-channel.ts

@@ -1,3 +1,4 @@
+// Message channel helpers classify and format channel identifiers.
 import {
   GATEWAY_CLIENT_MODES,
   GATEWAY_CLIENT_NAMES,

src/utils/normalize-secret-input.test.ts

@@ -1,3 +1,4 @@
+// Secret input normalization tests cover trimming and empty-value handling.
 import { describe, expect, it } from "vitest";
 import { normalizeOptionalSecretInput, normalizeSecretInput } from "./normalize-secret-input.js";
 

src/utils/provider-utils.test.ts

@@ -1,3 +1,4 @@
+// Provider utility tests cover provider normalization and utility behavior.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const { resolveProviderReasoningOutputModeWithPluginMock } = vi.hoisted(() => ({

src/utils/queue-helpers.test.ts

@@ -1,3 +1,4 @@
+// Queue helper tests cover queue ordering and dedupe utility behavior.
 import { describe, expect, it } from "vitest";
 import {
   applyQueueRuntimeSettings,

src/utils/reaction-level.test.ts

@@ -1,3 +1,4 @@
+// Reaction level tests cover normalization of reaction intensity values.
 import { describe, expect, it } from "vitest";
 import { resolveReactionLevel } from "./reaction-level.js";
 

src/utils/run-with-concurrency.test.ts

@@ -1,3 +1,4 @@
+// Concurrency runner tests cover bounded parallel task execution.
 import { describe, expect, it, vi } from "vitest";
 import { runTasksWithConcurrency } from "./run-with-concurrency.js";
 

src/utils/shell-argv.ts

@@ -1,3 +1,4 @@
+// Shell argv helpers quote and parse shell-style argument strings.
 const DOUBLE_QUOTE_ESCAPES = new Set(["\\", '"', "$", "`", "\n", "\r"]);
 
 // POSIX double quotes only consume the backslash before a small escape set;

src/utils/timer-delay.test.ts

@@ -1,3 +1,4 @@
+// Timer delay tests cover safe timeout clamping and scheduling behavior.
 import { describe, expect, it, vi } from "vitest";
 import { MAX_SAFE_TIMEOUT_DELAY_MS, setSafeTimeout } from "./timer-delay.js";
 

src/utils/timer-delay.ts

@@ -1,3 +1,4 @@
+// Timer delay helpers clamp delays to runtime-safe timeout values.
 import { resolveSafeTimeoutDelayMs } from "../../packages/gateway-client/src/timeouts.js";
 
 export {

src/utils/transcript-tools.test.ts

@@ -1,3 +1,4 @@
+// Transcript tool tests cover transcript utility parsing and formatting.
 import { describe, expect, it } from "vitest";
 import { countToolResults, extractToolCallNames, hasToolCall } from "./transcript-tools.js";
 

src/utils/usage-format.test.ts

@@ -1,3 +1,4 @@
+// Usage format tests cover display formatting for token and cost usage.
 import nodeFs from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";

src/utils/utils-misc.test.ts

@@ -1,3 +1,4 @@
+// Misc utility tests cover small shared helper behavior.
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
 import { asBoolean, parseBooleanValue } from "./boolean.js";

src/utils/zod-parse.ts

@@ -1,3 +1,4 @@
+// Zod parse helpers wrap schema parsing with consistent error handling.
 import type { ZodType } from "zod";
 
 /**