feat: declarative adapter registry (PAPERCLIP_ADAPTERS) (#104)

* feat(shared): add AdapterRegistryEntry declarative adapter type

* feat(shared): zod validator for the declarative adapter registry

* feat(plugin-kubernetes): resolve adapter defaults from a supplied registry + defaultEnv

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(plugin-kubernetes): accept declarative adapters registry in provider config

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(plugin-kubernetes): use the configured registry + defaultEnv when building agent env

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(plugin-kubernetes): define adapter registry schema locally (no workspace dep)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(server): parse PAPERCLIP_ADAPTERS + reconcile adapter availability (fail loud)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(server): thread declared adapter registry into the kubernetes env config

* feat(server): reconcile adapter availability from PAPERCLIP_ADAPTERS at startup

---------

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

Author: stubbi

packages/plugins/sandbox-providers/kubernetes/src/adapter-defaults.ts

@@ -1,8 +1,12 @@
+import type { AdapterRegistryEntry } from "./adapter-registry.js";
+
 export interface AdapterDefaults {
   runtimeImage: string;
   envKeys: string[];
   allowFqdns: string[];
   probeCommand: string[];
+  /** Non-secret env injected as the base layer for the Job (process-env wins on top). */
+  defaultEnv?: Record<string, string>;
 }
 
 const REGISTRY: Record<string, AdapterDefaults> = {
@@ -52,10 +56,61 @@ const REGISTRY: Record<string, AdapterDefaults> = {
 
 export const KNOWN_ADAPTER_TYPES: ReadonlySet<string> = new Set(Object.keys(REGISTRY));
 
-export function getAdapterDefaults(adapterType: string): AdapterDefaults {
+function fromRegistryEntry(entry: AdapterRegistryEntry): AdapterDefaults {
+  // Only runtimeImage is strictly required. The array fields are optional and
+  // default to []: the operator emits them with `omitempty`, so a genuinely
+  // empty allowFqdns/envKeys/probeCommand arrives as undefined, which is valid
+  // (no extra egress / no forwarded secrets / no probe), NOT an error.
+  if (!entry.runtimeImage) {
+    throw new Error(
+      `Adapter "${entry.adapterType}" is missing required runtime field: runtimeImage`,
+    );
+  }
+  return {
+    runtimeImage: entry.runtimeImage,
+    envKeys: entry.envKeys ?? [],
+    allowFqdns: entry.allowFqdns ?? [],
+    probeCommand: entry.probeCommand ?? [],
+    defaultEnv: entry.defaultEnv,
+  };
+}
+
+/**
+ * Resolve the runtime defaults for an adapter. When a `registry` is supplied it
+ * is authoritative (replace semantics): the type MUST be present and complete,
+ * else this throws. With no registry, falls back to the built-in REGISTRY.
+ */
+export function getAdapterDefaults(
+  adapterType: string,
+  registry?: readonly AdapterRegistryEntry[],
+): AdapterDefaults {
+  if (registry && registry.length > 0) {
+    const entry = registry.find((e) => e.adapterType === adapterType);
+    if (!entry) {
+      throw new Error(`Adapter "${adapterType}" is not in the configured adapter registry`);
+    }
+    return fromRegistryEntry(entry);
+  }
   const defaults = REGISTRY[adapterType];
   if (!defaults) {
     throw new Error(`Unknown adapter type: ${adapterType}`);
   }
   return defaults;
 }
+
+/**
+ * Build the per-run env for the Job: the non-secret `defaultEnv` is the base
+ * and the process-env values (the secret API keys named by `envKeys`) override
+ * it. Pure for testability.
+ */
+export function buildAdapterEnv(
+  defaults: AdapterDefaults,
+  processEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const out: Record<string, string> = { ...(defaults.defaultEnv ?? {}) };
+  for (const k of defaults.envKeys) {
+    const v = processEnv[k];
+    if (v) out[k] = v;
+  }
+  return out;
+}

packages/plugins/sandbox-providers/kubernetes/src/adapter-registry.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+/**
+ * One declarative agent-harness ("adapter") entry. Governs picker availability
+ * and, for sandboxed (Kubernetes) runs, the runtime wiring.
+ *
+ * NOTE: this shape is intentionally duplicated across the package boundary. It
+ * MUST stay structurally in sync with:
+ *   - server `@paperclipai/shared` `adapterRegistryEntrySchema` (the parser side)
+ *   - operator `AdapterRegistryEntry` Go struct (PAPERCLIP_ADAPTERS emitter)
+ * The duplication is deliberate: this plugin is standalone-installable and must
+ * not pull in heavy workspace packages at runtime.
+ */
+export const adapterRegistryEntrySchema = z
+  .object({
+    adapterType: z.string().min(1),
+    enabled: z.boolean().default(true),
+    runtimeImage: z.string().optional(),
+    envKeys: z.array(z.string()).optional(),
+    allowFqdns: z.array(z.string()).optional(),
+    probeCommand: z.array(z.string()).optional(),
+    defaultEnv: z.record(z.string()).optional(),
+  })
+  .strict();
+
+export const adapterRegistrySchema = z.array(adapterRegistryEntrySchema);
+
+export type AdapterRegistryEntry = z.infer<typeof adapterRegistryEntrySchema>;

packages/plugins/sandbox-providers/kubernetes/src/plugin.ts

@@ -19,7 +19,7 @@ import {
   type KubernetesLeaseMetadata,
 } from "./types.js";
 import { createKubeConfig, makeKubeClients } from "./kube-client.js";
-import { getAdapterDefaults } from "./adapter-defaults.js";
+import { getAdapterDefaults, buildAdapterEnv } from "./adapter-defaults.js";
 import { resolveImage } from "./image-allowlist.js";
 import { buildJobManifest } from "./pod-spec-builder.js";
 import { buildSandboxCrManifest } from "./sandbox-cr-builder.js";
@@ -64,24 +64,6 @@ function deriveTenantNamespace(config: KubernetesProviderConfig, companyId: stri
   return deriveNamespaceName(config.namespacePrefix, slug);
 }
 
-/**
- * Reads adapter env keys (e.g. ANTHROPIC_API_KEY) from the current process
- * environment. The plugin worker runs inside paperclip-server's pod, which has
- * these vars injected at deploy time.
- *
- * M4b approach: env vars sourced from process.env at acquire time.
- * TODO: future milestones may thread per-run secrets differently (e.g. via
- * a secret store reference on the environment config).
- */
-function extractAdapterEnvFromProcess(envKeys: string[]): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const k of envKeys) {
-    const v = process.env[k];
-    if (v) out[k] = v;
-  }
-  return out;
-}
-
 function generateBootstrapToken(): string {
   // TODO: paperclip-server's actual callback auth scheme is separate and is
   // out of M4b scope. This per-run random token is stored in the per-run
@@ -136,7 +118,7 @@ const plugin = definePlugin({
     }
     const warnings: string[] = [];
     const cfg = parsed.data;
-    const adapterDefaults = getAdapterDefaults(cfg.adapterType);
+    const adapterDefaults = getAdapterDefaults(cfg.adapterType, cfg.adapters);
     const totalFqdns = [...adapterDefaults.allowFqdns, ...cfg.egressAllowFqdns];
     if (cfg.egressMode === "standard" && totalFqdns.length > 0) {
       if (cfg.egressAllowCidrs.length === 0) {
@@ -212,7 +194,7 @@ const plugin = definePlugin({
     // Emit a runtime warning if FQDNs are configured but egressMode=standard
     // cannot enforce them. Mirrors the validateConfig warning so operators see
     // it in paperclip-server logs even if they missed the validation step.
-    const adapterDefaultsForWarn = getAdapterDefaults(config.adapterType);
+    const adapterDefaultsForWarn = getAdapterDefaults(config.adapterType, config.adapters);
     const totalFqdnsForWarn = [...adapterDefaultsForWarn.allowFqdns, ...config.egressAllowFqdns];
     if (config.egressMode === "standard" && totalFqdnsForWarn.length > 0) {
       if (config.egressAllowCidrs.length === 0) {
@@ -234,7 +216,7 @@ const plugin = definePlugin({
 
     // Ensure the tenant namespace and all its RBAC / network policy resources
     // exist before we try to create the Job.
-    const adapterDefaults = getAdapterDefaults(config.adapterType);
+    const adapterDefaults = getAdapterDefaults(config.adapterType, config.adapters);
 
     await ensureTenant(clients, {
       namespace,
@@ -299,9 +281,9 @@ const plugin = definePlugin({
 
     const { uid: ownerUid } = await orchestrator.claim(clients, namespace, manifest);
 
-    // M4b: adapter env vars are sourced from the plugin worker's own process
-    // environment (paperclip-server pod has them injected at deploy time).
-    const adapterEnv = extractAdapterEnvFromProcess(adapterDefaults.envKeys);
+    // defaultEnv (non-secret base, e.g. the inference base URL) is layered first;
+    // the process-env secrets named by envKeys override it.
+    const adapterEnv = buildAdapterEnv(adapterDefaults);
     const bootstrapToken = generateBootstrapToken();
 
     // Secret ownerRef: for job backend, the Job owns the Secret (cascade delete).

packages/plugins/sandbox-providers/kubernetes/src/types.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { adapterRegistrySchema } from "./adapter-registry.js";
 import { KNOWN_ADAPTER_TYPES } from "./adapter-defaults.js";
 
 const cidrRegex = /^(\d{1,3}\.){3}\d{1,3}\/\d{1,2}$/;
@@ -45,6 +46,13 @@ export const kubernetesProviderConfigSchema = z
         message: "adapterType must be one of the known adapter types",
       }),
 
+    /**
+     * Optional declarative adapter registry. When present it is authoritative
+     * for runtime image / envKeys / allowFqdns / probe / defaultEnv resolution
+     * (replace semantics). Absent = built-in defaults.
+     */
+    adapters: adapterRegistrySchema.optional(),
+
     /**
      * The sandbox backend to use.
      *

packages/plugins/sandbox-providers/kubernetes/test/unit/adapter-defaults.test.ts

@@ -1,7 +1,13 @@
 import { describe, it, expect } from "vitest";
-import { getAdapterDefaults, KNOWN_ADAPTER_TYPES } from "../../src/adapter-defaults.js";
+import {
+  getAdapterDefaults,
+  buildAdapterEnv,
+  KNOWN_ADAPTER_TYPES,
+  type AdapterDefaults,
+} from "../../src/adapter-defaults.js";
+import type { AdapterRegistryEntry } from "../../src/adapter-registry.js";
 
-describe("adapter-defaults", () => {
+describe("adapter-defaults (built-in)", () => {
   it("returns defaults for claude_local", () => {
     const d = getAdapterDefaults("claude_local");
     expect(d.runtimeImage).toBe("ghcr.io/paperclipai/agent-runtime-claude:v1");
@@ -35,3 +41,94 @@ describe("adapter-defaults", () => {
     );
   });
 });
+
+describe("getAdapterDefaults", () => {
+  it("returns built-in defaults when no registry is supplied", () => {
+    const d = getAdapterDefaults("claude_local");
+    expect(d.runtimeImage).toContain("agent-runtime-claude");
+    expect(d.envKeys).toEqual(["ANTHROPIC_API_KEY"]);
+    expect(d.defaultEnv).toBeUndefined();
+  });
+
+  it("throws on an unknown built-in type when no registry is supplied", () => {
+    expect(() => getAdapterDefaults("nope")).toThrow(/Unknown adapter type/);
+  });
+
+  it("resolves from the supplied registry (replace semantics, not merge)", () => {
+    const registry: AdapterRegistryEntry[] = [
+      {
+        adapterType: "opencode_local",
+        enabled: true,
+        runtimeImage: "registry.example/opencode:eu",
+        envKeys: ["ANTHROPIC_API_KEY"],
+        allowFqdns: [],
+        probeCommand: ["opencode", "--version"],
+        defaultEnv: { ANTHROPIC_BASE_URL: "http://bifrost:8080" },
+      },
+    ];
+    const d = getAdapterDefaults("opencode_local", registry);
+    expect(d.runtimeImage).toBe("registry.example/opencode:eu");
+    expect(d.defaultEnv).toEqual({ ANTHROPIC_BASE_URL: "http://bifrost:8080" });
+  });
+
+  it("throws when the type is absent from a supplied registry", () => {
+    const registry: AdapterRegistryEntry[] = [
+      {
+        adapterType: "opencode_local",
+        runtimeImage: "x",
+        envKeys: [],
+        allowFqdns: [],
+        probeCommand: ["x"],
+      },
+    ];
+    expect(() => getAdapterDefaults("claude_local", registry)).toThrow(
+      /not in the configured adapter registry/,
+    );
+  });
+
+  it("throws when a supplied registry entry is missing runtimeImage", () => {
+    const registry: AdapterRegistryEntry[] = [
+      { adapterType: "opencode_local", envKeys: [], allowFqdns: [], probeCommand: ["x"] },
+    ];
+    expect(() => getAdapterDefaults("opencode_local", registry)).toThrow(
+      /missing required runtime field: runtimeImage/,
+    );
+  });
+
+  it("defaults the optional array fields to [] when the registry omits them", () => {
+    const registry: AdapterRegistryEntry[] = [
+      { adapterType: "opencode_local", runtimeImage: "img" },
+    ];
+    const d = getAdapterDefaults("opencode_local", registry);
+    expect(d.envKeys).toEqual([]);
+    expect(d.allowFqdns).toEqual([]);
+    expect(d.probeCommand).toEqual([]);
+  });
+});
+
+describe("buildAdapterEnv", () => {
+  it("layers process-env (secret) over defaultEnv (non-secret base)", () => {
+    const defaults: AdapterDefaults = {
+      runtimeImage: "x",
+      envKeys: ["ANTHROPIC_API_KEY"],
+      allowFqdns: [],
+      probeCommand: ["x"],
+      defaultEnv: { ANTHROPIC_BASE_URL: "http://bifrost:8080", ANTHROPIC_API_KEY: "should-be-overridden" },
+    };
+    const env = buildAdapterEnv(defaults, { ANTHROPIC_API_KEY: "sk-real" });
+    expect(env).toEqual({
+      ANTHROPIC_BASE_URL: "http://bifrost:8080",
+      ANTHROPIC_API_KEY: "sk-real",
+    });
+  });
+
+  it("omits process-env keys that are absent", () => {
+    const defaults: AdapterDefaults = {
+      runtimeImage: "x",
+      envKeys: ["ANTHROPIC_API_KEY"],
+      allowFqdns: [],
+      probeCommand: ["x"],
+    };
+    expect(buildAdapterEnv(defaults, {})).toEqual({});
+  });
+});

packages/shared/src/index.ts

@@ -1375,3 +1375,11 @@ export type {
   EnvironmentProviderCapability,
   EnvironmentSupportStatus,
 } from "./environment-support.js";
+
+export type { AdapterRegistryEntry } from "./types/adapter-registry.js";
+
+export {
+  adapterRegistryEntrySchema,
+  adapterRegistrySchema,
+  type AdapterRegistryEntryParsed,
+} from "./validators/adapter-registry.js";

packages/shared/src/types/adapter-registry.ts

@@ -0,0 +1,30 @@
+/**
+ * One declarative agent-harness ("adapter") entry. The same shape is used for
+ * local self-hosting and our operator/cloud: it governs both availability (the
+ * picker) and, when the run is sandboxed on Kubernetes, the runtime wiring.
+ *
+ * Replace semantics: when a registry is supplied it is the COMPLETE declared
+ * set. Adopt (built-in defaults) = no registry at all. Remove = omit the entry.
+ * Add = include a new entry. Override = redefine an existing adapterType.
+ */
+export interface AdapterRegistryEntry {
+  /** The harness, e.g. "opencode_local". */
+  adapterType: string;
+  /** Availability (both local + k8s). Default true. */
+  enabled?: boolean;
+  /** k8s-sandbox-only: container image the Job/Sandbox runs. */
+  runtimeImage?: string;
+  /** k8s-sandbox-only: process-env keys forwarded into the Job (e.g. ANTHROPIC_API_KEY). */
+  envKeys?: string[];
+  /** k8s-sandbox-only: egress FQDN allow-list for the agent pod. */
+  allowFqdns?: string[];
+  /** k8s-sandbox-only: liveness/probe command. */
+  probeCommand?: string[];
+  /**
+   * Non-secret env injected into the Job/Sandbox as the BASE; the process-env
+   * values (the secret API key, via envKeys) override it. Carries e.g.
+   * ANTHROPIC_BASE_URL pointing at the in-cluster Bifrost gateway. NEVER put
+   * secrets here.
+   */
+  defaultEnv?: Record<string, string>;
+}

packages/shared/src/validators/adapter-registry.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { adapterRegistrySchema } from "./adapter-registry.js";
+
+describe("adapterRegistrySchema", () => {
+  it("parses a full entry", () => {
+    const parsed = adapterRegistrySchema.parse([
+      {
+        adapterType: "opencode_local",
+        runtimeImage: "ghcr.io/paperclipai/agent-runtime-opencode:v1",
+        envKeys: ["ANTHROPIC_API_KEY"],
+        allowFqdns: [],
+        probeCommand: ["opencode", "--version"],
+        defaultEnv: { ANTHROPIC_BASE_URL: "http://bifrost.bifrost.svc.cluster.local:8080" },
+      },
+    ]);
+    expect(parsed[0].adapterType).toBe("opencode_local");
+    expect(parsed[0].enabled).toBe(true); // defaulted
+    expect(parsed[0].defaultEnv?.ANTHROPIC_BASE_URL).toContain("bifrost");
+  });
+
+  it("defaults enabled to true and optional collections to undefined", () => {
+    const parsed = adapterRegistrySchema.parse([{ adapterType: "pi_local" }]);
+    expect(parsed[0]).toMatchObject({ adapterType: "pi_local", enabled: true });
+    expect(parsed[0].runtimeImage).toBeUndefined();
+  });
+
+  it("rejects an entry with no adapterType", () => {
+    expect(() => adapterRegistrySchema.parse([{ enabled: true }])).toThrow();
+  });
+
+  it("rejects a non-array", () => {
+    expect(() => adapterRegistrySchema.parse({ adapterType: "x" })).toThrow();
+  });
+});