docs: document agent command tests

steipete · steipete · commit a767c6d1df23 · 2026-06-04T14:12:48.000-04:00
diff --git a/src/agents/codex-native-web-search.test.ts b/src/agents/codex-native-web-search.test.ts
@@ -1,3 +1,4 @@
+// Covers Codex-native web search activation and payload projection.
 import { describe, expect, it } from "vitest";
 import {
   buildCodexNativeWebSearchTool,
@@ -47,6 +48,8 @@ describe("resolveCodexNativeSearchActivation", () => {
   });
 
   it("activates for direct openai when auth exists", () => {
+    // Direct OpenAI needs bridgeable auth before OpenClaw can suppress the
+    // managed web-search tool in favor of Codex native search.
     const result = resolveCodexNativeSearchActivation({
       config: {
         ...baseConfig,
@@ -79,6 +82,8 @@ describe("resolveCodexNativeSearchActivation", () => {
   });
 
   it("activates for api-compatible openai-chatgpt-responses providers without separate Codex auth", () => {
+    // Gateway-style providers already execute through a compatible Responses
+    // API, so native search can be enabled without a separate OpenAI profile.
     const result = resolveCodexNativeSearchActivation({
       config: baseConfig,
       modelProvider: "gateway",
@@ -188,6 +193,8 @@ describe("Codex native web-search payload helpers", () => {
 
   it("injects native web_search into provider payloads", () => {
     const payload: Record<string, unknown> = { tools: [{ type: "function", name: "read" }] };
+    // Payload patching mutates the provider request in place because callers
+    // already hold the request object that will be sent to the model runtime.
     const result = patchCodexNativeWebSearchPayload({ payload, config: baseConfig });
 
     expect(result.status).toBe("injected");
@@ -228,6 +235,8 @@ describe("shouldSuppressManagedWebSearchTool", () => {
 
 describe("isCodexNativeWebSearchRelevant", () => {
   it("treats a default model with model-level openai-chatgpt-responses api as relevant", () => {
+    // Provider-level APIs can be generic while individual models opt into the
+    // ChatGPT Responses shape that supports native web_search.
     expect(
       isCodexNativeWebSearchRelevant({
         config: {
diff --git a/src/agents/command-poll-backoff.test.ts b/src/agents/command-poll-backoff.test.ts
@@ -1,3 +1,4 @@
+// Verifies command polling backoff state used by diagnostic/session commands.
 import { describe, expect, it } from "vitest";
 import type { SessionState } from "../logging/diagnostic-session-state.js";
 import {
@@ -39,7 +40,8 @@ describe("command-poll-backoff", () => {
       };
       const retryMs = recordCommandPoll(state, "cmd-123", false);
       expect(retryMs).toBe(5000);
-      expect(state.commandPollCounts?.get("cmd-123")?.count).toBe(0); // First poll = index 0
+      // Poll counts are zero-based indexes into the backoff schedule.
+      expect(state.commandPollCounts?.get("cmd-123")?.count).toBe(0);
     });
 
     it("increments count and increases backoff on consecutive no-output polls", () => {
@@ -49,13 +51,13 @@ describe("command-poll-backoff", () => {
         queueDepth: 0,
       };
 
-      expect(recordCommandPoll(state, "cmd-123", false)).toBe(5000); // count=0 -> 5s
-      expect(recordCommandPoll(state, "cmd-123", false)).toBe(10000); // count=1 -> 10s
-      expect(recordCommandPoll(state, "cmd-123", false)).toBe(30000); // count=2 -> 30s
-      expect(recordCommandPoll(state, "cmd-123", false)).toBe(60000); // count=3 -> 60s
-      expect(recordCommandPoll(state, "cmd-123", false)).toBe(60000); // count=4 -> 60s (capped)
+      expect(recordCommandPoll(state, "cmd-123", false)).toBe(5000);
+      expect(recordCommandPoll(state, "cmd-123", false)).toBe(10000);
+      expect(recordCommandPoll(state, "cmd-123", false)).toBe(30000);
+      expect(recordCommandPoll(state, "cmd-123", false)).toBe(60000);
+      expect(recordCommandPoll(state, "cmd-123", false)).toBe(60000);
 
-      expect(state.commandPollCounts?.get("cmd-123")?.count).toBe(4); // 5 polls = index 4
+      expect(state.commandPollCounts?.get("cmd-123")?.count).toBe(4);
     });
 
     it("resets count when poll returns new output", () => {
@@ -70,9 +72,9 @@ describe("command-poll-backoff", () => {
       recordCommandPoll(state, "cmd-123", false);
       expect(state.commandPollCounts?.get("cmd-123")?.count).toBe(2); // 3 polls = index 2
 
-      // New output resets count
+      // New output resets count so the next quiet poll starts at the fast lane.
       const retryMs = recordCommandPoll(state, "cmd-123", true);
-      expect(retryMs).toBe(5000); // Back to first poll delay
+      expect(retryMs).toBe(5000);
       expect(state.commandPollCounts?.get("cmd-123")?.count).toBe(0);
     });
 
@@ -150,12 +152,12 @@ describe("command-poll-backoff", () => {
         state: "processing",
         queueDepth: 0,
         commandPollCounts: new Map([
-          ["cmd-old", { count: 5, lastPollAt: Date.now() - 7200000 }], // 2 hours ago
-          ["cmd-new", { count: 3, lastPollAt: Date.now() - 1000 }], // 1 second ago
+          ["cmd-old", { count: 5, lastPollAt: Date.now() - 7200000 }],
+          ["cmd-new", { count: 3, lastPollAt: Date.now() - 1000 }],
         ]),
       };
 
-      pruneStaleCommandPolls(state, 3600000); // 1 hour max age
+      pruneStaleCommandPolls(state, 3600000);
 
       expect(state.commandPollCounts?.has("cmd-old")).toBe(false);
       expect(state.commandPollCounts?.has("cmd-new")).toBe(true);
diff --git a/src/agents/command/attempt-callbacks.test.ts b/src/agents/command/attempt-callbacks.test.ts
@@ -1,3 +1,4 @@
+// Verifies the small lifecycle callback adapter used during agent attempts.
 import { describe, expect, it } from "vitest";
 import { createAgentAttemptLifecycleCallbacks } from "./attempt-callbacks.js";
 
@@ -10,6 +11,8 @@ describe("createAgentAttemptLifecycleCallbacks", () => {
     };
     const callbacks = createAgentAttemptLifecycleCallbacks(state);
 
+    // The callback mutates only the shared lifecycle state object; it should not
+    // need access to the wider runAgentAttempt closure.
     callbacks.onUserMessagePersisted?.({
       role: "user",
       content: "hello",
diff --git a/src/agents/command/attempt-execution.cli.test.ts b/src/agents/command/attempt-execution.cli.test.ts
@@ -1,3 +1,4 @@
+// Covers CLI-backed attempt execution and session-binding persistence.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -49,6 +50,8 @@ vi.mock("../model-runtime-aliases.js", async () => {
       modelId?: string;
     }) => {
       const key = provider && modelId ? `${provider}/${modelId}` : undefined;
+      // Runtime alias tests only need the model-level runtime override path;
+      // keeping the mock narrow avoids loading provider catalogs here.
       const runtime = key
         ? cfg?.agents?.defaults?.models?.[key]?.agentRuntime?.id?.trim()
         : undefined;
@@ -109,6 +112,8 @@ async function readSessionFileEntries(sessionFile: string) {
 }
 
 async function readSessionFileJsonLines<T>(sessionFile: string): Promise<T[]> {
+  // Session transcripts are JSONL; tests preserve that format so parent/child
+  // id ordering and append behavior are covered end-to-end.
   const raw = await fs.readFile(sessionFile, "utf-8");
   const entries: T[] = [];
   for (const line of raw.split(/\r?\n/)) {
@@ -218,6 +223,8 @@ describe("CLI attempt execution", () => {
   }
 
   async function writeClaudeCliAssistantTranscript(cliSessionId: string) {
+    // Claude stores resumable sessions under a workspace-derived project dir,
+    // so stale-session tests must create the same on-disk shape.
     const homeDir = path.join(tmpDir, `home-${cliSessionId}`);
     const projectsDir = resolveClaudeCliProjectDirForWorkspace({
       workspaceDir: tmpDir,
@@ -279,6 +286,8 @@ describe("CLI attempt execution", () => {
     const sessionStore: Record<string, SessionEntry> = { [sessionKey]: sessionEntry };
     await fs.writeFile(storePath, JSON.stringify(sessionStore, null, 2), "utf-8");
 
+    // The retry hook must clear poisoned bindings before the fresh CLI attempt
+    // runs, otherwise the runner would resume the same expired Claude session.
     runCliAgentMock.mockImplementationOnce(async (args: unknown) => {
       const retry = requireRecord(args, "run CLI agent argument").onBeforeFreshCliSessionRetry;
       expect(retry).toBeTypeOf("function");
@@ -425,6 +434,8 @@ describe("CLI attempt execution", () => {
     const sessionEntry = makeClaudeCliSessionEntry("session-storeless", cliSessionId);
     runCliAgentMock.mockResolvedValueOnce(makeCliResult("storeless ok"));
 
+    // Storeless attempts cannot persist binding cleanup, so installing the hook
+    // would only give callers a false sense that stale state was repaired.
     await runAgentAttempt({
       providerOverride: "claude-cli",
       originalProvider: "claude-cli",
diff --git a/src/agents/command/attempt-execution.error-propagation.test.ts b/src/agents/command/attempt-execution.error-propagation.test.ts
@@ -1,3 +1,4 @@
+// Covers ACP diagnostic event propagation and sanitized error formatting.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { AcpRuntimeError } from "../../acp/runtime/errors.js";
 import {
@@ -18,6 +19,8 @@ let unsubscribe: (() => void) | undefined;
 beforeEach(() => {
   resetAgentEventsForTest();
   captured = [];
+  // Subscribe to the process-level event bus so tests observe exactly what
+  // parent relay diagnostics would receive.
   unsubscribe = onAgentEvent((evt) => {
     captured.push(evt);
   });
@@ -95,6 +98,8 @@ describe("emitAcpLifecycleError preserves AcpRuntimeError detail (regression: op
   });
 
   it("flattens the cause chain into the error string so the underlying RequestError is not lost", () => {
+    // ACP callers historically surface a single string; flattening preserves
+    // the useful nested RequestError without exposing structured internals.
     const rootCause = new Error('RequestError: "Method not found": nes/close (-32601)');
     const wrapped = new Error("Agent does not support session/close (oneshot:abc)", {
       cause: rootCause,
diff --git a/src/agents/command/attempt-execution.shared.test.ts b/src/agents/command/attempt-execution.shared.test.ts
@@ -1,3 +1,5 @@
+// Covers shared attempt-execution helpers for prompt materialization and
+// guarded session-store persistence.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -14,6 +16,8 @@ import {
 import type { AgentCommandOpts } from "./types.js";
 
 function makeTaskCompletionEvents(): NonNullable<AgentCommandOpts["internalEvents"]> {
+  // The result deliberately contains internal markers to prove child output
+  // cannot spoof OpenClaw runtime-context envelopes.
   return [
     {
       type: "task_completion",
@@ -50,6 +54,8 @@ describe("attempt execution prompt materialization", () => {
 
     const prompt = resolveAcpPromptBody(body, events);
 
+    // ACP receives visible event text, while private runtime envelopes stay out
+    // of the model-facing prompt.
     expect(prompt).toContain("A background task completed.");
     expect(prompt).toContain("inspect ACP delivery");
     expect(prompt).toContain("child result");
@@ -92,6 +98,8 @@ describe("persistSessionEntry", () => {
         },
       };
 
+      // A guarded write can decline persistence after rereading disk; local
+      // memory must be cleared too so later turns do not reuse stale entries.
       const persisted = await persistSessionEntry({
         sessionStore,
         sessionKey: "main",
diff --git a/src/agents/command/attempt-execution.test.ts b/src/agents/command/attempt-execution.test.ts
@@ -1,3 +1,5 @@
+// Covers attempt-execution helper behavior around retries, Claude CLI
+// transcripts, and ACP visible text accumulation.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -86,6 +88,8 @@ describe("resolveFallbackRetryPrompt", () => {
 
   it("prepends priorContextPrelude before the retry marker on fallback retry", () => {
     const prelude = "## Prior session context (from claude-cli)\nuser: prior question";
+    // Claude fallback prelude must come before the retry marker so the model
+    // receives prior CLI context before the instruction about failure recovery.
     const result = resolveFallbackRetryPrompt({
       body: originalBody,
       isFallbackRetry: true,
@@ -150,6 +154,8 @@ describe("formatClaudeCliFallbackPrelude", () => {
   });
 
   it("formats user/assistant turns and tags tool blocks with compact hints", () => {
+    // Tool-use blocks are represented as compact hints because fallback prompts
+    // should preserve intent without replaying full tool schemas or outputs.
     const out = formatClaudeCliFallbackPrelude({
       recentTurns: [
         {
@@ -200,7 +206,7 @@ describe("formatClaudeCliFallbackPrelude", () => {
       content: `turn ${i + 1} ${"x".repeat(80)}`,
     }));
     const out = formatClaudeCliFallbackPrelude({ recentTurns: turns }, { charBudget: 350 });
-    // Newest turn (turn 10) must be present; oldest (turn 1) must not be.
+    // Newest turn must be present; oldest turns are the first budget casualty.
     expect(out).toContain("turn 10");
     expect(out).not.toContain("turn 1 ");
   });
@@ -248,6 +254,8 @@ describe("buildClaudeCliFallbackContextPrelude", () => {
     const sessionId = "e2e-session";
     const projectsDir = path.join(tmpHome, ".claude", "projects", "demo");
     try {
+      // Use Claude's JSONL shape directly so parser and formatter behavior stay
+      // aligned with real CLI transcripts rather than synthetic message arrays.
       await fs.mkdir(projectsDir, { recursive: true });
       const lines = [
         {
