@desplega.ai/agent-swarm 1.173.0 → 2.0.0

package/src/tests/explicit-model-validation.test.ts

@@ -542,7 +542,12 @@ describe("harness compatibility at every create entry point", () => {
   });
 
   test("send-task: the parent auto-route target is judged", async () => {
-    const parent = await createTaskExtended("codex parent", { agentId: codexId, source: "mcp" });
+    // The worker created the parent, so it may continue it (task.parent.attach).
+    const parent = await createTaskExtended("codex parent", {
+      agentId: codexId,
+      creatorAgentId: workerId,
+      source: "mcp",
+    });
     const refused = await sendTaskHandler(ownerCtx({ agentId: workerId }), {
       task: "child of a codex task",
       parentTaskId: parent.id,
@@ -662,3 +667,102 @@ describe("harness compatibility at every create entry point", () => {
     expect(String(res.body.error)).toContain("does not run on the codex harness");
   });
 });
+
+describe("nan and helmcode catalog models", () => {
+  let piId = "";
+  let opencodeId = "";
+
+  beforeAll(async () => {
+    piId = (
+      await createAgent({
+        name: "validation-pi",
+        isLead: false,
+        status: "idle",
+        harnessProvider: "pi",
+      })
+    ).id;
+    opencodeId = (
+      await createAgent({
+        name: "validation-opencode",
+        isLead: false,
+        status: "idle",
+        harnessProvider: "opencode",
+      })
+    ).id;
+  });
+
+  const ids = [
+    "nan/glm5.3-flash",
+    "nan/glm5.3",
+    "nan/mimo-v2.6-flash",
+    "helmcode/glm5.3",
+    "helmcode/qwen3.6",
+    "helmcode/deepseek-v4-flash",
+  ];
+
+  test("pi and opencode accept the ids without allowCustomModel", async () => {
+    for (const harnessProvider of ["pi", "opencode"]) {
+      for (const model of ids) {
+        expect(await explicitModelError({ model, harnessProvider })).toBeNull();
+      }
+    }
+  });
+
+  test("claude and codex reject them with the harness mismatch, even with allowCustomModel", async () => {
+    for (const harnessProvider of ["claude", "codex"]) {
+      for (const allowCustomModel of [false, true]) {
+        for (const model of ["nan/glm5.3-flash", "helmcode/glm5.3"]) {
+          expect(await explicitModelError({ model, harnessProvider, allowCustomModel })).toContain(
+            `does not run on the ${harnessProvider} harness`,
+          );
+        }
+      }
+    }
+  });
+
+  test("a misspelt helmcode id is unknown", async () => {
+    expect(
+      await explicitModelError({ model: "helmcode/glm-5.3", harnessProvider: "pi" }),
+    ).toContain("Unknown model");
+  });
+
+  test("send-task: pi and opencode agents take the ids, a claude agent gets the mismatch", async () => {
+    const sender = ownerCtx({ agentId: leadId });
+    const args = {
+      task: "nan route",
+      offerMode: false,
+      allowDuplicate: false,
+      routingReason: "human_pinned" as const,
+      routingNote: "pinned to check the nan/helmcode catalog ids",
+    };
+    for (const agentId of [piId, opencodeId]) {
+      for (const model of ["nan/mimo-v2.6-flash", "helmcode/glm5.3"]) {
+        const accepted = await sendTaskHandler(sender, {
+          ...args,
+          task: `nan route ${model} to ${agentId}`,
+          agentId,
+          model,
+        });
+        expect({ ok: accepted.ok, message: accepted.message }).toEqual({
+          ok: true,
+          message: expect.any(String),
+        });
+      }
+    }
+    const refused = await sendTaskHandler(sender, {
+      ...args,
+      agentId: workerId,
+      model: "helmcode/glm5.3",
+    });
+    expect(refused.ok).toBe(false);
+    expect(refused.message).toContain("does not run on the claude harness");
+  });
+
+  test("PATCH /api/agents/:id/runtime stores a helmcode model on a pi agent", async () => {
+    const res = await api("PATCH", `/api/agents/${piId}/runtime`, {
+      harness_provider: "pi",
+      model: "helmcode/glm5.3",
+    });
+    expect(res.status).toBe(200);
+  });
+});

package/src/tests/extensions-example-route-chat-channel.test.ts

@@ -0,0 +1,154 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, createAgent, getDbClient, getKv, initDb } from "../be/db";
+import { installExtension, listExtensionRuns } from "../be/extensions/db";
+import { enableExtension, stopExtensionRuntime } from "../extensions/lifecycle";
+import { chatSdkContextKey } from "../tasks/context-key";
+import type { Agent } from "../types";
+import {
+  flushChatBuffers,
+  postTelegramUpdate,
+  startTelegramHarness,
+  type TelegramHarness,
+  telegramUpdate,
+} from "./chat-sdk-harness";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-example-route-chat-channel.sqlite";
+
+let harness: TelegramHarness;
+let lead: Agent;
+let worker: Agent;
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
+  }
+}
+
+async function chatTask(chatId: number) {
+  return getDbClient().get<{ agentId: string | null }>(
+    "SELECT agentId FROM agent_tasks WHERE source = 'chat' AND contextKey = ? ORDER BY createdAt DESC LIMIT 1",
+    [chatSdkContextKey(`telegram:${chatId}`)],
+  );
+}
+
+/** A private-chat message, flushed out of the thread buffer. */
+async function sendDm(chatId: number, text: string): Promise<void> {
+  await postTelegramUpdate(telegramUpdate({ id: chatId, type: "private" }, text));
+  await flushChatBuffers();
+}
+
+async function installRouteFixture(channelId: string, agentId: string) {
+  const bundle = await loadBundleFixture("route-chat-channel-to-agent");
+  const { extension } = await installExtension({
+    ...bundle,
+    config: { adapter: "telegram", channelId, agentId },
+  });
+  return { extension, enabled: await enableExtension(extension.id) };
+}
+
+describe("extension Chat SDK channel routing", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+    lead = await createAgent({
+      id: crypto.randomUUID(),
+      name: "chat-route-lead",
+      isLead: true,
+      status: "idle",
+    });
+    worker = await createAgent({
+      id: crypto.randomUUID(),
+      name: "chat-route-worker",
+      isLead: false,
+      status: "idle",
+    });
+    harness = await startTelegramHarness();
+  });
+
+  afterAll(async () => {
+    await harness.stop();
+    await stopExtensionRuntime();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  beforeEach(async () => {
+    await stopExtensionRuntime();
+    await getDbClient().run("DELETE FROM extensions");
+  });
+
+  test("routes the configured channel to its agent and leaves other channels with the lead", async () => {
+    const { extension } = await installRouteFixture("telegram:3001", worker.id);
+
+    await sendDm(3001, "route this to the worker");
+    expect(await chatTask(3001)).toEqual({ agentId: worker.id });
+    expect(
+      (await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "pre.chat.route" && run.action === "modify",
+      ),
+    ).toBe(true);
+
+    await sendDm(3002, "use the normal route");
+    expect(await chatTask(3002)).toEqual({ agentId: lead.id });
+  });
+
+  test("a block creates no task", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const { extension } = await installExtension({
+      manifest: { ...bundle.manifest, name: "block-chat-route", description: "blocks chat" },
+      files: {
+        "hooks.ts": `import { block, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.chat.route", () => block("chat is muted"));
+};
+export default extension;
+`,
+      },
+    });
+    await enableExtension(extension.id);
+
+    await sendDm(3003, "this must not become a task");
+    expect(await chatTask(3003)).toBeNull();
+    const runs = await listExtensionRuns(extension.id);
+    expect(runs.some((run) => run.event === "pre.chat.route" && run.action === "block")).toBe(true);
+    // Ids only in the run subject: never the message text.
+    expect(runs.every((run) => !run.subject?.includes("must not"))).toBe(true);
+  });
+
+  test("falls back to the built-in router when the extension names an unknown agent", async () => {
+    await installRouteFixture("telegram:3004", "missing-agent");
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      await sendDm(3004, "use the fallback");
+      expect(await chatTask(3004)).toEqual({ agentId: lead.id });
+      expect(warn).toHaveBeenCalledWith(
+        "[chat-sdk] Extension selected an unknown agent missing-agent. Using the router.",
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test("post.chat.message carries the inbound sender", async () => {
+    const { extension, enabled } = await installRouteFixture("telegram:3005", worker.id);
+    await sendDm(3005, "record this message");
+
+    const deadline = Date.now() + 5_000;
+    while (
+      !(await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "post.chat.message" && run.action === "continue",
+      ) &&
+      Date.now() < deadline
+    ) {
+      await Bun.sleep(20);
+    }
+    expect(
+      await getKv(
+        `task:agent:${enabled.agentId}`,
+        "ext:route-chat-channel-to-agent:chat:telegram:3005",
+      ),
+    ).toMatchObject({ value: "777001" });
+  });
+});

package/src/tests/extensions-post-bridge.test.ts

@@ -33,6 +33,7 @@ const NEW_EVENTS = [
   "post.task.budgetRefused",
   "post.email.received",
   "post.kapso.message",
+  "post.chat.message",
   "post.vcs.event",
 ] as const satisfies readonly (keyof SwarmEventMap)[];
 
@@ -358,6 +359,56 @@ describe("extension post bridge: new events", () => {
     });
   });
 
