docs: document subagent tests

steipete · steipete · commit cc296f3a4600 · 2026-06-04T16:40:43.000-04:00
diff --git a/src/agents/minimax-docs.test.ts b/src/agents/minimax-docs.test.ts
@@ -1,3 +1,5 @@
+// MiniMax docs sync tests keep provider docs and live-test guidance aligned
+// with the shared MiniMax model constants.
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/agents/subagent-announce.live.test.ts b/src/agents/subagent-announce.live.test.ts
@@ -1,3 +1,5 @@
+// Live subagent announce E2E tests exercise real gateway, session, and provider
+// flows for subagent completion delivery.
 import { randomBytes, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -67,6 +69,8 @@ function resolveLiveSubagentModelConfig(): LiveSubagentModelConfig {
 }
 
 function requireLiveSubagentAuth(config: LiveSubagentModelConfig): void {
+  // Live E2E runs need the provider credential that matches the selected model
+  // family; fail early before gateway startup.
   expect(process.env[config.requiredEnv]?.trim(), config.requiredEnv).toBeTruthy();
 }
 
diff --git a/src/agents/subagent-registry.archive.e2e.test.ts b/src/agents/subagent-registry.archive.e2e.test.ts
@@ -1,3 +1,5 @@
+// Subagent registry archive tests cover keep/delete cleanup modes, retryable
+// session deletion, and context-engine lifecycle callbacks.
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -10,6 +12,8 @@ let currentConfig = {
 };
 const loadConfigMock = vi.fn(() => currentConfig);
 const flushSweepMicrotasks = async () => {
+  // Archive sweeps schedule follow-up work through microtasks; drain them before
+  // asserting registry and context-engine side effects.
   await Promise.resolve();
   await Promise.resolve();
 };
diff --git a/src/agents/subagent-registry.test.ts b/src/agents/subagent-registry.test.ts
@@ -1,3 +1,5 @@
+// Subagent registry tests cover run state, completion capture, archive cleanup,
+// persistence, lifecycle hooks, and orphan recovery scheduling.
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -59,6 +61,8 @@ function findRecordCallArg(
 }
 
 async function expectPathMissing(targetPath: string): Promise<void> {
+  // Cleanup assertions need ENOENT proof; fs.access success means the artifact
+  // directory survived when lifecycle cleanup should have removed it.
   try {
     await fs.access(targetPath);
   } catch (error) {
diff --git a/src/agents/subagent-run-timeout.test.ts b/src/agents/subagent-run-timeout.test.ts
@@ -1,3 +1,5 @@
+// Subagent run timeout tests keep semantic deadlines separate from the maximum
+// delay that Node timers can safely schedule.
 import { describe, expect, it } from "vitest";
 import { MAX_TIMER_TIMEOUT_MS } from "../shared/number-coercion.js";
 import {
@@ -20,6 +22,8 @@ describe("subagent run timeout helpers", () => {
   });
 
   it("caps actual timer delays without shortening semantic durations", () => {
+    // Long-lived subagent runs retain their requested deadline even though the
+    // watchdog timer must be scheduled in bounded chunks.
     const thirtyDaysSeconds = 30 * 24 * 60 * 60;
 
     expect(resolveSubagentRunTimerDelayMs(thirtyDaysSeconds)).toBe(MAX_TIMER_TIMEOUT_MS);
diff --git a/src/agents/subagent-spawn.model-session.test.ts b/src/agents/subagent-spawn.model-session.test.ts
@@ -1,3 +1,5 @@
+// Subagent spawn model-session tests verify runtime model metadata is persisted
+// before a child agent run starts.
 import os from "node:os";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import {
@@ -46,6 +48,8 @@ describe("spawnSubagentDirect runtime model persistence", () => {
   });
 
   it("persists runtime model fields on the child session before starting the run", async () => {
+    // The child run reads model/provider from session state, so persistence must
+    // happen before the gateway accepts the agent request.
     const operations: string[] = [];
     callGatewayMock.mockImplementation(async (opts: { method?: string }) => {
       operations.push(`gateway:${opts.method ?? "unknown"}`);
diff --git a/src/agents/subagent-spawn.test.ts b/src/agents/subagent-spawn.test.ts
@@ -1,3 +1,5 @@
+// Subagent spawn tests cover target policy, session patching, runtime model
+// persistence, registry registration, and lifecycle event emission.
 import os from "node:os";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import {
@@ -47,6 +49,8 @@ function requireRecord(value: unknown): Record<string, unknown> {
 }
 
 function gatewayRequestRecords(): Record<string, unknown>[] {
+  // Gateway calls are the seam proof for spawn orchestration; assertions inspect
+  // structured requests instead of matching rendered text.
   return hoisted.callGatewayMock.mock.calls.map((call) => requireRecord(call[0]));
 }
 
diff --git a/src/agents/subagent-target-policy.test.ts b/src/agents/subagent-target-policy.test.ts
@@ -1,3 +1,5 @@
+// Subagent target policy tests cover requester defaults, explicit allowlists,
+// wildcard target sets, and stale configured-agent filtering.
 import { describe, expect, it } from "vitest";
 import {
   resolveSubagentAllowedTargetIds,
diff --git a/src/agents/tool-call-id.test.ts b/src/agents/tool-call-id.test.ts
@@ -1,3 +1,5 @@
+// Tool-call id tests cover provider-safe rewrites, collision handling, replay
+// preservation for signed thinking turns, and strict short-id mode.
 import type { AgentMessage } from "openclaw/plugin-sdk/agent-core";
 import { describe, expect, it } from "vitest";
 import { castAgentMessages } from "./test-helpers/agent-message-fixtures.js";
@@ -148,6 +150,8 @@ function expectReplaySafeSignedTurnOwnership(params: {
   preservedTurn: "first" | "second";
   firstToolCallIndex: number;
 }) {
+  // Signed thinking blocks bind the following tool call; replay repair may keep
+  // only the safe turn's id and must rewrite the colliding sibling turn.
   const out = sanitizeToolCallIdsForCloudCodeAssist(params.input, "strict", {
     preserveReplaySafeThinkingToolCallIds: true,
     allowedToolNames: ["read"],
diff --git a/src/agents/tool-replay-repair.live.test.ts b/src/agents/tool-replay-repair.live.test.ts
@@ -1,3 +1,5 @@
+// Live tool replay repair tests validate repaired historical transcripts across
+// selected real model providers.
 import type { AgentMessage } from "openclaw/plugin-sdk/agent-core";
 import { SessionManager } from "openclaw/plugin-sdk/agent-sessions";
 import type { Context, Model } from "openclaw/plugin-sdk/llm";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// MiniMax docs sync tests keep provider docs and live-test guidance aligned`
	`2`	`+// with the shared MiniMax model constants.`
`1`	`3`	`import fs from "node:fs";`
`2`	`4`	`import path from "node:path";`
`3`	`5`	`import { describe, expect, it } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Live subagent announce E2E tests exercise real gateway, session, and provider`
	`2`	`+// flows for subagent completion delivery.`
`1`	`3`	`import { randomBytes, randomUUID } from "node:crypto";`
`2`	`4`	`import fs from "node:fs/promises";`
`3`	`5`	`import path from "node:path";`
`@@ -67,6 +69,8 @@ function resolveLiveSubagentModelConfig(): LiveSubagentModelConfig {`
`67`	`69`	`}`
`68`	`70`
`69`	`71`	`function requireLiveSubagentAuth(config: LiveSubagentModelConfig): void {`
	`72`	`+ // Live E2E runs need the provider credential that matches the selected model`
	`73`	`+ // family; fail early before gateway startup.`
`70`	`74`	`expect(process.env[config.requiredEnv]?.trim(), config.requiredEnv).toBeTruthy();`
`71`	`75`	`}`
`72`	`76`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Subagent spawn tests cover target policy, session patching, runtime model`
	`2`	`+// persistence, registry registration, and lifecycle event emission.`
`1`	`3`	`import os from "node:os";`
`2`	`4`	`import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
`3`	`5`	`import {`
`@@ -47,6 +49,8 @@ function requireRecord(value: unknown): Record<string, unknown> {`
`47`	`49`	`}`
`48`	`50`
`49`	`51`	`function gatewayRequestRecords(): Record<string, unknown>[] {`
	`52`	`+ // Gateway calls are the seam proof for spawn orchestration; assertions inspect`
	`53`	`+ // structured requests instead of matching rendered text.`
`50`	`54`	`return hoisted.callGatewayMock.mock.calls.map((call) => requireRecord(call[0]));`
`51`	`55`	`}`
`52`	`56`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Subagent target policy tests cover requester defaults, explicit allowlists,`
	`2`	`+// wildcard target sets, and stale configured-agent filtering.`
`1`	`3`	`import { describe, expect, it } from "vitest";`
`2`	`4`	`import {`
`3`	`5`	`resolveSubagentAllowedTargetIds,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Live tool replay repair tests validate repaired historical transcripts across`
	`2`	`+// selected real model providers.`
`1`	`3`	`import type { AgentMessage } from "openclaw/plugin-sdk/agent-core";`
`2`	`4`	`import { SessionManager } from "openclaw/plugin-sdk/agent-sessions";`
`3`	`5`	`import type { Context, Model } from "openclaw/plugin-sdk/llm";`