docs: document shared helpers

src/shared/agent-run-status.test.ts

@@ -1,3 +1,4 @@
+// Agent run status tests cover status normalization for agent run records.
 import { describe, expect, it } from "vitest";
 import { isNonTerminalAgentRunStatus } from "./agent-run-status.js";
 

src/shared/assistant-error-format.ts

@@ -1,3 +1,4 @@
+// Assistant error formatting helpers normalize assistant-visible error payloads.
 const ERROR_PAYLOAD_PREFIX_RE =
   /^(?:error|(?:[a-z][\w-]*\s+)?api\s*error|apierror|openai\s*error|anthropic\s*error|gateway\s*error|codex\s*error)(?:\s+\d{3})?[:\s-]+/i;
 const HTTP_STATUS_DELIMITER_RE = /(?:\s*:\s*|\s+)/;

src/shared/assistant-identity-values.test.ts

@@ -1,3 +1,4 @@
+// Assistant identity tests cover normalized assistant names and metadata values.
 import { describe, expect, it } from "vitest";
 import { coerceIdentityValue } from "./assistant-identity-values.js";
 

src/shared/assistant-identity-values.ts

@@ -1,3 +1,4 @@
+// Assistant identity helpers normalize assistant identity labels and metadata.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Normalizes optional assistant identity fields and truncates them to the caller's limit. */

src/shared/avatar-policy.test.ts

@@ -1,3 +1,4 @@
+// Avatar policy tests cover avatar source resolution and fallback behavior.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {

src/shared/avatar-policy.ts

@@ -1,3 +1,4 @@
+// Avatar policy helpers resolve avatar paths and provider fallback rules.
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { isPathInside } from "../infra/path-guards.js";

src/shared/chat-content.test.ts

@@ -1,3 +1,4 @@
+// Chat content tests cover message content normalization for chat surfaces.
 import { describe, expect, it } from "vitest";
 import { extractTextFromChatContent } from "./chat-content.js";
 

src/shared/chat-envelope.test.ts

@@ -1,3 +1,4 @@
+// Chat envelope tests cover parsing and formatting channel-prefixed chat text.
 import { describe, expect, it } from "vitest";
 import { stripEnvelope, stripMessageIdHints } from "./chat-envelope.js";
 

src/shared/chat-envelope.ts

