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

ui/src/adapters/adapter-display-registry.ts

@@ -0,0 +1,151 @@
+/**
+ * Single source of truth for adapter display metadata.
+ *
+ * Built-in adapters have entries in `adapterDisplayMap`. External (plugin)
+ * adapters get sensible defaults derived from their type string via
+ * `getAdapterDisplay()`.
+ */
+import type { ComponentType } from "react";
+import {
+  Bot,
+  Code,
+  Gem,
+  MousePointer2,
+  Sparkles,
+  Terminal,
+  Cpu,
+} from "lucide-react";
+import { OpenCodeLogoIcon } from "@/components/OpenCodeLogoIcon";
+
+// ---------------------------------------------------------------------------
+// Type suffix parsing
+// ---------------------------------------------------------------------------
+
+const TYPE_SUFFIXES: Record<string, string> = {
+  _local: "local",
+  _gateway: "gateway",
+};
+
+function getTypeSuffix(type: string): string | null {
+  for (const [suffix, mode] of Object.entries(TYPE_SUFFIXES)) {
+    if (type.endsWith(suffix)) return mode;
+  }
+  return null;
+}
+
+function withSuffix(label: string, suffix: string | null): string {
+  return suffix ? `${label} (${suffix})` : label;
+}
+
+// ---------------------------------------------------------------------------
+// Display metadata per adapter type
+// ---------------------------------------------------------------------------
+
+export interface AdapterDisplayInfo {
+  label: string;
+  description: string;
+  icon: ComponentType<{ className?: string }>;
+  recommended?: boolean;
+  comingSoon?: boolean;
+  disabledLabel?: string;
+}
+
+const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {
+  claude_local: {
+    label: "Claude Code",
+    description: "Local Claude agent",
+    icon: Sparkles,
+    recommended: true,
+  },
+  codex_local: {
+    label: "Codex",
+    description: "Local Codex agent",
+    icon: Code,
+    recommended: true,
+  },
+  gemini_local: {
+    label: "Gemini CLI",
+    description: "Local Gemini agent",
+    icon: Gem,
+  },
+  opencode_local: {
+    label: "OpenCode",
+    description: "Local multi-provider agent",
+    icon: OpenCodeLogoIcon,
+  },
+  pi_local: {
+    label: "Pi",
+    description: "Local Pi agent",
+    icon: Terminal,
+  },
+  cursor: {
+    label: "Cursor",
+    description: "Local Cursor agent",
+    icon: MousePointer2,
+  },
+  openclaw_gateway: {
+    label: "OpenClaw Gateway",
+    description: "Invoke OpenClaw via gateway protocol",
+    icon: Bot,
+    comingSoon: true,
+    disabledLabel: "Configure OpenClaw within the App",
+  },
+  process: {
+    label: "Process",
+    description: "Internal process adapter",
+    icon: Cpu,
+    comingSoon: true,
+  },
+  http: {
+    label: "HTTP",
+    description: "Internal HTTP adapter",
+    icon: Cpu,
+    comingSoon: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+function humanizeType(type: string): string {
+  // Strip known type suffixes so "droid_local" → "Droid", not "Droid Local"
+  let base = type;
+  for (const suffix of Object.keys(TYPE_SUFFIXES)) {
+    if (base.endsWith(suffix)) {
+      base = base.slice(0, -suffix.length);
+      break;
+    }
+  }
+  return base.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export function getAdapterLabel(type: string): string {
+  const base = adapterDisplayMap[type]?.label ?? humanizeType(type);
+  return withSuffix(base, getTypeSuffix(type));
+}
+
+export function getAdapterLabels(): Record<string, string> {
+  const suffixed: Record<string, string> = {};
+  for (const [type, info] of Object.entries(adapterDisplayMap)) {
+    suffixed[type] = withSuffix(info.label, getTypeSuffix(type));
+  }
+  return suffixed;
+}
+
+export function getAdapterDisplay(type: string): AdapterDisplayInfo {
+  const known = adapterDisplayMap[type];
+  if (known) return known;
+
+  const suffix = getTypeSuffix(type);
+  const label = withSuffix(humanizeType(type), suffix);
+  return {
+    label,
+    description: suffix ? `External ${suffix} adapter` : "External adapter",
+    icon: Cpu,
+  };
+}
+
+export function isKnownAdapterType(type: string): boolean {
+  return type in adapterDisplayMap;
+}

ui/src/adapters/disabled-store.ts

@@ -0,0 +1,33 @@
+/**
+ * Client-side store for disabled adapter types.
+ *
+ * Hydrated from the server's GET /api/adapters response.
+ * Provides synchronous reads so module-level constants can filter against it.
+ * Falls back to "nothing disabled" before the first hydration.
+ *
+ * Usage in components:
+ *   useQuery + adaptersApi.list() populates the store automatically.
+ *
+ * Usage in non-React code:
+ *   import { isAdapterTypeHidden } from "@/adapters/disabled-store";
+ */
+
+let disabledTypes = new Set<string>();
+
+/** Check if an adapter type is hidden from menus (sync read). */
+export function isAdapterTypeHidden(type: string): boolean {
+  return disabledTypes.has(type);
+}
+
+/** Get all hidden adapter types (sync read). */
+export function getHiddenAdapterTypes(): Set<string> {
+  return disabledTypes;
+}
+
+/**
+ * Hydrate the store from a server response.
+ * Called by components that fetch the adapters list.
+ */
+export function setDisabledAdapterTypes(types: string[]): void {
+  disabledTypes = new Set(types);
+}

ui/src/adapters/dynamic-loader.ts

@@ -0,0 +1,106 @@
+/**
+ * Dynamic UI parser loading for external adapters.
+ *
+ * When the Paperclip UI encounters an adapter type that doesn't have a
+ * built-in parser (e.g., an external adapter loaded via the plugin system),
+ * it fetches the parser JS from `/api/adapters/:type/ui-parser.js` and
+ * evaluates it to create a `parseStdoutLine` function.
+ *
+ * The parser module must export:
+ *   - `parseStdoutLine(line: string, ts: string): TranscriptEntry[]`
+ *   - optionally `createStdoutParser(): { parseLine, reset }` for stateful parsers
+ *
+ * This is the bridge between the server-side plugin system and the client-side
+ * UI rendering. Adapter developers ship a `dist/ui-parser.js` with zero
+ * runtime dependencies, and Paperclip's UI loads it on demand.
+ */
+
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+import type { StdoutLineParser } from "./types";
+
+// Cache of dynamically loaded parsers by adapter type.
+// Once loaded, the parser is reused for all runs of that adapter type.
+const dynamicParserCache = new Map<string, StdoutLineParser>();
+
+// Track which types we've already attempted to load (to avoid repeat 404s).
+const failedLoads = new Set<string>();
+
+/**
+ * Dynamically load a UI parser for an adapter type from the server API.
+ *
+ * Fetches `/api/adapters/:type/ui-parser.js`, evaluates the module source
+ * in a scoped context, and extracts the `parseStdoutLine` export.
+ *
+ * @returns A StdoutLineParser function, or null if unavailable.
+ */
+export async function loadDynamicParser(adapterType: string): Promise<StdoutLineParser | null> {
+  // Return cached parser if already loaded
+  const cached = dynamicParserCache.get(adapterType);
+  if (cached) return cached;
+
+  // Don't retry types that previously 404'd
+  if (failedLoads.has(adapterType)) return null;
+
+  try {
+    const response = await fetch(`/api/adapters/${encodeURIComponent(adapterType)}/ui-parser.js`);
+    if (!response.ok) {
+      failedLoads.add(adapterType);
+      return null;
+    }
+
+    const source = await response.text();
+
+    // Evaluate the module source using URL.createObjectURL + dynamic import().
+    // This properly supports ESM modules with `export` statements.
+    // (new Function("exports", source) would fail with SyntaxError on `export` keywords.)
+    const blob = new Blob([source], { type: "application/javascript" });
+    const blobUrl = URL.createObjectURL(blob);
+
+    let parseFn: StdoutLineParser;
+
+    try {
+      const mod = await import(/* @vite-ignore */ blobUrl);
+
+      // Prefer the factory function (stateful parser) if available,
+      // fall back to the static parseStdoutLine function.
+      if (typeof mod.createStdoutParser === "function") {
+        // Stateful parser — create one instance for the UI session.
+        // Each run creates its own transcript builder, so a single
+        // parser instance is sufficient per adapter type.
+        const parser = (mod.createStdoutParser as () => { parseLine: StdoutLineParser; reset: () => void })();
+        parseFn = parser.parseLine.bind(parser);
+      } else if (typeof mod.parseStdoutLine === "function") {
+        parseFn = mod.parseStdoutLine as StdoutLineParser;
+      } else {
+        console.warn(`[adapter-ui-loader] Module for "${adapterType}" exports neither parseStdoutLine nor createStdoutParser`);
+        failedLoads.add(adapterType);
+        return null;
+      }
+    } finally {
+      URL.revokeObjectURL(blobUrl);
+    }
+
+    // Cache for reuse
+    dynamicParserCache.set(adapterType, parseFn);
+    console.info(`[adapter-ui-loader] Loaded dynamic UI parser for "${adapterType}"`);
+    return parseFn;
+  } catch (err) {
+    console.warn(`[adapter-ui-loader] Failed to load UI parser for "${adapterType}":`, err);
+    failedLoads.add(adapterType);
+    return null;
+  }
+}
+
+/**
+ * Invalidate a cached dynamic parser, removing it from both the parser cache
+ * and the failed-loads set so that the next load attempt will try again.
+ */
+export function invalidateDynamicParser(adapterType: string): boolean {
+  const wasCached = dynamicParserCache.has(adapterType);
+  dynamicParserCache.delete(adapterType);
+  failedLoads.delete(adapterType);
+  if (wasCached) {
+    console.info(`[adapter-ui-loader] Invalidated dynamic UI parser for "${adapterType}"`);
+  }
+  return wasCached;
+}

ui/src/adapters/hermes-local/config-fields.tsx

@@ -1,49 +0,0 @@
-import type { AdapterConfigFieldsProps } from "../types";
-import {
-  Field,
-  DraftInput,
-} from "../../components/agent-config-primitives";
-import { ChoosePathButton } from "../../components/PathInstructionsModal";
-
-const inputClass =
-  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
-const instructionsFileHint =
-  "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";
-
-export function HermesLocalConfigFields({
-  isCreate,
-  values,
-  set,
-  config,
-  eff,
-  mark,
-  hideInstructionsFile,
-}: AdapterConfigFieldsProps) {
-  if (hideInstructionsFile) return null;
-  return (
-    <Field label="Agent instructions file" hint={instructionsFileHint}>
-      <div className="flex items-center gap-2">
-        <DraftInput
-          value={
-            isCreate
-              ? values!.instructionsFilePath ?? ""
-              : eff(
-                  "adapterConfig",
-                  "instructionsFilePath",
-                  String(config.instructionsFilePath ?? ""),
-                )
-          }
-          onCommit={(v) =>
-            isCreate
-              ? set!({ instructionsFilePath: v })
-              : mark("adapterConfig", "instructionsFilePath", v || undefined)
-          }
-          immediate
-          className={inputClass}
-          placeholder="/absolute/path/to/AGENTS.md"
-        />
-        <ChoosePathButton />
-      </div>
-    </Field>
-  );
-}

ui/src/adapters/hermes-local/index.ts

@@ -1,12 +0,0 @@
-import type { UIAdapterModule } from "../types";
-import { parseHermesStdoutLine } from "hermes-paperclip-adapter/ui";
-import { HermesLocalConfigFields } from "./config-fields";
-import { buildHermesConfig } from "hermes-paperclip-adapter/ui";
-
-export const hermesLocalUIAdapter: UIAdapterModule = {
-  type: "hermes_local",
-  label: "Hermes Agent",
-  parseStdoutLine: parseHermesStdoutLine,
-  ConfigFields: HermesLocalConfigFields,
-  buildAdapterConfig: buildHermesConfig,
-};

ui/src/adapters/index.ts

@@ -1,4 +1,11 @@
-export { getUIAdapter, listUIAdapters } from "./registry";
+export {
+  getUIAdapter,
+  listUIAdapters,
+  findUIAdapter,
+  registerUIAdapter,
+  unregisterUIAdapter,
+  syncExternalAdapters,
+} from "./registry";
 export { buildTranscript } from "./transcript";
 export type {
   TranscriptEntry,

ui/src/adapters/metadata.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { isEnabledAdapterType, listAdapterOptions } from "./metadata";
+import type { UIAdapterModule } from "./types";
+
+const externalAdapter: UIAdapterModule = {
+  type: "external_test",
+  label: "External Test",
+  parseStdoutLine: () => [],
+  ConfigFields: () => null,
+  buildAdapterConfig: () => ({}),
+};
+
+describe("adapter metadata", () => {
+  it("treats registered external adapters as enabled by default", () => {
+    expect(isEnabledAdapterType("external_test")).toBe(true);
+
+    expect(
+      listAdapterOptions((type) => type, [externalAdapter]),
+    ).toEqual([
+      {
+        value: "external_test",
+        label: "external_test",
+        comingSoon: false,
+        hidden: false,
+      },
+    ]);
+  });
+
+  it("keeps intentionally withheld built-in adapters marked as coming soon", () => {
+    expect(isEnabledAdapterType("process")).toBe(false);
+    expect(isEnabledAdapterType("http")).toBe(false);
+  });
+});

ui/src/adapters/metadata.ts

@@ -0,0 +1,61 @@
+/**
+ * Adapter metadata utilities — built on top of the display registry and UI adapter list.
+ *
+ * This module bridges the static display metadata with the dynamic adapter registry.
+ * "Coming soon" status is derived from the display registry's `comingSoon` flag.
+ * "Hidden" status comes from the disabled-adapter store (server-side toggle).
+ */
+import type { UIAdapterModule } from "./types";
+import { listUIAdapters } from "./registry";
+import { isAdapterTypeHidden } from "./disabled-store";
+import { getAdapterLabel, getAdapterDisplay } from "./adapter-display-registry";
+
+export interface AdapterOptionMetadata {
+  value: string;
+  label: string;
+  comingSoon: boolean;
+  hidden: boolean;
+}
+
+export function listKnownAdapterTypes(): string[] {
+  return listUIAdapters().map((adapter) => adapter.type);
+}
+
+/**
+ * Check whether an adapter type is enabled (not "coming soon").
+ * Unknown types (external adapters) are always considered enabled.
+ */
+export function isEnabledAdapterType(type: string): boolean {
+  return !getAdapterDisplay(type).comingSoon;
+}
+
+/**
+ * Build option metadata for a list of adapters (for dropdowns).
+ * `labelFor` callback allows callers to override labels; defaults to display registry.
+ */
+export function listAdapterOptions(
+  labelFor?: (type: string) => string,
+  adapters: UIAdapterModule[] = listUIAdapters(),
+): AdapterOptionMetadata[] {
+  const getLabel = labelFor ?? getAdapterLabel;
+  return adapters.map((adapter) => ({
+    value: adapter.type,
+    label: getLabel(adapter.type),
+    comingSoon: !!getAdapterDisplay(adapter.type).comingSoon,
+    hidden: isAdapterTypeHidden(adapter.type),
+  }));
+}
+
+/**
+ * List UI adapters excluding those hidden via the Adapters settings page.
+ */
+export function listVisibleUIAdapters(): UIAdapterModule[] {
+  return listUIAdapters().filter((a) => !isAdapterTypeHidden(a.type));
+}
+
+/**
+ * List visible adapter types (for non-React contexts like module-level constants).
+ */
+export function listVisibleAdapterTypes(): string[] {
+  return listVisibleUIAdapters().map((a) => a.type);
+}

ui/src/adapters/registry.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import type { UIAdapterModule } from "./types";
+import {
+  findUIAdapter,
+  getUIAdapter,
+  listUIAdapters,
+  registerUIAdapter,
+  unregisterUIAdapter,
+} from "./registry";
+import { processUIAdapter } from "./process";
+
+const externalUIAdapter: UIAdapterModule = {
+  type: "external_test",
+  label: "External Test",
+  parseStdoutLine: () => [],
+  ConfigFields: () => null,
+  buildAdapterConfig: () => ({}),
+};
+
+describe("ui adapter registry", () => {
+  beforeEach(() => {
+    unregisterUIAdapter("external_test");
+  });
+
+  afterEach(() => {
+    unregisterUIAdapter("external_test");
+  });
+
+  it("registers adapters for lookup and listing", () => {
+    registerUIAdapter(externalUIAdapter);
+
+    expect(findUIAdapter("external_test")).toBe(externalUIAdapter);
+    expect(getUIAdapter("external_test")).toBe(externalUIAdapter);
+    expect(listUIAdapters().some((adapter) => adapter.type === "external_test")).toBe(true);
+  });
+
+  it("falls back to the process parser for unknown types after unregistering", () => {
+    registerUIAdapter(externalUIAdapter);
+
+    unregisterUIAdapter("external_test");
+
+    expect(findUIAdapter("external_test")).toBeNull();
+    const fallback = getUIAdapter("external_test");
+    // Unknown types return a lazy-loading wrapper (for external adapters),
+    // not the process adapter directly. The type is preserved.
+    expect(fallback.type).toBe("external_test");
+    // But it uses the process parser under the hood.
+    expect(fallback.ConfigFields).toBe(processUIAdapter.ConfigFields);
+  });
+});

ui/src/adapters/registry.ts

@@ -3,32 +3,130 @@ import { claudeLocalUIAdapter } from "./claude-local";
 import { codexLocalUIAdapter } from "./codex-local";
 import { cursorLocalUIAdapter } from "./cursor";
 import { geminiLocalUIAdapter } from "./gemini-local";
-import { hermesLocalUIAdapter } from "./hermes-local";
 import { openCodeLocalUIAdapter } from "./opencode-local";
 import { piLocalUIAdapter } from "./pi-local";
 import { openClawGatewayUIAdapter } from "./openclaw-gateway";
 import { processUIAdapter } from "./process";
 import { httpUIAdapter } from "./http";
+import { loadDynamicParser } from "./dynamic-loader";
 
-const uiAdapters: UIAdapterModule[] = [
-  claudeLocalUIAdapter,
-  codexLocalUIAdapter,
-  geminiLocalUIAdapter,
-  hermesLocalUIAdapter,
-  openCodeLocalUIAdapter,
-  piLocalUIAdapter,
-  cursorLocalUIAdapter,
-  openClawGatewayUIAdapter,
-  processUIAdapter,
-  httpUIAdapter,
-];
+const uiAdapters: UIAdapterModule[] = [];
+const adaptersByType = new Map<string, UIAdapterModule>();
 
-const adaptersByType = new Map<string, UIAdapterModule>(
-  uiAdapters.map((a) => [a.type, a]),
-);
+function registerBuiltInUIAdapters() {
+  for (const adapter of [
+    claudeLocalUIAdapter,
+    codexLocalUIAdapter,
+    geminiLocalUIAdapter,
+    openCodeLocalUIAdapter,
+    piLocalUIAdapter,
+    cursorLocalUIAdapter,
+    openClawGatewayUIAdapter,
+    processUIAdapter,
+    httpUIAdapter,
+  ]) {
+    registerUIAdapter(adapter);
+  }
+}
+
+export function registerUIAdapter(adapter: UIAdapterModule): void {
+  const existingIndex = uiAdapters.findIndex((entry) => entry.type === adapter.type);
+  if (existingIndex >= 0) {
+    uiAdapters.splice(existingIndex, 1, adapter);
+  } else {
+    uiAdapters.push(adapter);
+  }
+  adaptersByType.set(adapter.type, adapter);
+}
+
+export function unregisterUIAdapter(type: string): void {
+  if (type === processUIAdapter.type || type === httpUIAdapter.type) return;
+  const existingIndex = uiAdapters.findIndex((entry) => entry.type === type);
+  if (existingIndex >= 0) {
+    uiAdapters.splice(existingIndex, 1);
+  }
+  adaptersByType.delete(type);
+}
+
+export function findUIAdapter(type: string): UIAdapterModule | null {
+  return adaptersByType.get(type) ?? null;
+}
+
+registerBuiltInUIAdapters();
 
 export function getUIAdapter(type: string): UIAdapterModule {
-  return adaptersByType.get(type) ?? processUIAdapter;
+  const builtIn = adaptersByType.get(type);
+
+  if (!builtIn) {
+    // No built-in adapter — fall through to the external-only path.
+    let loadStarted = false;
+    return {
+      type,
+      label: type,
+      parseStdoutLine: (line: string, ts: string) => {
+        if (!loadStarted) {
+          loadStarted = true;
+          loadDynamicParser(type).then((parser) => {
+            if (parser) {
+              registerUIAdapter({
+                type,
+                label: type,
+                parseStdoutLine: parser,
+                ConfigFields: processUIAdapter.ConfigFields,
+                buildAdapterConfig: processUIAdapter.buildAdapterConfig,
+              });
+            }
+          });
+        }
+        return processUIAdapter.parseStdoutLine(line, ts);
+      },
+      ConfigFields: processUIAdapter.ConfigFields,
+      buildAdapterConfig: processUIAdapter.buildAdapterConfig,
+    };
+  }
+
+  return builtIn;
+}
+
+/**
+ * Ensure external adapter types (from the server's /api/adapters response)
+ * are registered in the UI adapter list so they appear in dropdowns.
+ *
+ * For each type not already registered, creates a placeholder module that
+ * uses the process adapter defaults and kicks off dynamic parser loading.
+ * Once the parser resolves, the placeholder is replaced with the real one.
+ */
+export function syncExternalAdapters(
+  serverAdapters: { type: string; label: string }[],
+): void {
+  for (const { type, label } of serverAdapters) {
+    if (adaptersByType.has(type)) continue;
+
+    let loadStarted = false;
+    registerUIAdapter({
+      type,
+      label,
+      parseStdoutLine: (line: string, ts: string) => {
+        if (!loadStarted) {
+          loadStarted = true;
+          loadDynamicParser(type).then((parser) => {
+            if (parser) {
+              registerUIAdapter({
+                type,
+                label,
+                parseStdoutLine: parser,
+                ConfigFields: processUIAdapter.ConfigFields,
+                buildAdapterConfig: processUIAdapter.buildAdapterConfig,
+              });
+            }
+          });
+        }
+        return processUIAdapter.parseStdoutLine(line, ts);
+      },
+      ConfigFields: processUIAdapter.ConfigFields,
+      buildAdapterConfig: processUIAdapter.buildAdapterConfig,
+    });
+  }
 }
 
 export function listUIAdapters(): UIAdapterModule[] {

ui/src/adapters/use-disabled-adapters.ts

@@ -0,0 +1,49 @@
+import { useEffect, useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { adaptersApi } from "@/api/adapters";
+import { setDisabledAdapterTypes } from "@/adapters/disabled-store";
+import { syncExternalAdapters } from "@/adapters/registry";
+import { queryKeys } from "@/lib/queryKeys";
+
+/**
+ * Fetch adapters and keep the disabled-adapter store + UI adapter registry
+ * in sync with the server.
+ *
+ * - Registers external adapter types in the UI registry so they appear in
+ *   dropdowns (done eagerly during render — idempotent, no React state).
+ * - Syncs the disabled-adapter store for non-React consumers (useEffect).
+ *
+ * Returns a reactive Set of disabled types for use as useMemo dependencies.
+ * Call this at the top of any component that renders adapter menus.
+ */
+export function useDisabledAdaptersSync(): Set<string> {
+  const { data: adapters } = useQuery({
+    queryKey: queryKeys.adapters.all,
+    queryFn: () => adaptersApi.list(),
+    staleTime: 5 * 60 * 1000,
+  });
+
+  // Eagerly register external adapter types in the UI registry so that
+  // consumers calling listUIAdapters() in the same render cycle see them.
+  // This is idempotent — already-registered types are skipped.
+  if (adapters) {
+    syncExternalAdapters(
+      adapters
+        .filter((a) => a.source === "external")
+        .map((a) => ({ type: a.type, label: a.label })),
+    );
+  }
+
+  // Sync the disabled set to the global store for non-React code
+  useEffect(() => {
+    if (!adapters) return;
+    setDisabledAdapterTypes(
+      adapters.filter((a) => a.disabled).map((a) => a.type),
+    );
+  }, [adapters]);
+
+  return useMemo(
+    () => new Set(adapters?.filter((a) => a.disabled).map((a) => a.type) ?? []),
+    [adapters],
+  );
+}