@desplega.ai/agent-swarm 1.173.0 → 2.0.0

package/src/tests/openai-compatible-providers.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import {
+  baseUrlEnvVar,
+  OPENAI_COMPATIBLE_PROVIDERS,
+  openAICompatibleProviderIds,
+  providerBaseUrl,
+  providerForKeyVar,
+  providerForModel,
+  providerKeyFromEnv,
+  withRegistryCatalogSections,
+} from "@desplega/model-catalog";
+import { loadModelsDevCache } from "../be/modelsdev-cache";
+import snapshot from "../be/modelsdev-cache.json";
+import { normalizeProviderKeyAliases } from "../utils/credentials";
+
+type SnapshotModel = {
+  name: string;
+  reasoning?: boolean;
+  tool_call?: boolean;
+  modalities?: { input?: string[] };
+  limit?: { context?: number; output?: number };
+};
+type SnapshotProvider = {
+  api?: string;
+  env?: string[];
+  npm?: string;
+  models: Record<string, SnapshotModel>;
+};
+
+describe("openai-compatible provider table", () => {
+  test("providerForModel routes by exact prefix only", () => {
+    expect(providerForModel("nan/glm5.3-flash")?.id).toBe("nan");
+    expect(providerForModel("helmcode/gemma4")?.id).toBe("helmcode");
+    expect(providerForModel("openrouter/nan/glm5.3")).toBeUndefined();
+    expect(providerForModel("glm5.3")).toBeUndefined();
+    expect(providerForModel("nanx/glm5.3")).toBeUndefined();
+    expect(providerForModel("toString/x")).toBeUndefined();
+    expect(providerForModel(undefined)).toBeUndefined();
+  });
+
+  test("providerForKeyVar finds canonical and alias key vars", () => {
+    expect(providerForKeyVar("NAN_API_KEY")?.id).toBe("nan");
+    expect(providerForKeyVar("HELMCODE_API_NAN")?.id).toBe("nan");
+    expect(providerForKeyVar("HELMCODE_API_KEY")?.id).toBe("helmcode");
+    expect(providerForKeyVar("OPENROUTER_API_KEY")).toBeUndefined();
+  });
+
+  test("<ID>_BASE_URL overrides the default base URL", () => {
+    const nan = OPENAI_COMPATIBLE_PROVIDERS.nan;
+    const helmcode = OPENAI_COMPATIBLE_PROVIDERS.helmcode;
+    expect(baseUrlEnvVar(nan)).toBe("NAN_BASE_URL");
+    expect(baseUrlEnvVar(helmcode)).toBe("HELMCODE_BASE_URL");
+    expect(providerBaseUrl(nan, {})).toBe("https://api.nan.builders/v1");
+    expect(providerBaseUrl(nan, { NAN_BASE_URL: "  " })).toBe("https://api.nan.builders/v1");
+    expect(providerBaseUrl(helmcode, { HELMCODE_BASE_URL: "http://127.0.0.1:9/v1/" })).toBe(
+      "http://127.0.0.1:9/v1",
+    );
+  });
+
+  test("providerKeyFromEnv prefers the canonical var, then the alias", () => {
+    const nan = OPENAI_COMPATIBLE_PROVIDERS.nan;
+    expect(providerKeyFromEnv(nan, { HELMCODE_API_NAN: "alias" })).toBe("alias");
+    expect(providerKeyFromEnv(nan, { NAN_API_KEY: "canon", HELMCODE_API_NAN: "alias" })).toBe(
+      "canon",
+    );
+    expect(providerKeyFromEnv(nan, { NAN_API_KEY: "  " })).toBeUndefined();
+    expect(providerKeyFromEnv(OPENAI_COMPATIBLE_PROVIDERS.helmcode, { NAN_API_KEY: "k" })).toBe(
+      undefined,
+    );
+  });
+
+  test("normalizeProviderKeyAliases copies an alias only into an empty canonical var", () => {
+    const aliasOnly: Record<string, string | undefined> = { HELMCODE_API_NAN: "alias" };
+    normalizeProviderKeyAliases(aliasOnly);
+    expect(aliasOnly.NAN_API_KEY).toBe("alias");
+    const both: Record<string, string | undefined> = {
+      NAN_API_KEY: "canon",
+      HELMCODE_API_NAN: "alias",
+    };
+    normalizeProviderKeyAliases(both);
+    expect(both.NAN_API_KEY).toBe("canon");
+  });
+
+  test("registry-sourced sections are synthesized, never hand-written in the snapshot", () => {
+    const raw = snapshot as unknown as Record<string, unknown>;
+    for (const id of openAICompatibleProviderIds()) {
+      const entry = OPENAI_COMPATIBLE_PROVIDERS[id];
+      if (entry.catalog === "registry") expect(raw[id]).toBeUndefined();
+      else expect(raw[id]).toBeDefined();
+    }
+    // The server loader carries the synthesized sections.
+    expect(loadModelsDevCache()?.helmcode?.models?.["glm5.3"]?.limit?.context).toBe(1048576);
+  });
+
+  // The registry duplicates the models.dev sections of `catalog: "models.dev"`
+  // entries (the pi/opencode blocks need limits the worker cannot read from
+  // the catalog store); keep the two from drifting. Registry-sourced sections
+  // are built from the registry, so they agree by construction.
+  const merged = withRegistryCatalogSections(
+    snapshot as unknown as Record<string, SnapshotProvider | undefined>,
+  );
+  for (const id of openAICompatibleProviderIds()) {
+    test(`${id} matches its catalog section`, () => {
+      const entry = OPENAI_COMPATIBLE_PROVIDERS[id];
+      const section = merged[id];
+      expect(section).toBeDefined();
+      if (!section) return;
+      // OpenCode's built-in AI Gateway SDK has no OpenAI-compatible `api` URL.
+      if (entry.npm === "@ai-sdk/gateway") expect(section.api).toBeUndefined();
+      else expect(section.api).toBe(entry.baseUrl);
+      expect(section.env).toEqual([entry.envVar]);
+      expect(section.npm).toBe(entry.npm);
+      for (const model of entry.models) {
+        const snap = section.models[model.id];
+        expect(snap, `${id}/${model.id} missing from snapshot`).toBeDefined();
+        if (!snap) continue;
+        expect({
+          name: model.name,
+          contextWindow: model.contextWindow,
+          maxOutputTokens: model.maxOutputTokens,
+          reasoning: model.reasoning,
+          input: [...model.input],
+        }).toEqual({
+          name: snap.name,
+          contextWindow: snap.limit?.context,
+          maxOutputTokens: snap.limit?.output,
+          reasoning: snap.reasoning,
+          input: (snap.modalities?.input ?? []).filter((m) => m === "text" || m === "image"),
+        });
+        expect(snap.tool_call).toBe(true);
+      }
+    });
+  }
+});

