docs: document embedded attempt spawn tests

steipete · steipete · commit 9dcf42472b8a · 2026-06-04T14:46:45.000-04:00
diff --git a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-injection.test.ts b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-injection.test.ts
@@ -1,3 +1,4 @@
+// Coverage for bootstrap context injection and heartbeat filtering in attempts.
 import type { AgentMessage } from "openclaw/plugin-sdk/agent-core";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { filterHeartbeatTranscriptArtifacts } from "../../../auto-reply/heartbeat-filter.js";
@@ -19,6 +20,8 @@ async function resolveBootstrapContext(params: {
   completed?: boolean;
   resolver?: () => Promise<{ bootstrapFiles: unknown[]; contextFiles: unknown[] }>;
 }) {
+  // Helper exposes both resolved context and dependency calls so tests can
+  // assert when bootstrap probing is skipped.
   const hasCompletedBootstrapTurn = vi.fn(async () => params.completed ?? false);
   const resolveBootstrapContextForRun =
     params.resolver ??
@@ -94,6 +97,8 @@ describe("embedded attempt context injection", () => {
   });
 
   it("does not let a stale completed marker suppress pending workspace bootstrap", async () => {
+    // Pending BOOTSTRAP.md content takes precedence over completed-turn markers
+    // from earlier sessions.
     const resolver = vi.fn(async () => ({
       bootstrapFiles: [{ name: "BOOTSTRAP.md" }],
       contextFiles: [{ path: "BOOTSTRAP.md" }],
@@ -195,6 +200,8 @@ describe("embedded attempt context injection", () => {
   });
 
   it("filters no-op heartbeat pairs before history limiting and context-engine assembly", async () => {
+    // Heartbeat artifacts should not consume the limited turn budget passed into
+    // context-engine assembly.
     const assemble = vi.fn(async ({ messages }: { messages: AgentMessage[] }) => ({
       messages,
       estimatedTokens: 1,
diff --git a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.resource-loader.test.ts b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.resource-loader.test.ts
@@ -1,8 +1,11 @@
+// Coverage for explicit resource-loader wiring during attempt session creation.
 import { describe, expect, it, vi } from "vitest";
 import { createEmbeddedAgentSessionWithResourceLoader } from "./attempt-session.js";
 
 describe("runEmbeddedAttempt resource loader wiring", () => {
   it("passes an explicit resourceLoader to createAgentSession even without extension factories", async () => {
+    // The resource loader is an explicit runtime dependency; it must be passed
+    // even when no inline extension factories are present.
     const resourceLoader = { reload: vi.fn() };
     const createAgentSession = vi.fn(async () => ({ session: { id: "session" } }));
 
diff --git a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.sessions-spawn.test.ts b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.sessions-spawn.test.ts
@@ -1,9 +1,12 @@
+// Coverage for sessions_spawn workspace inheritance from sandbox context.
 import { describe, expect, it } from "vitest";
 import { createAgentToolsSandboxContext } from "../../test-helpers/agent-tools-sandbox-context.js";
 import { resolveAttemptSpawnWorkspaceDir } from "./attempt.thread-helpers.js";
 
 describe("runEmbeddedAttempt sessions_spawn workspace inheritance", () => {
   it("passes the real workspace to sessions_spawn when workspaceAccess is ro", () => {
+    // Read-only sandbox copies should not become the child session workspace;
+    // spawned sessions need the canonical real workspace.
     const realWorkspace = "/tmp/openclaw-real-workspace";
     const sandboxWorkspace = "/tmp/openclaw-sandbox-workspace";
     const sandbox = createAgentToolsSandboxContext({
diff --git a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.test-support.ts b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.test-support.ts
@@ -1,3 +1,4 @@
+// Shared harness and mocks for embedded attempt spawn-workspace tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -45,6 +46,8 @@ type BootstrapContext = {
 };
 
 function normalizeMockProviderId(providerId?: string): string {
+  // Provider ids in mocked model routing follow the same lowercase normalization
+  // as production helpers.
   return normalizeLowercaseStringOrEmpty(providerId);
 }
 
@@ -96,6 +99,8 @@ type AttemptSpawnWorkspaceHoisted = {
 };
 
 export function createSubscriptionMock(): SubscriptionMock {
+  // Minimal subscription surface for runEmbeddedAttempt tests; individual tests
+  // override only the lifecycle method they need.
   return {
     assistantTexts: [] as string[],
     toolMetas: [] as Array<{ toolName: string; meta?: string; asyncStarted?: boolean }>,
@@ -131,6 +136,8 @@ export function createSubscriptionMock(): SubscriptionMock {
 }
 
 const hoisted = vi.hoisted((): AttemptSpawnWorkspaceHoisted => {
+  // Hoisted mocks must exist before the runner module graph is imported, because
+  // runEmbeddedAttempt captures these dependencies at module load.
   const spawnSubagentDirectMock = vi.fn();
   const createAgentSessionMock = vi.fn();
   const sessionManagerOpenMock = vi.fn();
diff --git a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.timeout.test.ts b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.timeout.test.ts
@@ -1,6 +1,8 @@
+// Coverage for global Undici timeout wiring during embedded attempts.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
+  // Hoisted because attempt-http-runtime imports Undici wiring at module load.
   DEFAULT_UNDICI_STREAM_TIMEOUT_MS: 30 * 60 * 1000,
   ensureGlobalUndiciDispatcherStreamTimeouts: vi.fn(),
   ensureGlobalUndiciEnvProxyDispatcher: vi.fn(),
@@ -21,6 +23,8 @@ describe("runEmbeddedAttempt undici timeout wiring", () => {
   });
 
   it("does not lower global undici stream tuning below the shared default", () => {
+    // Attempt timeouts can be shorter than the shared stream timeout, but global
+    // dispatcher tuning must not be reduced for other in-flight streams.
     configureEmbeddedAttemptHttpRuntime({ timeoutMs: 123_456 });
 
     expect(mocks.ensureGlobalUndiciEnvProxyDispatcher).toHaveBeenCalledOnce();
diff --git a/src/agents/embedded-agent-runner/run/attempt.stop-reason-recovery.test.ts b/src/agents/embedded-agent-runner/run/attempt.stop-reason-recovery.test.ts
@@ -1,3 +1,4 @@
+// Coverage for converting sensitive/unhandled stop reasons into assistant errors.
 import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
 import {
   createAssistantMessageEventStream,
@@ -15,6 +16,8 @@ const anthropicModel = {
 
 describe("wrapStreamFnHandleSensitiveStopReason", () => {
   it("rewrites unhandled stop-reason errors into structured assistant errors", async () => {
+    // Some providers surface unhandled stop reasons as stream errors; convert
+    // them into a normal assistant error so fallback/retry paths can inspect it.
     const baseStreamFn: StreamFn = () => {
       const stream = createAssistantMessageEventStream();
       queueMicrotask(() => {
diff --git a/src/agents/embedded-agent-runner/run/attempt.subscription-cleanup.test.ts b/src/agents/embedded-agent-runner/run/attempt.subscription-cleanup.test.ts
@@ -1,3 +1,4 @@
+// Coverage for ordered cleanup of embedded attempt subscriptions and resources.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { log } from "../logger.js";
 import {
@@ -6,6 +7,7 @@ import {
 } from "./attempt.subscription-cleanup.js";
 
 function createDeferred<T>() {
+  // Manual deferreds let cleanup tests prove ordering around abort settlement.
   let resolve!: (value: T | PromiseLike<T>) => void;
   let reject!: (reason?: unknown) => void;
   const promise = new Promise<T>((resolvePromise, rejectPromise) => {
@@ -22,6 +24,8 @@ describe("cleanupEmbeddedAttemptResources", () => {
   });
 
   it("waits for aborted prompt settlement before flushing and releasing the lock", async () => {
+    // After an abort, pending prompt work gets a short chance to settle before
+    // session flush/release/dispose run.
     const order: string[] = [];
     const settle = createDeferred<void>();
 
@@ -97,6 +101,8 @@ describe("cleanupEmbeddedAttemptResources", () => {
   });
 
   it("releases the lock before runtime teardown can hang", async () => {
+    // Bundle runtime disposal can hang; release transcript locks first so other
+    // turns are not blocked by diagnostic cleanup.
     const order: string[] = [];
     let markRuntimeDisposeStarted!: () => void;
     const runtimeDisposeStarted = new Promise<void>((resolve) => {
diff --git a/src/agents/embedded-agent-runner/run/attempt.test.ts b/src/agents/embedded-agent-runner/run/attempt.test.ts
@@ -1,3 +1,4 @@
+// Broad helper coverage for runEmbeddedAttempt prompt, stream, and tool seams.
 import { describe, expect, it, vi } from "vitest";
 import { streamSimple } from "../../../llm/stream.js";
 
@@ -47,6 +48,8 @@ function createFakeStream(params: {
   events: unknown[];
   resultMessage: unknown;
 }): FakeWrappedStream {
+  // Minimal stream compatible with wrappers that decorate result and iteration
+  // without needing a real provider stream.
   return {
     async result() {
       return params.resultMessage;
@@ -67,6 +70,7 @@ async function invokeWrappedTestStream(
   ) => (...args: never[]) => FakeWrappedStream | Promise<FakeWrappedStream>,
   baseFn: (...args: never[]) => unknown,
 ): Promise<FakeWrappedStream> {
+  // Helper keeps wrapper tests focused on mutated stream behavior.
   const wrappedFn = wrap(baseFn);
   return await Promise.resolve(wrappedFn({} as never, {} as never, {} as never));
 }
@@ -101,6 +105,7 @@ function expectSingleToolCallContent(content: unknown[], name: string) {
 }
 
 function firstBaseContext(baseFn: ReturnType<typeof vi.fn>): { messages: unknown[] } {
+  // Wrapper tests assert the context passed to the underlying stream function.
   const call = baseFn.mock.calls.at(0);
   if (!call) {
     throw new Error("expected base stream call");
@@ -178,6 +183,8 @@ describe("resolvePromptBuildHookResult", () => {
   });
 
   it("merges prompt-build and before_agent_start context fields in deterministic order", async () => {
+    // Prompt-build hook context comes before before_agent_start context so plugin
+    // injections are replayed in stable order.
     const hookRunner = {
       hasHooks: vi.fn(() => true),
       runBeforePromptBuild: vi.fn(async () => ({