+  describe("post.chat.message", () => {
+    test("chat.message.received dispatches an inbound event", async () => {
+      await registerCapture("capture");
+      workflowEventBus.emit("chat.message.received", {
+        adapter: "telegram",
+        channelId: "telegram:555001",
+        threadId: "telegram:555001",
+        userId: "555001",
+        text: "hello swarm",
+        messageId: "555001:11",
+      });
+      await waitForEvents(1);
+      expect(received).toEqual([
+        {
+          extension: "capture",
+          event: "post.chat.message",
+          payload: {
+            adapter: "telegram",
+            channelId: "telegram:555001",
+            threadId: "telegram:555001",
+            userId: "555001",
+            text: "hello swarm",
+            direction: "inbound",
+            messageId: "555001:11",
+          },
+        },
+      ]);
+    });
+
+    test("chat.message.sent dispatches an outbound event", async () => {
+      await registerCapture("capture");
+      workflowEventBus.emit("chat.message.sent", {
+        adapter: "telegram",
+        channelId: "telegram:555001",
+        threadId: "telegram:555001",
+        text: "done",
+        taskId: "task-1",
+      });
+      await waitForEvents(1);
+      expect(received[0]?.payload).toEqual({
+        adapter: "telegram",
+        channelId: "telegram:555001",
+        threadId: "telegram:555001",
+        text: "done",
+        direction: "outbound",
+        taskId: "task-1",
+      });
+    });
+  });
+
   describe("post.kapso.message", () => {
     test("a bus emit dispatches the typed payload", async () => {
       await registerCapture("capture");

package/src/tests/fetch-resolved-env.test.ts

@@ -120,6 +120,95 @@ describe("fetchResolvedEnv", () => {
       warning.mockRestore();
     }
   });
+
+  test("exportToEnv=false rows stay out of the harness env, even over a boot copy", async () => {
+    const agentId = crypto.randomUUID();
+    mockResponsesByAgentId.set(agentId, {
+      status: 200,
+      body: {
+        configs: [
+          { key: "VERCEL_TOKEN", value: "row-vercel", isSecret: true, exportToEnv: false },
+          { key: "GITHUB_TOKEN", value: "row-github", isSecret: true, exportToEnv: true },
+          { key: "PUBLIC_SETTING", value: "visible", isSecret: false, exportToEnv: true },
+          { key: "HIDDEN_SETTING", value: "hidden", isSecret: false, exportToEnv: false },
+          // A pre-215 API sends no flag: the row keeps exporting.
+          { key: "LEGACY_SECRET", value: "row-legacy", isSecret: true },
+          // Restricted keys never export, whatever the row says.
+          { key: "SLACK_APP_TOKEN", value: "row-xapp", isSecret: true, exportToEnv: true },
+        ],
+      },
+    });
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      // The base env stands for the container env or an older entrypoint's
+      // boot export; a withheld row must remove those copies too.
+      const result = await fetchResolvedEnv(testUrl, "key", agentId, {
+        VERCEL_TOKEN: "boot-vercel",
+        SLACK_APP_TOKEN: "boot-xapp",
+      });
+      expect(result.env.VERCEL_TOKEN).toBeUndefined();
+      expect(result.env.HIDDEN_SETTING).toBeUndefined();
+      expect(result.env.SLACK_APP_TOKEN).toBeUndefined();
+      expect(result.env.GITHUB_TOKEN).toBe("row-github");
+      expect(result.env.PUBLIC_SETTING).toBe("visible");
+      expect(result.env.LEGACY_SECRET).toBe("row-legacy");
+      const logged = log.mock.calls.map((call) => String(call[0])).join("\n");
+      expect(logged).toContain("HIDDEN_SETTING, SLACK_APP_TOKEN, VERCEL_TOKEN");
+      expect(logged).not.toContain("row-vercel");
+      expect(logged).not.toContain("boot-vercel");
+    } finally {
+      log.mockRestore();
+    }
+  });
+
+  test("a row revoked after boot leaves process.env, so merged adapter envs lose it", async () => {
+    const agentId = crypto.randomUUID();
+    const key = "REVOKED_AFTER_BOOT_SECRET";
+    mockResponsesByAgentId.set(agentId, {
+      status: 200,
+      body: { configs: [{ key, value: "row-value", isSecret: true, exportToEnv: false }] },
+    });
+    // The entrypoint exported the row at boot, before it was switched off.
+    process.env[key] = "boot-export";
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const result = await fetchResolvedEnv(testUrl, "key", agentId);
+      expect(result.env[key]).toBeUndefined();
+      expect(process.env[key]).toBeUndefined();
+      // The amp, dsh, grok, cursor and claude adapters spawn with this shape.
+      expect({ ...process.env, ...result.env }[key]).toBeUndefined();
+    } finally {
+      delete process.env[key];
+      log.mockRestore();
+    }
+  });
+
+  test("a masked row keeps its boot value only when the row is exported", async () => {
+    const agentId = crypto.randomUUID();
+    mockResponsesByAgentId.set(agentId, {
+      status: 200,
+      body: {
+        configs: [
+          { key: "EXPORTED_BOOT", value: MASKED_SECRET_VALUE, isSecret: true, exportToEnv: true },
+          { key: "WITHHELD_BOOT", value: MASKED_SECRET_VALUE, isSecret: true, exportToEnv: false },
+        ],
+      },
+    });
+    const warning = spyOn(console, "warn").mockImplementation(() => {});
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const result = await fetchResolvedEnv(testUrl, "key", agentId, {
+        EXPORTED_BOOT: "boot-exported",
+        WITHHELD_BOOT: "boot-withheld",
+      });
+      expect(result.env.EXPORTED_BOOT).toBe("boot-exported");
+      expect(result.env.WITHHELD_BOOT).toBeUndefined();
+    } finally {
+      warning.mockRestore();
+      log.mockRestore();
+    }
+  });
+
   test("repository scope requires the requested repository identity", async () => {
     const repoId = crypto.randomUUID();
     let url = "https://github.com/another-owner/fixture";
@@ -305,6 +394,45 @@ describe("fetchResolvedEnv", () => {
     ]);
   });
 