@@ -1,3 +1,4 @@
+// Chat envelope helpers parse and format channel prefixes in chat text.
 const ENVELOPE_PREFIX = /^\[([^\]]+)\]\s*/;
 const ENVELOPE_CHANNELS = [
   "WebChat",

src/shared/chat-message-content.test.ts

@@ -1,3 +1,4 @@
+// Chat message content tests cover visible text extraction from message parts.
 import { describe, expect, it } from "vitest";
 import {
   extractAssistantTextForPhase,

src/shared/chat-message-content.ts

@@ -1,3 +1,4 @@
+// Chat message content helpers extract user-visible text from mixed message parts.
 import { readStringValue } from "@openclaw/normalization-core/string-coerce";
 
 /** Returns inline string content or the first array text block without scanning later blocks. */

src/shared/config-eval.test.ts

@@ -1,3 +1,4 @@
+// Config eval tests cover dynamic config loading and evaluation guards.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";

src/shared/config-eval.ts

@@ -1,3 +1,4 @@
+// Config evaluation helpers load dynamic config modules with guarded evaluation.
 import fs from "node:fs";
 import path from "node:path";
 

src/shared/custom-command-config.ts

@@ -1,3 +1,4 @@
+// Custom command config helpers normalize command configuration records.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** Raw custom slash-command entry from config. */

src/shared/device-auth-store.test.ts

@@ -1,3 +1,4 @@
+// Device auth store tests cover persisted paired-device auth state.
 import { describe, expect, it, vi } from "vitest";
 import {
   clearDeviceAuthTokenFromStore,

src/shared/device-auth-store.ts

@@ -1,3 +1,4 @@
+// Device auth store helpers persist and normalize paired device auth records.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import {
   type DeviceAuthEntry,

src/shared/device-auth.test.ts

@@ -1,3 +1,4 @@
+// Device auth tests cover role and scope normalization for paired devices.
 import { describe, expect, it } from "vitest";
 import { normalizeDeviceAuthRole, normalizeDeviceAuthScopes } from "./device-auth.js";
 

src/shared/device-bootstrap-profile.test.ts

@@ -1,3 +1,4 @@
+// Device bootstrap profile tests cover profile normalization for paired devices.
 import { describe, expect, test } from "vitest";
 import {
   BOOTSTRAP_HANDOFF_OPERATOR_SCOPES,

src/shared/device-bootstrap-profile.ts

@@ -1,3 +1,4 @@
+// Device bootstrap profile helpers build profile claims for device onboarding.
 import { normalizeDeviceAuthRole, normalizeDeviceAuthScopes } from "./device-auth.js";
 
 /** Normalized roles/scopes carried by a bootstrap token during device handoff. */

src/shared/device-pairing-access.test.ts

@@ -1,3 +1,4 @@
+// Device pairing access tests cover role and scope checks for pairing requests.
 import { describe, expect, it } from "vitest";
 import { resolvePendingDeviceApprovalState } from "./device-pairing-access.js";
 

src/shared/device-pairing-access.ts

@@ -1,3 +1,4 @@
+// Device pairing access helpers evaluate pairing scopes and role permissions.
 import { normalizeDeviceAuthScopes } from "./device-auth.js";
 
 export type DevicePairingAccessSummary = {

src/shared/entry-metadata.test.ts

@@ -1,3 +1,4 @@
+// Entry metadata tests cover display metadata resolution for agents and jobs.
 import { describe, expect, it } from "vitest";
 import { resolveEmojiAndHomepage } from "./entry-metadata.js";
 

src/shared/entry-metadata.ts

@@ -1,3 +1,4 @@
+// Entry metadata helpers resolve display names, emojis, and homepage links.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Resolves entry emoji/homepage with metadata taking precedence over frontmatter aliases. */

src/shared/entry-status.test.ts

@@ -1,3 +1,4 @@
+// Entry status tests cover normalized status labels and terminal-state behavior.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { mockProcessPlatform } from "../test-utils/vitest-spies.js";
 import {

src/shared/entry-status.ts

@@ -1,3 +1,4 @@
+// Entry status helpers resolve display metadata for run and queue entries.
 import { resolveEmojiAndHomepage } from "./entry-metadata.js";
 import {
   evaluateRequirementsFromMetadataWithRemote,

src/shared/frontmatter.test.ts

@@ -1,3 +1,4 @@
+// Frontmatter tests cover shared Markdown frontmatter parsing helpers.
 import { describe, expect, it, test } from "vitest";
 import {
   applyOpenClawManifestInstallCommonFields,

src/shared/frontmatter.ts

@@ -1,3 +1,4 @@
+// Shared frontmatter helpers parse Markdown frontmatter blocks and body text.
 import {
   normalizeOptionalLowercaseString,
   readStringValue,

src/shared/gateway-bind-url.test.ts

@@ -1,3 +1,4 @@
+// Gateway bind URL tests cover host and port normalization for gateway listeners.
 import { describe, expect, it, vi } from "vitest";
 import { resolveGatewayBindUrl } from "./gateway-bind-url.js";
 

src/shared/gateway-bind-url.ts

@@ -1,3 +1,4 @@
+// Gateway bind URL helpers compute listener URLs from host and port settings.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 export type GatewayBindUrlResult =

src/shared/gateway-method-policy.ts

@@ -1,3 +1,4 @@
+// Gateway method policy helpers classify reserved and operator-only gateway methods.
 const RESERVED_ADMIN_GATEWAY_METHOD_PREFIXES = [
   "exec.approvals.",
   "config.",

src/shared/gateway-tailscale-auth-policy.ts

@@ -1,3 +1,4 @@
+// Gateway Tailscale auth policy helpers describe auth requirements for Tailscale modes.
 import type { GatewayAuthMode, GatewayTailscaleMode } from "../config/types.gateway.js";
 
 /** True when Tailscale exposure is configured without gateway authentication. */

src/shared/global-singleton.test.ts

@@ -1,3 +1,4 @@
+// Global singleton tests cover process-wide singleton creation and reset behavior.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resolveGlobalMap, resolveGlobalSingleton } from "./global-singleton.js";
 

src/shared/google-models.ts

@@ -1,3 +1,4 @@
+// Google model helpers normalize Google model identifiers and aliases.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** Return true when a model id/name refers to the Gemma 4 family. */

src/shared/google-turn-ordering.ts

@@ -1,3 +1,4 @@
+// Google turn ordering helpers keep Google model conversations in supported order.
 import type { AgentMessage } from "../agents/runtime/index.js";
 
 const GOOGLE_TURN_ORDER_BOOTSTRAP_TEXT = "(session bootstrap)";

src/shared/import-specifier.ts

@@ -1,3 +1,4 @@
+// Import specifier helpers convert paths to stable ESM import specifiers.
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 

src/shared/json-schema-defaults.ts

@@ -1,3 +1,4 @@
+// JSON schema default helpers fill object values from TypeBox schema defaults.
 import { Compile } from "typebox/compile";
 import type { JsonSchemaObject } from "./json-schema.types.js";
 import { parseConfigPathArrayIndex } from "./path-array-index.js";

src/shared/json-schema.types.ts

@@ -1,3 +1,4 @@
+// JSON schema shared types keep TypeBox schema aliases consistent across callers.
 import type { TSchema } from "typebox";
 
 /** TypeBox schema value widened for generic JSON-schema object transforms. */

src/shared/lazy-promise.test.ts

@@ -1,3 +1,4 @@
+// Lazy promise tests cover single-flight loading and error reuse behavior.
 import { describe, expect, it, vi } from "vitest";
 import { createLazyImportLoader, createLazyPromiseLoader } from "./lazy-promise.js";
 

src/shared/lazy-runtime.ts

@@ -1,3 +1,4 @@
+// Lazy runtime helpers expose dynamic imports through cached runtime surfaces.
 export function createLazyRuntimeSurface<TModule, TSurface>(
   importer: () => Promise<TModule>,
   select: (module: TModule) => TSurface,

src/shared/model-param-b.test.ts

@@ -1,3 +1,4 @@
+// Model parameter B tests cover reasoning budget normalization and aliases.
 import { describe, expect, it } from "vitest";
 import { inferParamBFromIdOrName } from "./model-param-b.js";
 

src/shared/model-param-b.ts

@@ -1,3 +1,4 @@
+// Model parameter B helpers normalize provider-specific reasoning budget values.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** Infers the largest `<number>b` parameter-size token from a model id or display name. */

src/shared/node-list-parse.test.ts

@@ -1,3 +1,4 @@
+// Node list parsing tests cover normalized node inventory records.
 import { describe, expect, it } from "vitest";
 import { parseNodeList, parsePairingList } from "./node-list-parse.js";
 

src/shared/node-list-parse.ts

@@ -1,3 +1,4 @@
+// Node list parsing helpers normalize node inventory records from CLI output.
 import { asRecord } from "@openclaw/normalization-core/record-coerce";
 import type { NodeListNode, PairedNode, PairingList, PendingRequest } from "./node-list-types.js";
 

src/shared/node-match.test.ts

@@ -1,3 +1,4 @@
+// Node match tests cover node selection from names, ids, and address hints.
 import { describe, expect, it } from "vitest";
 import { normalizeNodeKey, resolveNodeIdFromCandidates, resolveNodeMatches } from "./node-match.js";
 

src/shared/node-match.ts

@@ -1,3 +1,4 @@
+// Node match helpers score and select nodes from names, ids, and addresses.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,

src/shared/node-presence.ts

@@ -1,3 +1,4 @@
+// Node presence helpers normalize live node presence and heartbeat metadata.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Gateway event name used by node hosts to refresh their last-seen presence. */

src/shared/node-resolve.test.ts

@@ -1,3 +1,4 @@
+// Node resolve tests cover node identity and address resolution helpers.
 import { describe, expect, it } from "vitest";
 import { resolveNodeFromNodeList, resolveNodeIdFromNodeList } from "./node-resolve.js";
 

src/shared/node-resolve.ts

@@ -1,3 +1,4 @@
+// Node resolution helpers resolve node references from names, ids, and URLs.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { type NodeMatchCandidate, resolveNodeIdFromCandidates } from "./node-match.js";
 

src/shared/operator-scope-compat.test.ts

@@ -1,3 +1,4 @@
+// Operator scope compatibility tests cover legacy operator scope normalization.
 import { describe, expect, it } from "vitest";
 import {
   resolveMissingRequestedScope,

src/shared/operator-scope-compat.ts

@@ -1,3 +1,4 @@
+// Operator scope compatibility helpers normalize legacy operator role names.
 const OPERATOR_ROLE = "operator";
 const OPERATOR_ADMIN_SCOPE = "operator.admin";
 const OPERATOR_READ_SCOPE = "operator.read";

src/shared/pid-alive.test.ts

@@ -1,3 +1,4 @@
+// PID liveness tests cover process existence checks across platforms.
 import fsSync from "node:fs";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { withMockedPlatform } from "../test-utils/vitest-spies.js";

src/shared/pid-alive.ts

@@ -1,3 +1,4 @@
+// PID liveness helpers check whether process ids still refer to active processes.
 import fsSync from "node:fs";
 
 function isValidPid(pid: number): boolean {

src/shared/requirements.test.ts

@@ -1,3 +1,4 @@
+// Requirement tests cover merging and formatting runtime requirements.
 import { describe, expect, it } from "vitest";
 import {
   buildConfigChecks,

src/shared/requirements.ts

@@ -1,3 +1,4 @@
+// Requirement types describe runtime requirements advertised by shared surfaces.
 export type Requirements = {
   bins: string[];
   anyBins: string[];

src/shared/runtime-import.test.ts

@@ -1,3 +1,4 @@
+// Runtime import tests cover lazy runtime import caching and failure handling.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   importRuntimeModule,

src/shared/scoped-expiring-id-cache.test.ts

@@ -1,3 +1,4 @@
+// Scoped expiring id cache tests cover TTL and scope isolation behavior.
 import { describe, expect, it } from "vitest";
 import { createScopedExpiringIdCache } from "./scoped-expiring-id-cache.js";
 

src/shared/silent-reply-policy.test.ts

@@ -1,3 +1,4 @@
+// Silent reply policy tests cover reply suppression decision rules.
 import { describe, expect, it } from "vitest";
 import {
   DEFAULT_SILENT_REPLY_POLICY,

src/shared/silent-reply-policy.ts

@@ -1,3 +1,4 @@
+// Silent reply policy helpers decide when automated replies should be suppressed.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 export type SilentReplyPolicy = "allow" | "disallow";

src/shared/string-sample.test.ts

@@ -1,3 +1,4 @@
+// String sample tests cover compact string sampling and truncation behavior.
 import { describe, expect, it } from "vitest";
 import { summarizeStringEntries } from "./string-sample.js";
 

src/shared/subagents-format.test.ts

@@ -1,3 +1,4 @@
+// Subagent format tests cover concise subagent status and duration formatting.
 import { describe, expect, it } from "vitest";
 import {
   formatDurationCompact,

src/shared/subagents-format.ts

@@ -1,3 +1,4 @@
+// Subagent formatting helpers expose compact durations and status text.
 export { formatDurationCompact } from "../infra/format-time/format-duration.ts";
 
 /** Formats token counts using compact k/m suffixes for subagent summaries. */

src/shared/tailscale-status.test.ts

@@ -1,3 +1,4 @@
+// Tailscale status tests cover status parsing and validation.
 import { describe, expect, it, vi } from "vitest";
 import { resolveTailnetHostWithRunner } from "./tailscale-status.js";
 

src/shared/tailscale-status.ts

@@ -1,3 +1,4 @@
+// Tailscale status helpers parse and validate status payloads from Tailscale.
 import { z } from "zod";
 import { safeParseJsonWithSchema } from "../utils/zod-parse.js";
 

src/shared/text-chunking.test.ts

@@ -1,3 +1,4 @@
+// Text chunking tests cover splitting text into bounded model-safe chunks.
 import { describe, expect, it } from "vitest";
 import { chunkTextByBreakResolver } from "./text-chunking.js";
 

src/shared/text/assistant-visible-text.test.ts

@@ -1,3 +1,4 @@
+// Assistant visible text tests cover extracting user-visible assistant output.
 import { describe, expect, it } from "vitest";
 import {
   sanitizeAssistantVisibleText,

src/shared/text/assistant-visible-text.ts

@@ -1,3 +1,4 @@
+// Assistant visible text helpers strip hidden reasoning and control marker text.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 import { stripModelSpecialTokens } from "./model-special-tokens.js";

src/shared/text/auto-linked-file-ref.ts

@@ -1,3 +1,4 @@
+// Auto-linked file ref helpers detect file references that can be linked in UI text.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 const FILE_REF_EXTENSIONS = ["md", "go", "py", "pl", "sh", "am", "at", "be", "cc"] as const;

src/shared/text/citation-control-markers.test.ts

@@ -1,3 +1,4 @@
+// Citation control marker tests cover stripping unsupported citation markers.
 import { describe, expect, it } from "vitest";
 import { stripUnsupportedCitationControlMarkers } from "./citation-control-markers.js";
 

src/shared/text/citation-control-markers.ts

@@ -1,3 +1,4 @@
+// Citation control marker helpers remove unsupported citation control tokens.
 const UNSUPPORTED_CITATION_CONTROL_MARKER_RE = /cite(?:[^]*)?/g;
 const TRAILING_UNSUPPORTED_CITATION_CONTROL_MARKER_RE = /[ \t]*cite(?:[^]*)?(?=\r?\n|$)/g;
 

src/shared/text/code-regions.test.ts

@@ -1,3 +1,4 @@
+// Code region tests cover Markdown code span and fence detection.
 import { describe, expect, it } from "vitest";
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 

src/shared/text/code-regions.ts

@@ -1,3 +1,4 @@
+// Code region helpers find fenced and inline code spans in Markdown text.
 export interface CodeRegion {
   start: number;
   end: number;

src/shared/text/final-tags.ts

@@ -1,3 +1,4 @@
+// Final tag helpers detect final-answer tag regions in assistant text.
 export type FinalTagMatch = {
   index: number;
   text: string;

src/shared/text/formatted-reasoning-message.ts

@@ -1,3 +1,4 @@
+// Formatted reasoning message helpers remove reasoning tags before display.
 import { stripReasoningTagsFromText } from "./reasoning-tags.js";
 
 /** Strip provider-formatted Reasoning/Thinking preambles from visible text. */

src/shared/text/join-segments.test.ts

@@ -1,3 +1,4 @@
+// Join segment tests cover stable text segment recombination.
 import { describe, expect, it } from "vitest";
 import { concatOptionalTextSegments, joinPresentTextSegments } from "./join-segments.js";
 

src/shared/text/model-special-tokens.ts

@@ -1,3 +1,4 @@
+// Model special token helpers strip model control tokens outside code regions.
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 
 // Match both ASCII pipe <|...|> and full-width pipe <｜...｜> (U+FF5C) variants.

src/shared/text/reasoning-tag-text-partitioner.test.ts

@@ -1,3 +1,4 @@
+// Reasoning tag partitioner tests cover splitting reasoning and visible text segments.
 import { describe, expect, it } from "vitest";
 import { createReasoningTagTextPartitioner } from "./reasoning-tag-text-partitioner.js";
 

src/shared/text/reasoning-tag-text-partitioner.ts

@@ -1,3 +1,4 @@
+// Reasoning tag partitioner helpers split text around reasoning tag regions.
 import {
   buildCodeSpanIndex,
   createInlineCodeState,

src/shared/text/reasoning-tags.test.ts

@@ -1,3 +1,4 @@
+// Reasoning tag tests cover parsing and stripping reasoning tag blocks.
 import { describe, expect, it } from "vitest";
 import { stripReasoningTagsFromText } from "./reasoning-tags.js";
 

src/shared/text/reasoning-tags.ts

@@ -1,3 +1,4 @@
+// Reasoning tag helpers find and remove model reasoning tag blocks from text.
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 import { findFinalTagMatches } from "./final-tags.js";
 export type ReasoningTagMode = "strict" | "preserve";

src/shared/text/tool-call-shaped-text.test.ts

@@ -1,3 +1,4 @@
+// Tool-call shaped text tests cover detection of text that resembles tool calls.
 import { describe, expect, it } from "vitest";
 import { detectToolCallShapedText } from "./tool-call-shaped-text.js";
 

src/shared/text/tool-call-shaped-text.ts

@@ -1,3 +1,4 @@
+// Tool-call shaped text helpers detect malformed text that resembles tool calls.
 import { asOptionalRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalString as readTrimmedString } from "@openclaw/normalization-core/string-coerce";
 

src/shared/thread-binding-lifecycle.test.ts

@@ -1,3 +1,4 @@
+// Thread binding lifecycle tests cover binding states across channel threads.
 import { describe, expect, it } from "vitest";
 import { resolveThreadBindingLifecycle } from "./thread-binding-lifecycle.js";
 

src/shared/usage-aggregates.test.ts

@@ -1,3 +1,4 @@
+// Usage aggregate tests cover token, cost, and latency accumulation.
 import { describe, expect, it } from "vitest";
 import {
   buildUsageAggregateTail,

src/shared/usage-aggregates.ts

@@ -1,3 +1,4 @@
+// Usage aggregate helpers accumulate token, cost, and latency usage totals.
 type LatencyTotalsLike = {
   count: number;
   sum: number;

src/shared/usage-types.ts

@@ -1,3 +1,4 @@
+// Usage types define shared usage accounting structures for sessions and runs.
 import type { SessionSystemPromptReport } from "../config/sessions/types.js";
 import type {
   CostUsageSummary,