feat(server): env-driven adapter model list for the model picker (#107)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: stubbi

server/src/adapters/registry.ts

@@ -4,6 +4,7 @@ import type {
   AdapterRuntimeCommandSpec,
   ServerAdapterModule,
 } from "./types.js";
+import { parseAdapterModelsEnv } from "../services/adapter-models-env.js";
 import {
   buildSandboxNpmInstallCommand,
   getAdapterSessionManagement,
@@ -655,6 +656,10 @@ export function getServerAdapter(type: string): ServerAdapterModule {
 }
 
 export async function listAdapterModels(type: string): Promise<{ id: string; label: string }[]> {
+  const declaredModels = parseAdapterModelsEnv();
+  if (declaredModels && declaredModels[type]?.length) {
+    return declaredModels[type].map((m) => ({ id: m.id, label: m.label ?? m.id }));
+  }
   const adapter = findActiveServerAdapter(type);
   if (!adapter) return [];
   if (adapter.listModels) {

server/src/services/adapter-models-env.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { parseAdapterModelsEnv } from "./adapter-models-env.js";
+
+const ENV = JSON.stringify({
+  opencode_local: [
+    { id: "tensorix/deepseek/deepseek-chat-v3.1", label: "DeepSeek v3.1" },
+    { id: "tensorix/z-ai/glm-4.7", label: "GLM 4.7" },
+  ],
+});
+
+describe("parseAdapterModelsEnv", () => {
+  it("returns null when unset", () => {
+    expect(parseAdapterModelsEnv({})).toBeNull();
+  });
+  it("parses the per-adapter model map", () => {
+    const m = parseAdapterModelsEnv({ PAPERCLIP_ADAPTER_MODELS: ENV });
+    expect(m?.opencode_local?.[0]).toEqual({ id: "tensorix/deepseek/deepseek-chat-v3.1", label: "DeepSeek v3.1" });
+    expect(m?.opencode_local?.length).toBe(2);
+  });
+  it("defaults label to id when omitted", () => {
+    const m = parseAdapterModelsEnv({ PAPERCLIP_ADAPTER_MODELS: JSON.stringify({ pi_local: [{ id: "tensorix/x/y" }] }) });
+    expect(m?.pi_local?.[0]).toEqual({ id: "tensorix/x/y", label: "tensorix/x/y" });
+  });
+  it("throws on invalid JSON (fail loud)", () => {
+    expect(() => parseAdapterModelsEnv({ PAPERCLIP_ADAPTER_MODELS: "{bad" })).toThrow(/PAPERCLIP_ADAPTER_MODELS/);
+  });
+  it("throws when an entry lacks a string id", () => {
+    expect(() => parseAdapterModelsEnv({ PAPERCLIP_ADAPTER_MODELS: JSON.stringify({ a: [{ label: "x" }] }) })).toThrow();
+  });
+});

server/src/services/adapter-models-env.ts

@@ -0,0 +1,40 @@
+export interface AdapterModelEntry {
+  id: string;
+  label?: string;
+}
+
+/**
+ * Per-adapter model list supplied by the operator via env, so the agent model
+ * picker can offer models the server cannot CLI-discover (e.g. gateway models).
+ * JSON object: adapterType -> [{ id, label? }]. Returns null when unset; throws
+ * loudly on malformed input.
+ */
+export function parseAdapterModelsEnv(
+  env: Record<string, string | undefined> = process.env,
+): Record<string, AdapterModelEntry[]> | null {
+  const raw = env.PAPERCLIP_ADAPTER_MODELS?.trim();
+  if (!raw) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`PAPERCLIP_ADAPTER_MODELS must be valid JSON: ${(e as Error).message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("PAPERCLIP_ADAPTER_MODELS must be a JSON object mapping adapterType to an array of {id,label}");
+  }
+  const out: Record<string, AdapterModelEntry[]> = {};
+  for (const [type, list] of Object.entries(parsed as Record<string, unknown>)) {
+    if (!Array.isArray(list)) {
+      throw new Error(`PAPERCLIP_ADAPTER_MODELS[${type}] must be an array`);
+    }
+    out[type] = list.map((m) => {
+      const o = m as Record<string, unknown>;
+      if (typeof o.id !== "string" || !o.id) {
+        throw new Error(`PAPERCLIP_ADAPTER_MODELS[${type}] entries require a non-empty string id`);
+      }
+      return { id: o.id, label: typeof o.label === "string" ? o.label : o.id };
+    });
+  }
+  return out;
+}