+  test("HELMCODE_API_NAN alias becomes NAN_API_KEY and pools for a nan/* model", async () => {
+    const agentId = crypto.randomUUID();
+    mockResponsesByAgentId.set(agentId, {
+      status: 200,
+      body: { configs: [{ key: "HELMCODE_API_NAN", value: "fixture-nan-a,fixture-nan-b" }] },
+    });
+    const result = await fetchResolvedEnv(testUrl, "key", agentId, {}, "nan/glm5.3-flash", {
+      provider: "opencode",
+    });
+    expect(result.env.NAN_API_KEY).toMatch(/^fixture-nan-[ab]$/);
+    expect(result.credentialSelections.map((selection) => selection.keyType)).toEqual([
+      "NAN_API_KEY",
+    ]);
+  });
+
+  test("an explicit NAN_API_KEY wins over the HELMCODE_API_NAN alias", async () => {
+    const agentId = crypto.randomUUID();
+    mockResponsesByAgentId.set(agentId, {
+      status: 200,
+      body: {
+        configs: [
+          { key: "NAN_API_KEY", value: "fixture-nan-canonical" },
+          { key: "HELMCODE_API_NAN", value: "fixture-nan-alias" },
+        ],
+      },
+    });
+    const result = await fetchResolvedEnv(testUrl, "key", agentId, {}, "nan/qwen3.6", {
+      provider: "pi",
+    });
+    expect(result.env.NAN_API_KEY).toBe("fixture-nan-canonical");
+  });
+
+  test("the alias also normalizes from the boot env when the API is unreachable", async () => {
+    const result = await fetchResolvedEnv("", "key", "agent-1", {
+      HELMCODE_API_NAN: "fixture-nan-boot",
+    });
+    expect(result.env.NAN_API_KEY).toBe("fixture-nan-boot");
+  });
+
   describe("model-scoped window filter — GET /api/keys/available?model=<family>", () => {
     beforeEach(() => {
       keysAvailableRequests.length = 0;

package/src/tests/fixtures/chat-sdk/telegram-private-text.json

@@ -0,0 +1,10 @@
+{
+  "update_id": 900001,
+  "message": {
+    "message_id": 11,
+    "date": 1760400000,
+    "chat": { "id": 555001, "type": "private", "first_name": "Taras", "username": "taras_test" },
+    "from": { "id": 555001, "is_bot": false, "first_name": "Taras", "username": "taras_test" },
+    "text": "hello swarm, please summarize the open tasks"
+  }
+}

package/src/tests/fixtures/extensions/route-chat-channel-to-agent/hooks.ts

@@ -0,0 +1,27 @@
+import { modify, type SwarmExtension } from "swarm-extension";
+import { z } from "zod";
+
+export const config = z.object({ adapter: z.string(), channelId: z.string(), agentId: z.string() });
+
+const manifest = {
+  name: "route-chat-channel-to-agent",
+  description: "Routes one Chat SDK channel to a configured agent",
+  version: "1.0.0",
+  runtime: "api",
+  assets: { hooks: "hooks.ts" },
+  config,
+} as const;
+
+const extension: SwarmExtension<typeof manifest> = (api) => {
+  api.on("pre.chat.route", (event, ctx) => {
+    if (event.adapter !== ctx.config.adapter || event.channelId !== ctx.config.channelId) return;
+    return modify({ target: { kind: "agent", agentId: ctx.config.agentId } });
+  });
+
+  api.on("post.chat.message", async (event, ctx) => {
+    if (event.direction !== "inbound" || !event.userId) return;
+    await ctx.state.set(`chat:${event.channelId}`, event.userId);
+  });
+};
+
+export default extension;

package/src/tests/fixtures/extensions/route-chat-channel-to-agent/manifest.json

@@ -0,0 +1,9 @@
+{
+  "name": "route-chat-channel-to-agent",
+  "description": "Routes one Chat SDK channel to a configured agent",
+  "version": "1.0.0",
+  "runtime": "api",
+  "assets": {
+    "hooks": "hooks.ts"
+  }
+}

package/src/tests/fixtures/openai-compatible-registry-extension.child.ts

@@ -0,0 +1,146 @@
+/**
+ * Proof that adding an OpenAI-compatible provider takes one registry entry.
+ *
+ * A fake `testgw` entry is added to the registry table
+ * (`packages/model-catalog/src/openai-compatible-providers.ts`) through
+ * `mock.module`, without editing any production file, and must reach
+ * credential routing, the opencode config, the pi models.json writer, the
+ * dashboard integration cards and the model picker groups.
+ *
+ * The mock is installed before any consumer below is imported (dynamic
+ * imports). Consumers cache derivations of the table at import (the
+ * integration cards, the picker constants), and `mock.module` cannot undo
+ * those, so this file only runs in its own `bun test` child process,
+ * spawned by `src/tests/openai-compatible-registry-extension.test.ts`. Its
+ * name keeps it out of the root test glob.
+ */
+import { afterAll, describe, expect, mock, test } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const REGISTRY_MODULE = "../../../packages/model-catalog/src/openai-compatible-providers.ts";
+
+const TESTGW = {
+  id: "testgw",
+  displayName: "TestGW",
+  description: "A fake gateway for the registry extension test.",
+  baseUrl: "https://testgw.invalid/v1",
+  docsUrl: "https://testgw.invalid/docs",
+  envVar: "TESTGW_API_KEY",
+  aliasEnvVars: [],
+  catalog: "registry",
+  npm: "@ai-sdk/openai-compatible",
+  models: [
+    {
+      id: "m1",
+      name: "Test Model 1",
+      contextWindow: 131072,
+      maxOutputTokens: 8192,
+      input: ["text"],
+      reasoning: true,
+      compat: { supportsDeveloperRole: true },
+      reasoningEfforts: ["low", "high"],
+    },
+  ],
+} as const;
+
+const real = (await import(REGISTRY_MODULE)) as {
+  OPENAI_COMPATIBLE_PROVIDERS: Record<string, unknown>;
+};
+const original = real.OPENAI_COMPATIBLE_PROVIDERS;
+mock.module(REGISTRY_MODULE, () => ({
+  OPENAI_COMPATIBLE_PROVIDERS: { ...original, testgw: TESTGW },
+}));
+
+// The test preload already loaded `src/utils/credentials.ts`, so only its
+// call-time paths (routing, pooling) see the mock; `CREDENTIAL_POOL_VARS` is
+// fixed at import and covered by the registry spread in its declaration.
+const { getModelAwareCredentialVars, resolveCredentialPools } = await import(
+  "../../utils/credentials"
+);
+const { applyProviderKeySplice } = await import("../../providers/opencode-adapter");
+type OpencodeConfig = import("../../providers/opencode-adapter").OpencodeConfig;
+const { writeSessionModelsJson } = await import("../../providers/pi-mono-adapter");
+const { INTEGRATIONS } = await import("../../../apps/ui/src/lib/integrations-catalog");
+const { modelGroupsForHarness } = await import("../../../apps/ui/src/lib/agent-runtime-models");
+
+const tmpDirs: string[] = [];
+afterAll(async () => {
+  for (const dir of tmpDirs) await rm(dir, { recursive: true, force: true });
+});
+
+describe("a new registry entry (testgw) reaches every derived surface", () => {
+  test("credential routing picks its key on pi and opencode", () => {
+    expect(getModelAwareCredentialVars("pi", "testgw/x")).toEqual(["TESTGW_API_KEY"]);
+    expect(getModelAwareCredentialVars("opencode", "testgw/x")).toEqual(["TESTGW_API_KEY"]);
+  });
+
+  test("its key pools alone for a testgw/* model", async () => {
+    const env: Record<string, string | undefined> = {
+      TESTGW_API_KEY: "example-gw-a,example-gw-b",
+      OPENROUTER_API_KEY: "example-or-a,example-or-b",
+    };
+    const selections = await resolveCredentialPools(env, { provider: "pi", model: "testgw/m1" });
+    expect(["example-gw-a", "example-gw-b"]).toContain(env.TESTGW_API_KEY ?? "");
+    expect(selections.map((s) => [s.keyType, s.total])).toEqual([["TESTGW_API_KEY", 2]]);
+    expect(env.OPENROUTER_API_KEY).toBe("example-or-a,example-or-b");
+  });
+
+  test("opencode gets a custom block with the picked key at the base URL", () => {
+    const config: OpencodeConfig = {};
+    const picked = applyProviderKeySplice(config, "testgw/m1", { TESTGW_API_KEY: "k1,k2" });
+    expect(picked).toEqual({ key: "k1", name: "TESTGW_API_KEY" });
+    const block = config.provider?.testgw;
+    expect(block?.npm).toBe("@ai-sdk/openai-compatible");
+    expect(block?.env).toEqual([]);
+    expect(block?.options).toEqual({ baseURL: "https://testgw.invalid/v1", apiKey: "k1" });
+    expect(block?.models?.m1).toMatchObject({ name: "Test Model 1", tool_call: true });
+
+    const overridden: OpencodeConfig = {};
+    applyProviderKeySplice(overridden, "testgw/m1", {
+      TESTGW_API_KEY: "k1",
+      TESTGW_BASE_URL: "http://127.0.0.1:9/v1",
+    });
+    expect(overridden.provider?.testgw?.options?.baseURL).toBe("http://127.0.0.1:9/v1");
+  });
+
+  test("the pi models.json writer adds its provider block", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "testgw-pi-"));
+    tmpDirs.push(dir);
+    const models = await writeSessionModelsJson(dir, { TESTGW_API_KEY: "k1" }, "testgw/m1");
+    const written = JSON.parse(await readFile(models.modelsPath as string, "utf-8"));
+    await models.dispose();
+    expect(written.providers.testgw).toMatchObject({
+      baseUrl: "https://testgw.invalid/v1",
+      api: "openai-completions",
+      apiKey: "$TESTGW_API_KEY",
+    });
+    expect(written.providers.testgw.models.map((m: { id: string }) => m.id)).toEqual(["m1"]);
+  });
+
+  test("the dashboard lists an integration card with its key and base URL", () => {
+    const card = INTEGRATIONS.find((def) => def.id === "testgw");
+    expect(card?.name).toBe("TestGW");
+    expect(card?.providerIconKey as string | undefined).toBe("testgw");
+    expect(card?.fields.map((f) => [f.key, f.isSecret])).toEqual([
+      ["TESTGW_API_KEY", true],
+      ["TESTGW_BASE_URL", false],
+    ]);
+  });
+
+  test("the picker shows its models, locked without a key and enabled with one", () => {
+    for (const harness of ["pi", "opencode"] as const) {
+      const locked = modelGroupsForHarness(harness, [], {}).find((g) => g.provider === "TestGW");
+      expect(locked?.enabled).toBe(false);
+      expect(locked?.requiredKey).toBe("TESTGW_API_KEY");
+      expect(locked?.models.map((m) => m.id)).toEqual(["testgw/m1"]);
+      expect(locked?.models[0]?.reasoningLevels).toEqual(["low", "high"]);
+
+      const enabled = modelGroupsForHarness(harness, [], { TESTGW_API_KEY: true }).find(
+        (g) => g.provider === "TestGW",
+      );
+      expect(enabled?.enabled).toBe(true);
+    }
+  });
+});