feat(adapters): external adapter plugin system with dynamic UI parser

- Plugin loader: install/reload/remove/reinstall external adapters
  from npm packages or local directories
- Plugin store persisted at ~/.paperclip/adapter-plugins.json
- Self-healing UI parser resolution with version caching
- UI: Adapter Manager page, dynamic loader, display registry
  with humanized names for unknown adapter types
- Dev watch: exclude adapter-plugins dir from tsx watcher
  to prevent mid-request server restarts during reinstall
- All consumer fallbacks use getAdapterLabel() for consistent display
- AdapterTypeDropdown uses controlled open state for proper close behavior
- Remove hermes-local from built-in UI (externalized to plugin)
- Add docs for external adapters and UI parser contract

server/src/adapters/index.ts

@@ -1,4 +1,13 @@
-export { getServerAdapter, listAdapterModels, listServerAdapters, findServerAdapter, detectAdapterModel } from "./registry.js";
+export {
+  getServerAdapter,
+  listAdapterModels,
+  listServerAdapters,
+  findServerAdapter,
+  detectAdapterModel,
+  registerServerAdapter,
+  unregisterServerAdapter,
+  requireServerAdapter,
+} from "./registry.js";
 export type {
   ServerAdapterModule,
   AdapterExecutionContext,

server/src/adapters/plugin-loader.ts

@@ -0,0 +1,262 @@
+/**
+ * External adapter plugin loader.
+ *
+ * Loads external adapter packages from the adapter-plugin-store and returns
+ * their ServerAdapterModule instances. The caller (registry.ts) is
+ * responsible for registering them.
+ *
+ * This avoids circular initialization: plugin-loader imports only
+ * adapter-utils, never registry.ts.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ServerAdapterModule } from "./types.js";
+import { logger } from "../middleware/logger.js";
+
+import {
+  listAdapterPlugins,
+  getAdapterPluginsDir,
+  getAdapterPluginByType,
+} from "../services/adapter-plugin-store.js";
+import type { AdapterPluginRecord } from "../services/adapter-plugin-store.js";
+
+// ---------------------------------------------------------------------------
+// In-memory UI parser cache
+// ---------------------------------------------------------------------------
+
+const uiParserCache = new Map<string, string>();
+
+export function getUiParserSource(adapterType: string): string | undefined {
+  return uiParserCache.get(adapterType);
+}
+
+/**
+ * On cache miss, attempt on-demand extraction from the plugin store.
+ * Makes the ui-parser.js endpoint self-healing.
+ */
+export function getOrExtractUiParserSource(adapterType: string): string | undefined {
+  const cached = uiParserCache.get(adapterType);
+  if (cached) return cached;
+
+  const record = getAdapterPluginByType(adapterType);
+  if (!record) return undefined;
+
+  const packageDir = resolvePackageDir(record);
+  const source = extractUiParserSource(packageDir, record.packageName);
+  if (source) {
+    uiParserCache.set(adapterType, source);
+    logger.info(
+      { type: adapterType, packageName: record.packageName, origin: "lazy" },
+      "UI parser extracted on-demand (cache miss)",
+    );
+  }
+  return source;
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function resolvePackageDir(record: Pick<AdapterPluginRecord, "localPath" | "packageName">): string {
+  return record.localPath
+    ? path.resolve(record.localPath)
+    : path.resolve(getAdapterPluginsDir(), "node_modules", record.packageName);
+}
+
+function resolvePackageEntryPoint(packageDir: string): string {
+  const pkgJsonPath = path.join(packageDir, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+
+  if (pkg.exports && typeof pkg.exports === "object" && pkg.exports["."]) {
+    const exp = pkg.exports["."];
+    return typeof exp === "string" ? exp : (exp.import ?? exp.default ?? "index.js");
+  }
+  return pkg.main ?? "index.js";
+}
+
+// ---------------------------------------------------------------------------
+// UI parser extraction
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_PARSER_CONTRACT = "1";
+
+function extractUiParserSource(
+  packageDir: string,
+  packageName: string,
+): string | undefined {
+  const pkgJsonPath = path.join(packageDir, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+
+  if (!pkg.exports || typeof pkg.exports !== "object" || !pkg.exports["./ui-parser"]) {
+    return undefined;
+  }
+
+  const contractVersion = pkg.paperclip?.adapterUiParser;
+  if (contractVersion) {
+    const major = contractVersion.split(".")[0];
+    if (major !== SUPPORTED_PARSER_CONTRACT) {
+      logger.warn(
+        { packageName, contractVersion, supported: `${SUPPORTED_PARSER_CONTRACT}.x` },
+        "Adapter declares unsupported UI parser contract version — skipping UI parser",
+      );
+      return undefined;
+    }
+  } else {
+    logger.info(
+      { packageName },
+      "Adapter has ./ui-parser export but no paperclip.adapterUiParser version — loading anyway (future versions may require it)",
+    );
+  }
+
+  const uiParserExp = pkg.exports["./ui-parser"];
+  const uiParserFile = typeof uiParserExp === "string"
+    ? uiParserExp
+    : (uiParserExp.import ?? uiParserExp.default);
+  const uiParserPath = path.resolve(packageDir, uiParserFile);
+
+  if (!uiParserPath.startsWith(packageDir + path.sep) && uiParserPath !== packageDir) {
+    logger.warn(
+      { packageName, uiParserFile },
+      "UI parser path escapes package directory — skipping",
+    );
+    return undefined;
+  }
+
+  if (!fs.existsSync(uiParserPath)) {
+    return undefined;
+  }
+
+  try {
+    const source = fs.readFileSync(uiParserPath, "utf-8");
+    logger.info(
+      { packageName, uiParserFile, size: source.length },
+      `Loaded UI parser from adapter package${contractVersion ? "" : " (no version declared)"}`,
+    );
+    return source;
+  } catch (err) {
+    logger.warn({ err, packageName, uiParserFile }, "Failed to read UI parser from adapter package");
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Load / reload
+// ---------------------------------------------------------------------------
+
+function validateAdapterModule(mod: unknown, packageName: string): ServerAdapterModule {
+  const m = mod as Record<string, unknown>;
+  const createServerAdapter = m.createServerAdapter;
+  if (typeof createServerAdapter !== "function") {
+    throw new Error(
+      `Package "${packageName}" does not export createServerAdapter(). ` +
+      `Ensure the package's main entry exports a createServerAdapter function.`,
+    );
+  }
+
+  const adapterModule = createServerAdapter() as ServerAdapterModule;
+  if (!adapterModule || !adapterModule.type) {
+    throw new Error(
+      `createServerAdapter() from "${packageName}" returned an invalid module (missing "type").`,
+    );
+  }
+  return adapterModule;
+}
+
+export async function loadExternalAdapterPackage(
+  packageName: string,
+  localPath?: string,
+): Promise<ServerAdapterModule> {
+  const packageDir = localPath
+    ? path.resolve(localPath)
+    : path.resolve(getAdapterPluginsDir(), "node_modules", packageName);
+
+  const entryPoint = resolvePackageEntryPoint(packageDir);
+  const modulePath = path.resolve(packageDir, entryPoint);
+  const uiParserSource = extractUiParserSource(packageDir, packageName);
+
+  logger.info({ packageName, packageDir, entryPoint, modulePath, hasUiParser: !!uiParserSource }, "Loading external adapter package");
+
+  const mod = await import(modulePath);
+  const adapterModule = validateAdapterModule(mod, packageName);
+
+  if (uiParserSource) {
+    uiParserCache.set(adapterModule.type, uiParserSource);
+  }
+
+  return adapterModule;
+}
+
+async function loadFromRecord(record: AdapterPluginRecord): Promise<ServerAdapterModule | null> {
+  try {
+    return await loadExternalAdapterPackage(record.packageName, record.localPath);
+  } catch (err) {
+    logger.warn(
+      { err, packageName: record.packageName, type: record.type },
+      "Failed to dynamically load external adapter; skipping",
+    );
+    return null;
+  }
+}
+
+/**
+ * Reload an external adapter at runtime (dev iteration without server restart).
+ * Busts the ESM module cache via a cache-busting query string.
+ */
+export async function reloadExternalAdapter(
+  type: string,
+): Promise<ServerAdapterModule | null> {
+  const record = getAdapterPluginByType(type);
+  if (!record) return null;
+
+  const packageDir = resolvePackageDir(record);
+  const entryPoint = resolvePackageEntryPoint(packageDir);
+  const modulePath = path.resolve(packageDir, entryPoint);
+
+  const cacheBustUrl = `file://${modulePath}?t=${Date.now()}`;
+
+  logger.info(
+    { type, packageName: record.packageName, modulePath, cacheBustUrl },
+    "Reloading external adapter (cache bust)",
+  );
+
+  const mod = await import(cacheBustUrl);
+  const adapterModule = validateAdapterModule(mod, record.packageName);
+
+  uiParserCache.delete(type);
+  const uiParserSource = extractUiParserSource(packageDir, record.packageName);
+  if (uiParserSource) {
+    uiParserCache.set(adapterModule.type, uiParserSource);
+  }
+
+  logger.info(
+    { type, packageName: record.packageName, hasUiParser: !!uiParserSource },
+    "Successfully reloaded external adapter",
+  );
+
+  return adapterModule;
+}
+
+/**
+ * Build all external adapter modules from the plugin store.
+ */
+export async function buildExternalAdapters(): Promise<ServerAdapterModule[]> {
+  const results: ServerAdapterModule[] = [];
+
+  const storeRecords = listAdapterPlugins();
+  for (const record of storeRecords) {
+    const adapter = await loadFromRecord(record);
+    if (adapter) {
+      results.push(adapter);
+    }
+  }
+
+  if (results.length > 0) {
+    logger.info(
+      { count: results.length, adapters: results.map((a) => a.type) },
+      "Loaded external adapters from plugin store",
+    );
+  }
+
+  return results;
+}

server/src/adapters/registry.ts

@@ -67,18 +67,6 @@ import {
 import {
   agentConfigurationDoc as piAgentConfigurationDoc,
 } from "@paperclipai/adapter-pi-local";
-import {
-  execute as hermesExecute,
-  testEnvironment as hermesTestEnvironment,
-  sessionCodec as hermesSessionCodec,
-  listSkills as hermesListSkills,
-  syncSkills as hermesSyncSkills,
-  detectModel as detectModelFromHermes,
-} from "hermes-paperclip-adapter/server";
-import {
-  agentConfigurationDoc as hermesAgentConfigurationDoc,
-  models as hermesModels,
-} from "hermes-paperclip-adapter";
 import { processAdapter } from "./process/index.js";
 import { httpAdapter } from "./http/index.js";
 
@@ -175,21 +163,10 @@ const piLocalAdapter: ServerAdapterModule = {
   agentConfigurationDoc: piAgentConfigurationDoc,
 };
 
-const hermesLocalAdapter: ServerAdapterModule = {
-  type: "hermes_local",
-  execute: hermesExecute,
-  testEnvironment: hermesTestEnvironment,
-  sessionCodec: hermesSessionCodec,
-  listSkills: hermesListSkills,
-  syncSkills: hermesSyncSkills,
-  models: hermesModels,
-  supportsLocalAgentJwt: true,
-  agentConfigurationDoc: hermesAgentConfigurationDoc,
-  detectModel: () => detectModelFromHermes(),
-};
+const adaptersByType = new Map<string, ServerAdapterModule>();
 
-const adaptersByType = new Map<string, ServerAdapterModule>(
-  [
+function registerBuiltInAdapters() {
+  for (const adapter of [
     claudeLocalAdapter,
     codexLocalAdapter,
     openCodeLocalAdapter,
@@ -197,21 +174,84 @@ const adaptersByType = new Map<string, ServerAdapterModule>(
     cursorLocalAdapter,
     geminiLocalAdapter,
     openclawGatewayAdapter,
-    hermesLocalAdapter,
     processAdapter,
     httpAdapter,
-  ].map((a) => [a.type, a]),
-);
+  ]) {
+    adaptersByType.set(adapter.type, adapter);
+  }
+}
 
-export function getServerAdapter(type: string): ServerAdapterModule {
+registerBuiltInAdapters();
+
+// ---------------------------------------------------------------------------
+// Load external adapter plugins (droid, hermes, etc.)
+//
+// External adapter packages export createServerAdapter() which returns a
+// ServerAdapterModule. The host fills in sessionManagement.
+// ---------------------------------------------------------------------------
+
+import { buildExternalAdapters } from "./plugin-loader.js";
+import { getDisabledAdapterTypes } from "../services/adapter-plugin-store.js";
+
+/** Cached sync wrapper — the store is a simple JSON file read, safe to call frequently. */
+function getDisabledAdapterTypesFromStore(): string[] {
+  return getDisabledAdapterTypes();
+}
+
+/**
+ * Load external adapters from the plugin store and hardcoded sources.
+ * Called once at module initialization. The promise is exported so that
+ * callers (e.g. assertKnownAdapterType, app startup) can await completion
+ * and avoid racing against the loading window.
+ */
+const externalAdaptersReady: Promise<void> = (async () => {
+  try {
+    const externalAdapters = await buildExternalAdapters();
+    for (const externalAdapter of externalAdapters) {
+      adaptersByType.set(
+        externalAdapter.type,
+        {
+          ...externalAdapter,
+          sessionManagement: getAdapterSessionManagement(externalAdapter.type) ?? undefined,
+        },
+      );
+    }
+  } catch (err) {
+    console.error("[paperclip] Failed to load external adapters:", err);
+  }
+})();
+
+/**
+ * Await this before validating adapter types to avoid race conditions
+ * during server startup. External adapters are loaded asynchronously;
+ * calling assertKnownAdapterType before this resolves will reject
+ * valid external adapter types.
+ */
+export function waitForExternalAdapters(): Promise<void> {
+  return externalAdaptersReady;
+}
+
+export function registerServerAdapter(adapter: ServerAdapterModule): void {
+  adaptersByType.set(adapter.type, adapter);
+}
+
+export function unregisterServerAdapter(type: string): void {
+  if (type === processAdapter.type || type === httpAdapter.type) return;
+  adaptersByType.delete(type);
+}
+
+export function requireServerAdapter(type: string): ServerAdapterModule {
   const adapter = adaptersByType.get(type);
   if (!adapter) {
-    // Fall back to process adapter for unknown types
-    return processAdapter;
+    throw new Error(`Unknown adapter type: ${type}`);
   }
   return adapter;
 }
 
+export function getServerAdapter(type: string): ServerAdapterModule {
+  return adaptersByType.get(type) ?? processAdapter;
+}
+
 export async function listAdapterModels(type: string): Promise<{ id: string; label: string }[]> {
   const adapter = adaptersByType.get(type);
   if (!adapter) return [];
@@ -226,13 +266,32 @@ export function listServerAdapters(): ServerAdapterModule[] {
   return Array.from(adaptersByType.values());
 }
 
+/**
+ * List adapters excluding those that are disabled in settings.
+ * Used for menus and agent creation flows — disabled adapters remain
+ * functional for existing agents but hidden from selection.
+ */
+export function listEnabledServerAdapters(): ServerAdapterModule[] {
+  const disabled = getDisabledAdapterTypesFromStore();
+  const disabledSet = disabled.length > 0 ? new Set(disabled) : null;
+  return disabledSet
+    ? Array.from(adaptersByType.values()).filter((a) => !disabledSet.has(a.type))
+    : Array.from(adaptersByType.values());
+}
+
 export async function detectAdapterModel(
   type: string,
-): Promise<{ model: string; provider: string; source: string } | null> {
+): Promise<{ model: string; provider: string; source: string; candidates?: string[] } | null> {
   const adapter = adaptersByType.get(type);
   if (!adapter?.detectModel) return null;
   const detected = await adapter.detectModel();
-  return detected ? { model: detected.model, provider: detected.provider, source: detected.source } : null;
+  if (!detected) return null;
+  return {
+    model: detected.model,
+    provider: detected.provider,
+    source: detected.source,
+    ...(detected.candidates?.length ? { candidates: detected.candidates } : {}),
+  };
 }
 
 export function findServerAdapter(type: string): ServerAdapterModule | null {