package/src/tests/openai-compatible-registry-extension.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Proof that adding an OpenAI-compatible provider takes one registry entry:
+ * a fake `testgw` entry must reach every derived surface
+ * (`fixtures/openai-compatible-registry-extension.child.ts`).
+ *
+ * The proof mocks the registry module, and its consumers cache derivations of
+ * the table at import (integration cards, picker constants) that no mock
+ * restore can undo. It runs in its own `bun test` child so this process, and
+ * every file sharing it in a single-process run, keeps the real table.
+ */
+import { expect, test } from "bun:test";
+import { join } from "node:path";
+import { modelGroupsForHarness } from "../../apps/ui/src/lib/agent-runtime-models";
+import { INTEGRATIONS } from "../../apps/ui/src/lib/integrations-catalog";
+import { CHILD_PROCESS_TEST_BUDGET_MS, expectChildOk, runChild } from "./test-proc";
+
+const REPO_ROOT = join(import.meta.dir, "../..");
+const CHILD = "./src/tests/fixtures/openai-compatible-registry-extension.child.ts";
+
+test(
+  "a testgw registry entry reaches every derived surface (child process)",
+  async () => {
+    const result = expectChildOk(
+      await runChild([process.execPath, "test", CHILD], {
+        cwd: REPO_ROOT,
+        env: { ...process.env },
+      }),
+      "registry extension proof",
+    );
+    // bun test reports to stderr; 0 fail and every case ran.
+    const report = `${result.stdout}\n${result.stderr}`;
+    expect(report).toMatch(/\b6 pass\b/);
+    expect(report).toMatch(/\b0 fail\b/);
+  },
+  CHILD_PROCESS_TEST_BUDGET_MS,
+);
+
+test("this process still sees the real registry only", () => {
+  expect(INTEGRATIONS.some((def) => def.id === "testgw")).toBe(false);
+  const providers = modelGroupsForHarness("pi", [], {}).map((g) => g.provider);
+  expect(providers).not.toContain("TestGW");
+});

