docs: document workspace transport tests

steipete · steipete · commit ff254a44c969 · 2026-06-04T16:01:19.000-04:00
diff --git a/src/agents/transport-message-transform.test.ts b/src/agents/transport-message-transform.test.ts
@@ -1,3 +1,5 @@
+// Transport message transform tests cover replay cleanup for provider-specific
+// tool-call/result sequencing before messages are sent back to transports.
 import type { Api, Context, Model } from "openclaw/plugin-sdk/llm";
 import { describe, expect, it } from "vitest";
 import { transformTransportMessages } from "./transport-message-transform.js";
@@ -139,6 +141,8 @@ describe("transformTransportMessages synthetic tool-result policy", () => {
   });
 
   it("moves displaced OpenAI transport results before synthesizing missing siblings", () => {
+    // OpenAI requires tool results immediately after the assistant tool call;
+    // displaced results are moved back before any missing siblings are aborted.
     const messages: Context["messages"] = [
       {
         ...assistantToolCall("call_keep"),
diff --git a/src/agents/transport-stream-shared.test.ts b/src/agents/transport-stream-shared.test.ts
@@ -1,3 +1,5 @@
+// Transport stream shared tests cover payload sanitization, header merging, and
+// final/error stream termination helpers used by provider transports.
 import { describe, expect, it, vi } from "vitest";
 import {
   failTransportStream,
@@ -74,6 +76,8 @@ describe("transport stream shared helpers", () => {
   });
 
   it("marks transport stream failures and runs cleanup", () => {
+    // Failure finalization mutates the output message before emitting it so
+    // downstream transcript consumers see the same error state as the stream.
     const push = vi.fn();
     const end = vi.fn();
     const cleanup = vi.fn();
diff --git a/src/agents/workspace-run.test.ts b/src/agents/workspace-run.test.ts
@@ -1,3 +1,5 @@
+// Workspace run tests cover runtime workspace resolution from explicit input,
+// agent config, session keys, and environment fallback.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
@@ -104,6 +106,8 @@ describe("resolveRunWorkspaceDir", () => {
   });
 
   it("throws for malformed agent session keys even when config has a default agent", () => {
+    // Malformed agent-prefixed keys are configuration/data errors; default
+    // agents should not mask them as legacy main-session keys.
     const mainWorkspace = path.join(process.cwd(), "tmp", "workspace-main-default");
     const researchWorkspace = path.join(process.cwd(), "tmp", "workspace-research-default");
     const cfg = {
diff --git a/src/agents/workspace.defaults.test.ts b/src/agents/workspace.defaults.test.ts
@@ -1,3 +1,5 @@
+// Workspace default tests cover environment-variable precedence for the
+// built-in agent workspace location.
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resolveDefaultAgentWorkspaceDir } from "./workspace.js";
diff --git a/src/agents/workspace.load-extra-bootstrap-files.test.ts b/src/agents/workspace.load-extra-bootstrap-files.test.ts
@@ -1,3 +1,5 @@
+// Extra bootstrap file tests cover glob/literal path loading, workspace
+// containment checks, symlink handling, and diagnostics for skipped files.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -117,6 +119,8 @@ describe("loadExtraBootstrapFiles", () => {
   });
 
   it("rejects hardlinked aliases to files outside workspace", async () => {
+    // Hardlinks can look like in-workspace files by path; inode/realpath checks
+    // keep outside bootstrap content from entering the prompt.
     if (process.platform === "win32") {
       return;
     }
diff --git a/src/agents/workspace.test.ts b/src/agents/workspace.test.ts
@@ -1,3 +1,5 @@
+// Workspace tests cover bootstrap seeding, attestation safety, bootstrap file
+// filtering, and setup-completion state for agent workspaces.
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -90,6 +92,8 @@ async function expectWorkspaceVanished(
   action: Promise<unknown>,
   expected?: { attestationPath?: string },
 ): Promise<void> {
+  // Recently attested generated workspaces must not be silently recreated after
+  // deletion or wipe; that could hide user data loss.
   await expect(action).rejects.toMatchObject({
     code: WORKSPACE_VANISHED_ERROR_CODE,
     name: "WorkspaceVanishedError",
@@ -221,6 +225,8 @@ describe("ensureAgentWorkspace", () => {
   });
 
   it("accepts a recently attested workspace when customized AGENTS.md survives", async () => {
+    // Custom instructions prove the directory is user-managed, so reseeding is
+    // skipped and the workspace is accepted.
     const tempDir = await makeTempWorkspace("openclaw-workspace-");
     await ensureAgentWorkspace({ dir: tempDir, ensureBootstrapFiles: true });
     await fs.writeFile(path.join(tempDir, DEFAULT_AGENTS_FILENAME), "custom instructions\n");

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Workspace default tests cover environment-variable precedence for the`
	`2`	`+// built-in agent workspace location.`
`1`	`3`	`import path from "node:path";`
`2`	`4`	`import { afterEach, describe, expect, it, vi } from "vitest";`
`3`	`5`	`import { resolveDefaultAgentWorkspaceDir } from "./workspace.js";`