docs: document agent test helpers

src/agents/test-helpers/agent-tool-stubs.ts

@@ -1,6 +1,10 @@
 import { Type } from "typebox";
 import type { AgentTool, AgentToolResult } from "../runtime/index.js";
 
+/**
+ * Small reusable agent-tool stubs for tests that only need inventory shape.
+ */
+/** Creates a no-op tool with an empty object schema. */
 export function createStubTool(name: string): AgentTool {
   return {
     name,

src/agents/test-helpers/agent-tools-fs-helpers.ts

@@ -1,7 +1,11 @@
 import { expect } from "vitest";
 
+/**
+ * Assertion helpers for built-in filesystem tool tests.
+ */
 type TextResultBlock = { type: string; text?: string };
 
+/** Extracts the first text block from a tool result. */
 export function getTextContent(result?: { content?: TextResultBlock[] }) {
   const textBlock = result?.content?.find((block) => block.type === "text");
   return textBlock?.text ?? "";
@@ -15,6 +19,7 @@ function expectTool<T extends { name: string }>(tools: T[], name: string): T {
   return tool;
 }
 
+/** Asserts read/write/edit tools are present and returns them by name. */
 export function expectReadWriteEditTools<T extends { name: string }>(tools: T[]) {
   const names = tools.map((tool) => tool.name);
   expect(names).toContain("read");
@@ -27,6 +32,7 @@ export function expectReadWriteEditTools<T extends { name: string }>(tools: T[])
   };
 }
 
+/** Asserts read/write tools are present and returns them by name. */
 export function expectReadWriteTools<T extends { name: string }>(tools: T[]) {
   const names = tools.map((tool) => tool.name);
   expect(names).toContain("read");

src/agents/test-helpers/agent-tools-sandbox-context.ts

@@ -1,6 +1,9 @@
 import type { SandboxContext, SandboxToolPolicy, SandboxWorkspaceAccess } from "../sandbox.js";
 import type { SandboxFsBridge } from "../sandbox/fs-bridge.js";
 
+/**
+ * Sandbox context fixture builder for agent-tool tests.
+ */
 type AgentToolsSandboxContextParams = {
   workspaceDir: string;
   agentWorkspaceDir?: string;
@@ -14,6 +17,7 @@ type AgentToolsSandboxContextParams = {
   dockerOverrides?: Partial<SandboxContext["docker"]>;
 };
 
+/** Builds a Docker-shaped sandbox context with safe test defaults. */
 export function createAgentToolsSandboxContext(
   params: AgentToolsSandboxContextParams,
 ): SandboxContext {

src/agents/test-helpers/fast-bash-tools.ts

@@ -1,6 +1,9 @@
 import { vi } from "vitest";
 import { stubTool } from "./fast-tool-stubs.js";
 
+/**
+ * Fast Vitest mock for bash tool registration in tests that only need tool inventory.
+ */
 vi.mock("../bash-tools.js", () => ({
   createExecTool: () => stubTool("exec"),
   createProcessTool: () => stubTool("process"),

src/agents/test-helpers/fast-coding-tools.ts

@@ -1 +1,4 @@
+/**
+ * Fast coding-tool helper side-effect import for tests that use shared tool stubs.
+ */
 import "./fast-tool-stubs.js";

src/agents/test-helpers/fast-openclaw-tools.ts

@@ -1,6 +1,9 @@
 import { vi } from "vitest";
 import { stubTool } from "./fast-tool-stubs.js";
 
+/**
+ * Fast Vitest mock for the OpenClaw tool bundle used by inventory-heavy tests.
+ */
 function stubActionTool(name: string, actions: string[]) {
   return {
     ...stubTool(name),
@@ -57,6 +60,8 @@ const createOpenClawToolsMock = vi.fn(
   },
 );
 
+// Preserve action enums for tools whose tests assert schema/inventory behavior without paying the
+// cost of constructing the real tool bundle.
 vi.mock("../openclaw-tools.js", () => ({
   createOpenClawTools: createOpenClawToolsMock,
   testing: {

src/agents/test-helpers/host-sandbox-fs-bridge.ts

@@ -3,6 +3,10 @@ import path from "node:path";
 import { resolveSandboxPath } from "../sandbox-paths.js";
 import type { SandboxFsBridge, SandboxFsStat, SandboxResolvedPath } from "../sandbox/fs-bridge.js";
 
+/**
+ * Host-backed sandbox filesystem bridge fixtures for tests.
+ */
+/** Creates a sandbox fs bridge from a caller-provided path resolver. */
 export function createSandboxFsBridgeFromResolver(
   resolvePath: (filePath: string, cwd?: string) => SandboxResolvedPath,
 ): SandboxFsBridge {
@@ -76,6 +80,7 @@ export function createSandboxFsBridgeFromResolver(
   };
 }
 
+/** Creates a sandbox fs bridge rooted at a real host directory. */
 export function createHostSandboxFsBridge(rootDir: string): SandboxFsBridge {
   const root = path.resolve(rootDir);
 

src/agents/test-helpers/session-config.ts

@@ -1,5 +1,9 @@
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 
+/**
+ * Session config fixtures shared by agent/session tests.
+ */
+/** Builds a per-sender session config with optional targeted overrides. */
 export function createPerSenderSessionConfig(
   overrides: Partial<NonNullable<OpenClawConfig["session"]>> = {},
 ): NonNullable<OpenClawConfig["session"]> {