docs: document models config serialization tests

steipete · steipete · commit 8605076a6f00 · 2026-06-04T15:30:20.000-04:00
diff --git a/src/agents/models-config.providers.stepfun.test.ts b/src/agents/models-config.providers.stepfun.test.ts
@@ -1,3 +1,4 @@
+// Verifies StepFun standard and Step Plan catalog pairing across regions.
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -37,6 +38,7 @@ function buildStepFunCatalog(params: {
   profileId?: string;
   env?: NodeJS.ProcessEnv;
 }): ModelProviderConfig | null {
+  // Region can be explicit, profile-tagged, or env-inferred; catalog ids stay paired.
   if (!params.apiKey) {
     return null;
   }
@@ -75,6 +77,7 @@ function inferRegionFromBaseUrl(baseUrl: string | undefined): StepFunRegion | un
 }
 
 function inferRegionFromProfileId(profileId: string | undefined): StepFunRegion | undefined {
+  // Auth profile suffixes are the lightweight region signal for paired providers.
   if (!profileId) {
     return undefined;
   }
@@ -183,6 +186,7 @@ describe("StepFun provider catalog", () => {
       }),
     };
     const pairedStandard = buildStepFunCatalog({
+      // Paired surfaces should converge on the same regional host family.
       surface: "standard",
       apiKey: "test-stepfun-key",
       explicitBaseUrl: resolveDefaultBaseUrl(
diff --git a/src/agents/models-config.providers.vercel-ai-gateway.test.ts b/src/agents/models-config.providers.vercel-ai-gateway.test.ts
@@ -1,9 +1,11 @@
+// Verifies Vercel AI Gateway auth marker resolution from env and profiles.
 import { beforeAll, describe, expect, it, vi } from "vitest";
 
 let NON_ENV_SECRETREF_MARKER: typeof import("./model-auth-markers.js").NON_ENV_SECRETREF_MARKER;
 let createProviderAuthResolver: typeof import("./models-config.providers.secrets.js").createProviderAuthResolver;
 
 async function loadModules() {
+  // This file needs the real auth resolver after other provider tests install mocks.
   vi.doUnmock("../plugins/manifest-registry.js");
   vi.doUnmock("../plugins/provider-runtime.js");
   vi.doUnmock("../secrets/provider-env-vars.js");
@@ -47,6 +49,7 @@ describe("vercel-ai-gateway provider resolution", () => {
     });
 
     const auth = resolveAuth("vercel-ai-gateway");
+    // Persist the env marker, not the resolved plaintext profile key.
     expect(auth.apiKey).toBe("AI_GATEWAY_API_KEY");
     expect(auth.mode).toBe("api_key");
     expect(auth.source).toBe("profile");
diff --git a/src/agents/models-config.runtime-source-snapshot.test.ts b/src/agents/models-config.runtime-source-snapshot.test.ts
@@ -1,3 +1,4 @@
+// Verifies generated models.json preserves source secret markers from runtime snapshots.
 import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createFixtureSuite } from "../test-utils/fixture-suite.js";
@@ -90,6 +91,7 @@ function createOpenAiApiKeySourceConfig(): OpenClawConfig {
 }
 
 function createOpenAiApiKeyRuntimeConfig(): OpenClawConfig {
+  // Runtime config simulates already-resolved secrets that must not be persisted.
   return {
     models: {
       providers: {
@@ -224,6 +226,7 @@ async function planGeneratedProviders(params: {
   config: OpenClawConfig;
   sourceConfigForSecrets: OpenClawConfig;
 }) {
+  // Planner assertions avoid filesystem noise for marker-projection cases.
   const plan = await planOpenClawModelsJsonWithDeps(
     {
       cfg: params.config,
@@ -250,6 +253,7 @@ async function planGeneratedProviders(params: {
 function expectOpenAiHeaderMarkers(
   providers: Record<string, { headers?: Record<string, string> }>,
 ) {
+  // Env header refs keep their id; non-env refs collapse to the shared sentinel.
   expect(providers.openai?.headers?.Authorization).toBe(
     "secretref-env:OPENAI_HEADER_TOKEN", // pragma: allowlist secret
   );
diff --git a/src/agents/models-config.skips-writing-models-json-no-env-token.test.ts b/src/agents/models-config.skips-writing-models-json-no-env-token.test.ts
@@ -1,3 +1,4 @@
+// Verifies models.json generation skips env-gated providers until auth exists.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
@@ -24,6 +25,7 @@ vi.mock("./auth-profiles/external-cli-sync.js", () => ({
 
 vi.mock("./models-config.providers.js", async () => {
   function createImplicitProvider(baseUrl: string): ModelsProviderConfig {
+    // Shared implicit-provider fixture keeps generated-provider expectations compact.
     return {
       baseUrl,
       api: "openai-completions",
@@ -106,6 +108,7 @@ type ParsedProviderConfig = {
 async function readGeneratedProviders(
   agentDir: string,
 ): Promise<Record<string, ParsedProviderConfig>> {
+  // Generated plugin catalogs are separate files but part of the effective provider set.
   const raw = await fs.readFile(path.join(agentDir, "models.json"), "utf8");
   const parsed = JSON.parse(raw) as { providers?: Record<string, ParsedProviderConfig> };
   const providers = { ...parsed.providers };
@@ -142,6 +145,7 @@ async function runEnvProviderCase(params: {
   providerKey: "minimax" | "synthetic";
   expectedApiKeyRef: string;
 }) {
+  // Mutate one env var at a time so auth-gated provider generation stays isolated.
   const previousValue = process.env[params.envVar];
   process.env[params.envVar] = params.envValue;
   try {
diff --git a/src/agents/models-config.uses-first-github-copilot-profile-env-tokens.test.ts b/src/agents/models-config.uses-first-github-copilot-profile-env-tokens.test.ts
@@ -1,3 +1,4 @@
+// Verifies GitHub Copilot profile token fallback and implicit provider planning.
 import { describe, expect, it, vi } from "vitest";
 import {
   planOpenClawModelsJson,
@@ -251,6 +252,7 @@ describe("models-config", () => {
 function createCopilotImplicitResolver(
   provider: ProviderConfig,
 ): ResolveImplicitProvidersForModelsJson {
+  // Models planner receives implicit Copilot providers from the auth exchange layer.
   return async () => ({ "github-copilot": provider });
 }
 
@@ -272,6 +274,7 @@ async function planCopilotWithImplicitProvider(params: { provider: ProviderConfi
 function expectCopilotProviderFromPlan(
   plan: Awaited<ReturnType<typeof planCopilotWithImplicitProvider>>,
 ) {
+  // Keep assertions on the emitted provider payload, not planner implementation details.
   expect(plan.action).toBe("write");
   const parsed =
     plan.action === "write"
diff --git a/src/agents/models-config.write-serialization.test.ts b/src/agents/models-config.write-serialization.test.ts
@@ -1,3 +1,4 @@
+// Verifies models.json writes, plugin catalog writes, and ready-cache serialization.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
@@ -29,6 +30,7 @@ let clearCurrentPluginMetadataSnapshot: typeof import("../plugins/current-plugin
 let setCurrentPluginMetadataSnapshot: typeof import("../plugins/current-plugin-metadata-snapshot.js").setCurrentPluginMetadataSnapshot;
 
 function createPluginMetadataSnapshot(workspaceDir: string): PluginMetadataSnapshot {
+  // Minimal process snapshot used to prove when metadata may be reused.
   const policyHash = resolveInstalledPluginIndexPolicyHash({});
   return {
     policyHash,
@@ -72,6 +74,7 @@ function createPluginMetadataSnapshot(workspaceDir: string): PluginMetadataSnaps
 }
 
 async function expectMissingPath(operation: Promise<unknown>) {
+  // Filesystem deletion assertions should fail on the errno, not path text.
   let error: NodeJS.ErrnoException | undefined;
   try {
     await operation;
@@ -87,6 +90,7 @@ function planParamsAt(callIndex: number): {
   providerDiscoveryTimeoutMs?: number;
   workspaceDir?: string;
 } {
+  // Planner call shape is the contract between ensureOpenClawModelsJson and planning.
   const call = planOpenClawModelsJsonMock.mock.calls[callIndex];
   if (!call) {
     throw new Error(`expected models planner call #${callIndex + 1}`);
@@ -397,6 +401,7 @@ describe("models-config write serialization", () => {
       let modelsWriteCount = 0;
       writePrivateStoreTextWriteMock.mockImplementation(
         async (params: { filePath: string; rootDir: string; content: string | Uint8Array }) => {
+          // Hold both writes at the store boundary to prove the outer serializer works.
           const isModelsWrite = path.basename(params.filePath) === "models.json";
           if (isModelsWrite) {
             modelsWriteCount += 1;