package/src/tests/opencode-adapter.test.ts

@@ -7,18 +7,20 @@
  * config wiring, steering, abort, and stream-death handling.
  */
 
-import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, spyOn, test } from "bun:test";
 import type { OpenCodeEvent } from "@opencode/sdk";
 import { normalizeSessionLogs, type SessionLogRecord } from "../../apps/ui/src/logs-parser";
 import {
   _setOpencodeSdkLoaderForTests,
   _setOpencodeSessionHooksForTests,
   applyOpenRouterBaseUrlOverride,
+  applyProviderKeySplice,
   OpencodeAdapter,
   type OpencodeSession,
   resolveOpencodeSdkSpecifier,
 } from "../providers/opencode-adapter";
 import type { ProviderEvent, ProviderSessionConfig } from "../providers/types";
+import { clearVolatileSecretsForTesting } from "../utils/secret-scrubber";
 
 const SESSION_ID = "ses_test";
 
@@ -128,13 +130,14 @@ function makeFakeHost(events: OpenCodeEvent[], opts: FakeHostOptions = {}) {
   return host;
 }
 
-function installHost(host: FakeHost) {
+function installHost(host: FakeHost, onCreate?: (options: Record<string, unknown>) => void) {
   _setOpencodeSdkLoaderForTests(async () => ({
     version: "2.0.28",
     sdk: {
       OpenCode: {
         create: async (options: Record<string, unknown>) => {
           host.createOptions = options;
+          onCreate?.(options);
           // Set the plugins up the way OpenCode does, with a stub context.
           const plugins = options.plugins as Array<{ setup: (ctx: unknown) => Promise<void> }>;
           for (const plugin of plugins) {
@@ -143,6 +146,8 @@ function installHost(host: FakeHost) {
                 hook: async () => {},
                 list: async () => host.tools.map((id) => ({ id })),
               },
+              // Registered when the session config carries a per-task env.
+              shell: { hook: async () => {} },
               session: {
                 hook: async (
                   name: string,
@@ -841,3 +846,212 @@ describe("OpenRouter attribution config", () => {
     expect(config).toEqual({});
   });
 });
+
+describe("provider key splice (one picked key per task)", () => {
+  const PICKED = "sk-picked-member-0123456789";
+  const POOL = "sk-pool-member-aaaaaaaaaa,sk-pool-member-bbbbbbbbbb";
+  const SPLICE_VARS = [
+    "NAN_API_KEY",
+    "HELMCODE_API_NAN",
+    "HELMCODE_API_KEY",
+    "OPENROUTER_API_KEY",
+    "OPENROUTER_BASE_URL",
+  ];
+  const saved: Record<string, string | undefined> = {};
+  beforeAll(() => {
+    for (const key of SPLICE_VARS) saved[key] = process.env[key];
+  });
+  afterEach(() => {
+    for (const key of SPLICE_VARS) {
+      if (saved[key] === undefined) delete process.env[key];
+      else process.env[key] = saved[key];
+    }
+    clearVolatileSecretsForTesting();
+  });
+
+  test("nan: env [] and the per-task key, even with a pool in process.env", async () => {
+    process.env.NAN_API_KEY = POOL;
+    const { host } = await runSession(
+      [succeeded],
+      testConfig({ model: "nan/glm5.3-flash", env: { NAN_API_KEY: PICKED } }),
+    );
+    const nan = configOf(host).provider.nan;
+    expect(nan.env).toEqual([]);
+    expect(nan.options.apiKey).toBe(PICKED);
+  });
+
+  test("nan: the HELMCODE_API_NAN alias is read when NAN_API_KEY is empty", () => {
+    const config = {};
+    const picked = applyProviderKeySplice(config, "nan/qwen3.6", { HELMCODE_API_NAN: PICKED });
+    expect(picked).toEqual({ key: PICKED, name: "HELMCODE_API_NAN" });
+    expect(config).toEqual({ provider: { nan: { env: [], options: { apiKey: PICKED } } } });
+  });
+
+  test("a pool that reaches the splice unpicked yields its first member", () => {
+    const config = {};
+    applyProviderKeySplice(config, "nan/qwen3.6", {
+      NAN_API_KEY: ` ${PICKED} , sk-other-0000000000`,
+    });
+    expect(config).toEqual({ provider: { nan: { env: [], options: { apiKey: PICKED } } } });
+  });
+
+  test("helmcode: full custom block with limits, reasoning options merged in", async () => {
+    const { host } = await runSession(
+      [succeeded],
+      testConfig({
+        model: "helmcode/glm5.3",
+        reasoningEffort: "high",
+        env: { HELMCODE_API_KEY: PICKED },
+      }),
+    );
+    const helmcode = configOf(host).provider.helmcode;
+    expect(helmcode).toMatchObject({
+      npm: "@ai-sdk/openai-compatible",
+      name: "Helmcode",
+      env: [],
+      options: { baseURL: "https://api.helmcode.com/v1", apiKey: PICKED },
+    });
+    expect(helmcode.models["glm5.3"]).toEqual({
+      name: "GLM-5.3",
+      tool_call: true,
+      reasoning: true,
+      limit: { context: 1048576, output: 32768 },
+      options: { reasoningEffort: "high" },
+    });
+    expect(Object.keys(helmcode.models)).toEqual([
+      "deepseek-v4-flash",
+      "glm5.3",
+      "glm5.3-flash",
+      "qwen3.6",
+      "gemma4",
+    ]);
+  });
+
+  test("helmcode: a model missing from the table still gets an entry", () => {
+    const config: Record<string, any> = {};
+    applyProviderKeySplice(config, "helmcode/brand-new", { HELMCODE_API_KEY: PICKED });
+    expect(config.provider.helmcode.models["brand-new"]).toEqual({
+      name: "brand-new",
+      tool_call: true,
+    });
+  });
+
+  test("openrouter gateway: baseURL kept next to env [] and the picked key", async () => {
+    process.env.OPENROUTER_API_KEY = POOL;
+    const { host } = await runSession(
+      [succeeded],
+      testConfig({
+        model: "openrouter/deepseek/deepseek-v4-flash",
+        env: { OPENROUTER_API_KEY: PICKED, OPENROUTER_BASE_URL: "http://127.0.0.1:1234/v1" },
+      }),
+    );
+    expect(configOf(host).provider.openrouter).toEqual({
+      env: [],
+      options: { apiKey: PICKED, baseURL: "http://127.0.0.1:1234/v1" },
+    });
+  });
+
+  test("openrouter host: attribution headers kept next to env [] and the picked key", async () => {
+    const { host } = await runSession(
+      [succeeded],
+      testConfig({
+        model: "openrouter/deepseek/deepseek-v4-flash",
+        env: { OPENROUTER_API_KEY: PICKED },
+      }),
+    );
+    const openrouter = configOf(host).provider.openrouter;
+    expect(openrouter.env).toEqual([]);
+    expect(openrouter.options.apiKey).toBe(PICKED);
+    expect(openrouter.options.headers).toMatchObject({ "X-Title": "Agent Swarm" });
+  });
+
+  test("no splice without a key, or for providers outside the splice", () => {
+    for (const model of ["nan/qwen3.6", "helmcode/glm5.3", "openrouter/x/y"]) {
+      const config = {};
+      expect(applyProviderKeySplice(config, model, {})).toBeUndefined();
+      expect(config).toEqual({});
+    }
+    for (const model of ["anthropic/claude-sonnet-4-5", "openai/gpt-5", "glm5.3", "", undefined]) {
+      const config = {};
+      applyProviderKeySplice(config, model, {
+        ANTHROPIC_API_KEY: PICKED,
+        OPENAI_API_KEY: PICKED,
+        NAN_API_KEY: PICKED,
+      });
+      expect(config).toEqual({});
+    }
+  });
+});
+
+describe("spliced key never reaches logs, events, or errors", () => {
+  // Not in process.env: the key a dashboard save delivers to the per-task env only.
+  const SENTINEL = "sk-nan-sentinel-do-not-log-4f9c2e";
+  let captured: string[] = [];
+  let spies: Array<ReturnType<typeof spyOn>> = [];
+  beforeAll(() => {
+    delete process.env.NAN_API_KEY;
+  });
+  afterEach(() => {
+    for (const spy of spies) spy.mockRestore();
+    spies = [];
+    captured = [];
+    clearVolatileSecretsForTesting();
+  });
+  function captureConsole() {
+    for (const method of ["log", "info", "warn", "error", "debug"] as const) {
+      spies.push(
+        spyOn(console, method).mockImplementation((...args: unknown[]) => {
+          captured.push(args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" "));
+        }),
+      );
+    }
+  }
+
+  test("SDK log lines and a provider failure that echo the config are scrubbed", async () => {
+    captureConsole();
+    const host = makeFakeHost([
+      ev("session.execution.failed", {
+        sessionID: SESSION_ID,
+        error: { message: `401 Invalid API key ${SENTINEL}` },
+      }),
+    ]);
+    installHost(host, (options) => {
+      const content = (options.config as { content: string }).content;
+      const log = options.log as { emit: (entry: { message: string }) => void };
+      log.emit({ message: `config: ${content}` });
+    });
+    const session = (await new OpencodeAdapter().createSession(
+      testConfig({ model: "nan/glm5.3-flash", env: { NAN_API_KEY: SENTINEL } }),
+    )) as OpencodeSession;
+    const emitted: ProviderEvent[] = [];
+    session.onEvent((e) => emitted.push(e));
+    const result = await session.waitForCompletion();
+
+    // Positive control: the key did reach the SDK config.
+    expect(configOf(host).provider.nan.options.apiKey).toBe(SENTINEL);
+    expect(captured.some((line) => line.includes("[opencode] config:"))).toBe(true);
+    expect(result.isError).toBe(true);
+
+    for (const line of captured) expect(line).not.toContain(SENTINEL);
+    expect(JSON.stringify(emitted)).not.toContain(SENTINEL);
+    expect(result.failureReason ?? "").not.toContain(SENTINEL);
+  });
+
+  test("a host start failure that echoes the config is scrubbed before it propagates", async () => {
+    captureConsole();
+    const host = makeFakeHost([]);
+    installHost(host, (options) => {
+      const content = (options.config as { content: string }).content;
+      throw new Error(`invalid config ${content}`);
+    });
+    const error = await new OpencodeAdapter()
+      .createSession(testConfig({ model: "nan/glm5.3-flash", env: { NAN_API_KEY: SENTINEL } }))
+      .then(
+        () => undefined,
+        (err: unknown) => err as Error,
+      );
+    expect(error?.message).toStartWith("opencode host failed to start: invalid config");
+    expect(error?.message).not.toContain(SENTINEL);
+    for (const line of captured) expect(line).not.toContain(SENTINEL);
+  });
+});

package/src/tests/opencode-helmcode-sdk.test.ts

@@ -0,0 +1,201 @@
+/**
+ * The provider key splice and the `helmcode` block, run through the real
+ * `@opencode/sdk` embedded host against a fake OpenAI-compatible server.
+ *
+ * `applyProviderKeySplice` builds the provider entry; the test only repoints
+ * `options.baseURL` at a local `Bun.serve({ port: 0 })` that answers
+ * `/v1/chat/completions`, then checks the request OpenCode sent: the picked
+ * pool member as the bearer (not the comma pool sitting in `process.env`) and
+ * the bare model id. The model catalog is bundled in the SDK, and no request
+ * leaves the machine. The control test pins why `env: []` is needed: without
+ * it, the pool in `process.env` beats `options.apiKey`.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { OpenCode, type OpenCodeEvent } from "@opencode/sdk";
+import { applyProviderKeySplice, type OpencodeConfig } from "../providers/opencode-adapter";
+
+const TEST_TIMEOUT_MS = 60_000;
+
+const PICKED = "sk-helmcode-picked-live-0123456789";
+const POOL_IN_PROCESS_ENV = "sk-helmcode-wrong-aaaaaaaaaa,sk-helmcode-wrong-bbbbbbbbbb";
+
+type SeenRequest = { path: string; authorization: string | null; model?: string };
+
+let server: ReturnType<typeof Bun.serve>;
+let directory: string;
+const seen: SeenRequest[] = [];
+let prevHelmcodeKey: string | undefined;
+
+/** One streamed (or plain) assistant turn that says "pong". */
+function completion(model: string, stream: boolean): Response {
+  const base = { id: "chatcmpl-test", created: 0, model };
+  const usage = { prompt_tokens: 5, completion_tokens: 1, total_tokens: 6 };
+  if (!stream) {
+    return Response.json({
+      ...base,
+      object: "chat.completion",
+      choices: [
+        {
+          index: 0,
+          message: { role: "assistant", content: "pong" },
+          finish_reason: "stop",
+        },
+      ],
+      usage,
+    });
+  }
+  const chunk = (body: Record<string, unknown>) =>
+    `data: ${JSON.stringify({ ...base, object: "chat.completion.chunk", ...body })}\n\n`;
+  const sse =
+    chunk({
+      choices: [{ index: 0, delta: { role: "assistant", content: "pong" }, finish_reason: null }],
+    }) +
+    chunk({ choices: [{ index: 0, delta: {}, finish_reason: "stop" }], usage }) +
+    "data: [DONE]\n\n";
+  return new Response(sse, { headers: { "content-type": "text/event-stream" } });
+}
+
+beforeAll(() => {
+  directory = mkdtempSync(join(tmpdir(), "opencode-helmcode-sdk-"));
+  server = Bun.serve({
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+      const body = req.method === "POST" ? ((await req.json().catch(() => ({}))) as any) : {};
+      seen.push({
+        path: url.pathname,
+        authorization: req.headers.get("authorization"),
+        model: body?.model,
+      });
+      if (url.pathname.endsWith("/chat/completions")) {
+        return completion(String(body?.model ?? ""), body?.stream === true);
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+  // The pool a production entrypoint exports raw; the splice must beat it.
+  prevHelmcodeKey = process.env.HELMCODE_API_KEY;
+  process.env.HELMCODE_API_KEY = POOL_IN_PROCESS_ENV;
+});
+
+afterAll(() => {
+  server.stop(true);
+  rmSync(directory, { recursive: true, force: true });
+  if (prevHelmcodeKey === undefined) delete process.env.HELMCODE_API_KEY;
+  else process.env.HELMCODE_API_KEY = prevHelmcodeKey;
+});
+
+async function runOnePrompt(config: OpencodeConfig): Promise<string> {
+  const host = await OpenCode.create({
+    config: { content: JSON.stringify(config) },
+    plugins: [],
+    log: { level: "error", emit: () => {} },
+  });
+  try {
+    const session = await host.sessions.create({ location: { directory } });
+    const done = (async () => {
+      for await (const event of host.events.subscribe() as AsyncIterable<OpenCodeEvent>) {
+        const data = (event as { data?: { sessionID?: string; error?: unknown } }).data;
+        if (data?.sessionID !== session.id) continue;
+        if (event.type === "session.execution.succeeded") return "succeeded";
+        if (event.type === "session.execution.failed") {
+          return `failed: ${JSON.stringify(data.error)}`;
+        }
+      }
+      return "stream ended";
+    })();
+    await host.sessions.prompt({ sessionID: session.id, text: "say pong", delivery: "queue" });
+    return await done;
+  } finally {
+    await host.close();
+  }
+}
+
+describe("provider key splice through the real OpenCode host", () => {
+  test(
+    "sends the picked key and the bare model id to the provider's baseURL",
+    async () => {
+      seen.length = 0;
+      const model = "helmcode/glm5.3";
+      const config: OpencodeConfig = { model };
+      const spliced = applyProviderKeySplice(config, model, { HELMCODE_API_KEY: PICKED });
+      expect(spliced?.name).toBe("HELMCODE_API_KEY");
+      const helmcode = config.provider?.helmcode;
+      if (!helmcode?.options) throw new Error("helmcode block missing");
+      helmcode.options.baseURL = `http://127.0.0.1:${server.port}/v1`;
+
+      const outcome = await runOnePrompt(config);
+
+      const chats = seen.filter((r) => r.path === "/v1/chat/completions");
+      expect(chats.length).toBeGreaterThan(0);
+      for (const chat of chats) {
+        expect(chat.authorization).toBe(`Bearer ${PICKED}`);
+        expect(chat.model).toBe("glm5.3");
+      }
+      expect(outcome).toBe("succeeded");
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "nan (built-in provider): env [] plus the picked key beats a pool in process.env",
+    async () => {
+      const prevNan = process.env.NAN_API_KEY;
+      process.env.NAN_API_KEY = POOL_IN_PROCESS_ENV;
+      seen.length = 0;
+      try {
+        const model = "nan/glm5.3-flash";
+        const config: OpencodeConfig = { model };
+        const spliced = applyProviderKeySplice(config, model, { NAN_API_KEY: PICKED });
+        expect(spliced?.name).toBe("NAN_API_KEY");
+        const nan = config.provider?.nan;
+        if (!nan?.options) throw new Error("nan block missing");
+        nan.options.baseURL = `http://127.0.0.1:${server.port}/v1`;
+
+        const outcome = await runOnePrompt(config);
+
+        const chats = seen.filter((r) => r.path === "/v1/chat/completions");
+        expect(chats.length).toBeGreaterThan(0);
+        for (const chat of chats) {
+          expect(chat.authorization).toBe(`Bearer ${PICKED}`);
+          expect(chat.model).toBe("glm5.3-flash");
+        }
+        expect(outcome).toBe("succeeded");
+      } finally {
+        if (prevNan === undefined) delete process.env.NAN_API_KEY;
+        else process.env.NAN_API_KEY = prevNan;
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "nan control: without the splice the pool in process.env reaches the provider",
+    async () => {
+      const prevNan = process.env.NAN_API_KEY;
+      process.env.NAN_API_KEY = POOL_IN_PROCESS_ENV;
+      seen.length = 0;
+      try {
+        const model = "nan/glm5.3-flash";
+        const config: OpencodeConfig = {
+          model,
+          provider: {
+            nan: { options: { apiKey: PICKED, baseURL: `http://127.0.0.1:${server.port}/v1` } },
+          },
+        };
+        await runOnePrompt(config);
+        const chats = seen.filter((r) => r.path === "/v1/chat/completions");
+        expect(chats.length).toBeGreaterThan(0);
+        expect(chats[0]?.authorization).not.toBe(`Bearer ${PICKED}`);
+      } finally {
+        if (prevNan === undefined) delete process.env.NAN_API_KEY;
+        else process.env.NAN_API_KEY = prevNan;
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+});