PaperClipAI/server/src/adapters/registry.ts

import { pluginRunnerAiConnectionRequiredTestResult } from "../services/plugin-runner-ai-connection.js";
import { HttpError } from "../errors.js";
import type { AdapterRuntimeCommandSpec, ServerAdapterModule } from "./types.js";
import { parseAdapterModelsEnv } from "../services/adapter-models-env.js";
import { validateAiApiKey } from "../services/ai-api-key-test.js";
import type { AdapterEnvironmentTestResult } from "@paperclipai/shared";
import { stampClaudeAgentIdHeader } from "./claude-agent-id-header.js";
import {
  buildSandboxNpmInstallCommand,
  getAdapterSessionManagement,
  PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES,
  PAPERCLIP_RUNNER_ACPX_PROFILES,
} from "@paperclipai/adapter-utils";
import type { AdapterLoginCapability } from "@paperclipai/adapter-utils";
import { runAdapterExecutionTargetShellCommand } from "@paperclipai/adapter-utils/execution-target";
import {
  execute as claudeExecute,
  listClaudeSkills,
  syncClaudeSkills,
  listClaudeModels,
  refreshClaudeModels,
  testEnvironment as claudeTestEnvironment,
  sessionCodec as claudeSessionCodec,
  getQuotaWindows as claudeGetQuotaWindows,
  getConfigSchema as getClaudeConfigSchema,
  CLAUDE_SETUP_TOKEN_COMMAND,
  parseSetupTokenPrompt,
  parseSetupTokenCredential,
} from "@paperclipai/adapter-claude-local/server";
import {
  agentConfigurationDoc as claudeAgentConfigurationDoc,
  models as claudeModels,
} from "@paperclipai/adapter-claude-local";
import {
  execute as codexExecute,
  listCodexSkills,
  syncCodexSkills,
  testEnvironment as codexTestEnvironment,
  sessionCodec as codexSessionCodec,
  getQuotaWindows as codexGetQuotaWindows,
  getConfigSchema as getCodexConfigSchema,
  CODEX_DEVICE_LOGIN_COMMAND,
  parseDeviceLoginPrompt,
} from "@paperclipai/adapter-codex-local/server";
import {
  agentConfigurationDoc as codexAgentConfigurationDoc,
  models as codexModels,
} from "@paperclipai/adapter-codex-local";
import {
  execute as cursorExecute,
  listCursorSkills,
  syncCursorSkills,
  testEnvironment as cursorTestEnvironment,
  sessionCodec as cursorSessionCodec,
} from "@paperclipai/adapter-cursor-local/server";
import {
  agentConfigurationDoc as cursorAgentConfigurationDoc,
  models as cursorModels,
} from "@paperclipai/adapter-cursor-local";
import {
  execute as cursorCloudExecute,
  getConfigSchema as getCursorCloudConfigSchema,
  sessionCodec as cursorCloudSessionCodec,
  testEnvironment as cursorCloudTestEnvironment,
} from "@paperclipai/adapter-cursor-cloud/server";
import { agentConfigurationDoc as cursorCloudAgentConfigurationDoc } from "@paperclipai/adapter-cursor-cloud";
import {
  execute as geminiExecute,
  listGeminiSkills,
  syncGeminiSkills,
  testEnvironment as geminiTestEnvironment,
  sessionCodec as geminiSessionCodec,
  getConfigSchema as getGeminiConfigSchema,
} from "@paperclipai/adapter-gemini-local/server";
import {
  agentConfigurationDoc as geminiAgentConfigurationDoc,
  models as geminiModels,
} from "@paperclipai/adapter-gemini-local";
import {
  execute as grokExecute,
  listGrokSkills,
  syncGrokSkills,
  testEnvironment as grokTestEnvironment,
  sessionCodec as grokSessionCodec,
  GROK_DEVICE_LOGIN_COMMAND,
  parseGrokDeviceLoginPrompt,
} from "@paperclipai/adapter-grok-local/server";
import {
  agentConfigurationDoc as grokAgentConfigurationDoc,
  models as grokModels,
} from "@paperclipai/adapter-grok-local";
import {
  execute as kimiExecute,
  listKimiSkills,
  syncKimiSkills,
  testEnvironment as kimiTestEnvironment,
  sessionCodec as kimiSessionCodec,
} from "@paperclipai/adapter-kimi-local/server";
import {
  agentConfigurationDoc as kimiAgentConfigurationDoc,
  models as kimiModels,
} from "@paperclipai/adapter-kimi-local";
import {
  createHermesGatewayServerAdapter,
  createHermesLocalServerAdapter,
} from "@paperclipai/hermes-paperclip-adapter";
import {
  execute as openCodeExecute,
  listOpenCodeSkills,
  syncOpenCodeSkills,
  testEnvironment as openCodeTestEnvironment,
  sessionCodec as openCodeSessionCodec,
  listOpenCodeModels,
} from "@paperclipai/adapter-opencode-local/server";
import {
  agentConfigurationDoc as openCodeAgentConfigurationDoc,
  models as openCodeModels,
} from "@paperclipai/adapter-opencode-local";
import {
  execute as openclawGatewayExecute,
  testEnvironment as openclawGatewayTestEnvironment,
} from "@paperclipai/adapter-openclaw-gateway/server";
import {
  agentConfigurationDoc as openclawGatewayAgentConfigurationDoc,
  models as openclawGatewayModels,
} from "@paperclipai/adapter-openclaw-gateway";
import { listCodexModels, refreshCodexModels } from "./codex-models.js";
import { listCursorModels } from "./cursor-models.js";
import {
  execute as piExecute,
  listPiSkills,
  syncPiSkills,
  testEnvironment as piTestEnvironment,
  sessionCodec as piSessionCodec,
  listPiModels,
} from "@paperclipai/adapter-pi-local/server";
import { agentConfigurationDoc as piAgentConfigurationDoc } from "@paperclipai/adapter-pi-local";
import { BUILTIN_ADAPTER_TYPES } from "./builtin-adapter-types.js";
import { buildExternalAdapters } from "./plugin-loader.js";
import { isCloudManagedInstance } from "../services/cloud-instance.js";
import { assertExternalAdapterCodeAllowed } from "../services/adapter-code-policy.js";
import { NativeEnvironmentProbeCleanupError } from "../vendor/paperclip-runner/index.js";
import { processAdapter } from "./process/index.js";
import { httpAdapter } from "./http/index.js";
import {
  DEFAULT_OPENCODE_RUNNER_MODEL,
  PaperclipRunnerProviderProfileError,
  DEFAULT_ACPX_RUNNER_MODELS,
  QUALIFIED_OPENCODE_RUNNER_VERSION,
  resolvePaperclipRunnerProviderProfile,
} from "../services/native-runtime/provider-profile.js";

async function verifyNativeAcpxApiKey(
  config: Record<string, unknown>,
  result: AdapterEnvironmentTestResult,
): Promise<AdapterEnvironmentTestResult> {
  const env = config.env as Record<string, unknown> | undefined;
  const account = config.acpxAgent === "claude" ? { provider: "anthropic" as const, name: "Anthropic", key: "ANTHROPIC_API_KEY",
    routing: ["ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"] }
    : config.acpxAgent === "grok" ? { provider: "xai" as const, name: "xAI", key: "XAI_API_KEY", routing: ["XAI_BASE_URL", "GROK_BASE_URL"] } : null;
  if (!account || !env || typeof env[account.key] !== "string" || !env[account.key]
    || config.managedAiRouting || config.managedAiConnection || account.routing.some(key => env[key])) return result;
  try {
    await validateAiApiKey(account.provider, env[account.key] as string);
    return { ...result, checks: [...result.checks, {
      code: "ai_connection_api_key_reverified", level: "info",
      message: `${account.name} verified this API key. Model access is checked when the agent runs.`,
    }] };
  } catch (error) {
    const details = error && typeof error === "object" && "details" in error
      ? error.details as { code?: string } | undefined : undefined;
    return { ...result, status: "fail", checks: [...result.checks, {
      code: details?.code === "ai_connection_api_key_rejected" ? details.code : "ai_connection_verification_failed",
      level: "error", message: `Could not verify the ${account.name} API key. Check the connection and try again.`,
    }] };
  }
}

function readConfiguredCommand(config: Record<string, unknown>, fallback: string): string {
  const value = typeof config.command === "string" ? config.command.trim() : "";
  return value.length > 0 ? value : fallback;
}

function hasPathSeparator(command: string): boolean {
  return command.includes("/") || command.includes("\\");
}

function shellQuote(value: string): string {
  return `'${value.replace(/'/g, `'"'"'`)}'`;
}

function buildNpmRuntimeCommandSpec(
  config: Record<string, unknown>,
  fallbackCommand: string,
  packageName: string,
): AdapterRuntimeCommandSpec {
  const command = readConfiguredCommand(config, fallbackCommand);
  const canSelfInstall = !hasPathSeparator(command) && command === fallbackCommand;
  const installLine = buildSandboxNpmInstallCommand(packageName);
  return {
    command,
    detectCommand: command,
    installCommand: canSelfInstall
      ? `if ! command -v ${shellQuote(command)} >/dev/null 2>&1; then ${installLine}; fi`
      : null,
  };
}

function buildCursorRuntimeCommandSpec(config: Record<string, unknown>): AdapterRuntimeCommandSpec {
  const command = readConfiguredCommand(config, "agent");
  return {
    command,
    detectCommand: command,
    installCommand: null,
  };
}

const retiredAcpxMessage =
  "The acpx_local adapter has been retired. Existing Claude and Codex ACPX agents should be migrated to claude_local or codex_local with adapterConfig.engine=\"acp\".";

const retiredAcpxAgentConfigurationDoc = `# acpx_local retired

Adapter: acpx_local

The standalone ACPX adapter has been retired. Use:

- claude_local with adapterConfig.engine="acp" for Claude ACP execution.
- codex_local with adapterConfig.engine="acp" for Codex ACP execution.

Paperclip keeps this tombstone registered so stale acpx_local rows fail clearly instead of falling back to the process adapter.
`;

// The Claude interactive login capability. Claude runs `claude setup-token` on a
// real pseudo-terminal. The user pastes a browser code back into the flow. The
// flow uses a fixed host-side timeout and records a stored session identifier on
// success. The capability data holds no secret; the callbacks return runtime
// values only.
const claudeLoginCapability: AdapterLoginCapability = {
  panelMode: "submitted_browser_code",
  timeoutPolicy: "fixed",
  getCommand: () => CLAUDE_SETUP_TOKEN_COMMAND,
  parsePrompt: (output) => {
    const prompt = parseSetupTokenPrompt(output);
    return prompt ? { url: prompt.url } : null;
  },
  captureCredential: (output) => {
    const token = parseSetupTokenCredential(output);
    return token === null ? null : Buffer.from(token, "utf8");
  },
  completionClaim: "storedSessionId",
};

// The Codex interactive login capability. Codex runs `codex login --device-auth`
// on a real pseudo-terminal, because a pipe emits no login prompt. The flow shows
// a one-time code that the user enters in the browser. The caller sets the
// host-side timeout. The device-login flow writes its credential inside the
// sandbox, so the capability declares no terminal credential capture and no
// completion claim.
const codexLoginCapability: AdapterLoginCapability = {
  panelMode: "displayed_code",
  timeoutPolicy: "caller_bounded",
  getCommand: () => CODEX_DEVICE_LOGIN_COMMAND,
  parsePrompt: (output) => {
    const prompt = parseDeviceLoginPrompt(output);
    return prompt ? { url: prompt.url, code: prompt.code } : null;
  },
};

// The Grok interactive login capability. Grok runs `grok login --device-auth`
// on a real pseudo-terminal, the same way Codex does. The flow shows a
// one-time code that the user enters in the browser. The caller sets the
// host-side timeout. The device-login flow writes its credential inside the
// sandbox, so the capability declares no terminal credential capture and no
// completion claim. `getCommand` is descriptive only: the login path selects
// the real command from the closed key map in `login-command.ts`, never from
// this member.
const grokLoginCapability: AdapterLoginCapability = {
  panelMode: "displayed_code",
  timeoutPolicy: "caller_bounded",
  getCommand: () => GROK_DEVICE_LOGIN_COMMAND,
  parsePrompt: (output) => {
    const prompt = parseGrokDeviceLoginPrompt(output);
    return prompt ? { url: prompt.url, code: prompt.code } : null;
  },
};

const claudeLocalAdapter: ServerAdapterModule = {
  type: "claude_local",
  runtimeToolDelivery: "native_mcp",
  execute: stampClaudeAgentIdHeader(claudeExecute),
  testEnvironment: claudeTestEnvironment,
  acp: {
    agentId: "claude",
    skillsMode: "ephemeral",
    prerequisites: {
      nodeRange: ">=24.11.0",
      packages: ["@agentclientprotocol/claude-agent-acp"],
    },
  },
  listSkills: listClaudeSkills,
  syncSkills: syncClaudeSkills,
  sessionCodec: claudeSessionCodec,
  sessionManagement: getAdapterSessionManagement("claude_local") ?? undefined,
  supportsToolRefreshOnResume: true,
  models: claudeModels,
  listModels: listClaudeModels,
  refreshModels: refreshClaudeModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: false,
  getRuntimeCommandSpec: (config) =>
    buildNpmRuntimeCommandSpec(config, "claude", "@anthropic-ai/claude-code"),
  agentConfigurationDoc: claudeAgentConfigurationDoc,
  getConfigSchema: getClaudeConfigSchema,
  getQuotaWindows: claudeGetQuotaWindows,
  loginCapability: claudeLoginCapability,
};

const acpxLocalAdapter: ServerAdapterModule = {
  type: "acpx_local",
  runtimeToolDelivery: "environment",
  async execute(ctx) {
    await ctx.onLog("stderr", `${retiredAcpxMessage}\n`);
    await ctx.onMeta?.({
      adapterType: "acpx_local",
      command: "acpx_local-retired",
      commandNotes: [retiredAcpxMessage],
    });
    return {
      exitCode: 1,
      signal: null,
      timedOut: false,
      errorMessage: retiredAcpxMessage,
      errorCode: "acpx_local_retired",
      provider: "acpx",
      summary: retiredAcpxMessage,
    };
  },
  async testEnvironment() {
    return {
      adapterType: "acpx_local",
      status: "fail",
      testedAt: new Date().toISOString(),
      checks: [
        {
          code: "acpx_local_retired",
          level: "error",
          message: retiredAcpxMessage,
          hint: "Set the agent adapter to claude_local or codex_local and set adapterConfig.engine to acp.",
        },
      ],
    };
  },
  models: [],
  supportsLocalAgentJwt: false,
  supportsInstructionsBundle: false,
  requiresMaterializedRuntimeSkills: false,
  agentConfigurationDoc: retiredAcpxAgentConfigurationDoc,
  getConfigSchema: () => ({ fields: [] }),
};

const codexLocalAdapter: ServerAdapterModule = {
  type: "codex_local",
  runtimeToolDelivery: "native_mcp",
  execute: codexExecute,
  testEnvironment: codexTestEnvironment,
  acp: {
    agentId: "codex",
    skillsMode: "ephemeral",
    prerequisites: {
      nodeRange: ">=24.11.0",
      packages: ["@agentclientprotocol/codex-acp"],
    },
  },
  listSkills: listCodexSkills,
  syncSkills: syncCodexSkills,
  sessionCodec: codexSessionCodec,
  sessionManagement: getAdapterSessionManagement("codex_local") ?? undefined,
  supportsToolRefreshOnResume: true,
  models: codexModels,
  listModels: listCodexModels,
  refreshModels: refreshCodexModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: false,
  getRuntimeCommandSpec: (config) => buildNpmRuntimeCommandSpec(config, "codex", "@openai/codex"),
  agentConfigurationDoc: codexAgentConfigurationDoc,
  getConfigSchema: getCodexConfigSchema,
  getQuotaWindows: codexGetQuotaWindows,
  loginCapability: codexLoginCapability,
};

const paperclipRunnerAdapter: ServerAdapterModule = {
  type: "paperclip_runner",
  runtimeToolDelivery: "environment",
  async execute(ctx) {
    const message = "paperclip_runner requires the native runner coordinator";
    await ctx.onLog("stderr", `${message}\n`);
    return {
      exitCode: 1,
      signal: null,
      timedOut: false,
      errorMessage: message,
      errorCode: "paperclip_runner_coordinator_required",
      provider: ctx.config.provider === "opencode"
        ? "opencode"
        : ctx.config.provider === "claude_managed"
          ? "anthropic"
          : ctx.config.provider === "aws_agentcore"
            ? "amazon-bedrock"
        : ctx.config.provider === "acpx"
            ? "acpx"
            : ctx.config.provider === "cursor_cloud" ? "cursor"
            : "codex",
      summary: message,
    };
  },
  async testEnvironment(context) {
    let profile: ReturnType<typeof resolvePaperclipRunnerProviderProfile>;
    try {
      profile = resolvePaperclipRunnerProviderProfile(context.config, { companyId: context.companyId });
    } catch (error) {
      const profileError = error instanceof PaperclipRunnerProviderProfileError
        ? error
        : new PaperclipRunnerProviderProfileError(
            "paperclip_runner_provider_unsupported",
            "Paperclip Runner provider configuration is invalid.",
          );
      return {
        adapterType: "paperclip_runner",
        status: "fail" as const,
        testedAt: new Date().toISOString(),
        checks: [{
          code: profileError.code,
          level: "error" as const,
          message: profileError.message,
        }],
      };
    }
    if (profile.provider !== "cursor_cloud" && context.executionTarget?.kind === "remote" && context.executionTarget.transport === "sandbox" && context.executionTarget.runnerTask) {
      // Managed connections probe through testManagedEnvironment. This path has
      // none, which a plugin Runner-task environment never runs.
      return pluginRunnerAiConnectionRequiredTestResult("paperclip_runner");
    }
    if (profile.provider === "cursor_cloud") {
      const failure = (code: string, message: string) => ({ adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(), checks: [{ code, level: "error" as const, message }] });
      if (context.executionTarget?.kind === "remote") return failure("cursor_cloud_local_controller_required", "Select a local Paperclip controller. Cursor hosts the execution environment.");
      const configuredEnv = context.config.env;
      const binding = configuredEnv && typeof configuredEnv === "object" && !Array.isArray(configuredEnv)
        ? (configuredEnv as Record<string, unknown>).CURSOR_API_KEY : undefined;
      const apiKey = typeof binding === "string" ? binding : binding && typeof binding === "object" && "type" in binding && binding.type === "plain" && "value" in binding && typeof binding.value === "string" ? binding.value : "";
      if (!apiKey.trim()) return failure("cursor_cloud_api_key_missing", "Bind a Cursor Cloud API key to CURSOR_API_KEY before testing.");
      try {
        const { remoteMcpRelayUrl } = await import("../services/native-runtime/remote-mcp-relay.js");
        const { resolveCursorCloudPublicOrigin } = await import("../services/native-runtime/cursor-cloud-runtime.js");
        const url = remoteMcpRelayUrl(resolveCursorCloudPublicOrigin() ?? "", "00000000-0000-4000-8000-000000000000");
        const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}", redirect: "error", signal: AbortSignal.timeout(5_000) });
        await response.body?.cancel();
        if (response.status !== 401) throw new Error("relay_unavailable");
      } catch {
        return failure("cursor_cloud_public_relay_unavailable", "Configure PAPERCLIP_PUBLIC_URL as a reachable HTTPS origin for /mcp/native-runs/. The callback must reject unauthenticated requests with HTTP 401. Expose only this callback path through the public proxy.");
      }
      try {
        const { CursorCloudClient } = await import("../vendor/paperclip-runner/index.js");
        const { items } = await new CursorCloudClient({ apiKey }).listModels();
        const listed = items.some(item => item.id === profile.model || item.aliases?.includes(profile.model));
        return { adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(), checks: [
          { code: "cursor_cloud_account_ready", level: "info" as const, message: "The bound Cursor Cloud API key can read its model catalog. No prompt was sent." },
          { code: listed ? "cursor_cloud_model_listed" : "cursor_cloud_model_unlisted", level: listed ? "info" as const : "warn" as const,
            message: listed ? "The selected model appears in this account's catalog." : "The selected model is absent from the recommended catalog. Cursor will decide whether this exact model is available when it runs." },
          { code: "cursor_cloud_model_identity_unverified", level: "warn" as const, message: "This experimental integration forwards the selected model; Cursor does not acknowledge the effective model. Cloud commands use Cursor-managed permissions." },
        ] };
      } catch { return failure("cursor_cloud_account_unavailable", "Cursor Cloud could not validate the bound key. Check its Cloud Agents access and retry."); }
    }
    if (profile.provider === "muse") {
      return { adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
        checks: [{ code: "muse_background_test_required", level: "warn" as const, message: "Muse manages its model and billing. Verify the paired receiver and independent background reply in Paperclip; this read-only check does not wake Muse." }] };
    }
    if (profile.provider === "openai_dot") {
      return { adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
        checks: [{ code: "dot_event_test_required", level: "warn" as const, message: "Dot manages its model and billing. Validate the dedicated agent binding and event round trip in Paperclip; this read-only check does not wake the Dot." }] };
    }
    if (profile.provider === "acpx") {
      try {
        if (profile.acpxAgent === "antigravity") {
          const { testAntigravityConnection } = await import("../services/antigravity-connection-probe.js");
          return await testAntigravityConnection(context, profile.model);
        }
        if (profile.acpxAgent === "copilot") {
          const configured = context.config.env;
          const token = configured && typeof configured === "object" && !Array.isArray(configured)
            ? (configured as Record<string, unknown>).COPILOT_GITHUB_TOKEN : undefined;
          if (typeof token !== "string" || !token) {
            return { adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
              checks: [{ code: "COPILOT_AUTH_REQUIRED", level: "error" as const, message: "Select a saved Copilot token connection." }] };
          }
          const { probeCopilotExecutionTarget } = await import("../services/copilot-connection-probe.js");
          await probeCopilotExecutionTarget(token, context.executionTarget, profile.model);
          return { adapterType: "paperclip_runner", status: "pass" as const, testedAt: new Date().toISOString(),
            checks: [{ code: "copilot_metadata_verified", level: "info" as const,
              message: "The verified Copilot runtime authenticated this account and accepted the selected model. No model prompt was sent." }] };
        }
        if (profile.acpxAgent !== "claude" && profile.acpxAgent !== "grok" && profile.acpxAgent !== "cursor" && profile.acpxAgent !== "pi" && profile.acpxAgent !== "kimi") throw new Error("Select Codex to use the native Codex runner.");
        if (profile.acpxAgent === "kimi") {
          const environment = context.config.env as Record<string, unknown> | undefined;
          if (typeof environment?.KIMI_API_KEY !== "string" || !environment.KIMI_API_KEY.trim()) {
            return { adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
              checks: [{ code: "KIMI_AUTH_REQUIRED", level: "error" as const, message: "Bind a company secret to KIMI_API_KEY in the agent environment." }] };
          }
        }
        const target = context.executionTarget;
        if (profile.acpxAgent === "kimi") {
          const { probeKimiExecutionTarget } = await import("../services/kimi-connection-probe.js");
          await probeKimiExecutionTarget((context.config.env as Record<string, string>).KIMI_API_KEY, target, profile.model, { companyId: context.companyId });
          return { adapterType: "paperclip_runner", status: "pass" as const, testedAt: new Date().toISOString(),
            checks: [{ code: "kimi_metadata_verified", level: "info" as const,
              message: "The selected environment verified the pinned Kimi Code runtime. Its Code model catalog accepted the credential and lists the exact selected model. No model prompt was sent." }] };
        }
        if (target?.kind === "remote") {
          const probe = await runAdapterExecutionTargetShellCommand(
            `acpx-platform-${crypto.randomUUID()}`, target, "uname -s && uname -m",
            { cwd: target.remoteCwd, env: {}, timeoutSec: 15 },
          );
          if (probe.timedOut || probe.exitCode !== 0) throw new Error("Could not verify the remote ACPX runner platform.");
          const [os, arch] = probe.stdout.trim().split(/\s+/);
          if (!((os === "Linux" && (arch === "x86_64" || (profile.acpxAgent === "claude" && ["aarch64", "arm64"].includes(arch)))) || (os === "Darwin" && (arch === "arm64" || (!["grok"].includes(profile.acpxAgent) && arch === "x86_64"))))) {
            throw new Error(`ACPX ${profile.acpxAgent} requires a qualified Linux ${profile.acpxAgent === "claude" ? "x64/ARM64" : "x64"} or macOS architecture.`);
          }
          return verifyNativeAcpxApiKey(context.config, {
            adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
            checks: [{ code: "acpx_remote_runtime_unverified", level: "warn" as const,
              message: "The remote platform is supported. Runtime package integrity and readiness must still be verified by the remote runner before launch." }],
          });
        }
        const { probeAcpxClaudeInstallation, probeAcpxGrokInstallation, probeAcpxCursorInstallation, probeAcpxPiInstallation } = await import("../vendor/paperclip-runner/live/index.js");
        await (profile.acpxAgent === "pi" ? probeAcpxPiInstallation : profile.acpxAgent === "grok" ? probeAcpxGrokInstallation : profile.acpxAgent === "cursor" ? probeAcpxCursorInstallation : probeAcpxClaudeInstallation)(profile.model);
        return verifyNativeAcpxApiKey(context.config, {
          adapterType: "paperclip_runner", status: "pass" as const, testedAt: new Date().toISOString(),
          checks: [{ code: "acpx_runtime_ready", level: "info" as const, message: `ACPX ${profile.acpxAgent} runtime is installed and verified. Model access is checked when it runs.` }],
        });
      } catch (error) {
        // The selected managed credential home must outlive an uncertain
        // native retirement. Its caller retains writeback until proof arrives.
        if (error instanceof NativeEnvironmentProbeCleanupError) throw error;
        if (profile.acpxAgent === "antigravity") {
          const { antigravityConnectionProbeFailure } = await import("../services/antigravity-connection-probe.js");
          return antigravityConnectionProbeFailure(context.companyId, error);
        }
        if (profile.acpxAgent === "copilot") {
          const details = error instanceof HttpError && error.details && typeof error.details === "object" && !Array.isArray(error.details)
            ? error.details as Record<string, unknown> : {};
          const codes = ["COPILOT_AUTH_REQUIRED", "COPILOT_ENTITLEMENT_DENIED", "COPILOT_MODEL_UNAVAILABLE", "COPILOT_INSTALLATION_INVALID", "COPILOT_REQUEST_FAILED"];
          const code = typeof details.code === "string" && codes.includes(details.code) ? details.code : "COPILOT_REQUEST_FAILED";
          return { adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
            checks: [{ code, level: "error" as const, message: error instanceof HttpError ? error.message : "Copilot metadata verification failed." }] };
        }
        return {
          adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
          checks: [{
            code: error instanceof Error && "code" in error && error.code === "ACPX_RUNTIME_PACKAGE_MISSING"
              ? "acpx_runtime_package_missing" : "acpx_runtime_unavailable",
            level: "error" as const,
            message: error instanceof Error ? error.message : "The ACPX runtime could not be verified.",
          }],
        };
      }
    }
    if (profile.provider === "claude_managed") {
      return {
        adapterType: "paperclip_runner",
        status: "warn" as const,
        testedAt: new Date().toISOString(),
        checks: [{
          code: "claude_managed_profile_selected",
          level: "info" as const,
          message: `Claude Managed profile ${profile.managedProfileId} is selected with retention acknowledged. Its stored qualification, API-key binding, and spend ceiling are verified before the first turn.`,
        }, {
          code: "claude_managed_retention_notice",
          level: "warn" as const,
          message: "Claude Managed is a stateful beta service and is not eligible for ZDR or HIPAA modes.",
        }],
      };
    }
    if (profile.provider === "aws_agentcore") {
      return {
        adapterType: "paperclip_runner",
        status: "warn" as const,
        testedAt: new Date().toISOString(),
        checks: [{
          code: "aws_agentcore_profile_selected",
          level: "info" as const,
          message: `AWS AgentCore profile ${profile.agentCoreProfileId} is selected with retention acknowledged. Its stored qualification, invocation limits, and estimated spend ceiling are verified before the first turn.`,
        }, {
          code: "aws_agentcore_retention_notice",
          level: "warn" as const,
          message: "AgentCore Memory retains short-term events for 90 days; the spend ceiling is an estimate, not an AWS currency hard stop.",
        }],
      };
    }
    if (profile.provider === "codex") {
      const { testNativeRunnerAuthentication } = await import("../services/native-runtime/setup-readiness.js");
      return testNativeRunnerAuthentication(context, "codex", profile.model);
    }
    const result = await openCodeTestEnvironment(context);
    return { ...result, adapterType: "paperclip_runner" };
  },
  listSkills: listCodexSkills,
  syncSkills: syncCodexSkills,
  sessionCodec: codexSessionCodec,
  models: [
    ...codexModels,
    { id: DEFAULT_OPENCODE_RUNNER_MODEL, label: "OpenRouter · DeepSeek V4 Flash 0731" },
    { id: DEFAULT_ACPX_RUNNER_MODELS.claude, label: "Claude Opus 5.5" },
    { id: "global.anthropic.claude-sonnet-4-6", label: "Amazon Bedrock · Claude Sonnet 4.6 (global)" },
  ],
  listModels: async () => [
    ...await listCodexModels(),
    { id: DEFAULT_OPENCODE_RUNNER_MODEL, label: "OpenRouter · DeepSeek V4 Flash 0731" },
    { id: DEFAULT_ACPX_RUNNER_MODELS.claude, label: "Claude Opus 5.5" },
    { id: "global.anthropic.claude-sonnet-4-6", label: "Amazon Bedrock · Claude Sonnet 4.6 (global)" },
  ],
  refreshModels: async () => [
    ...await refreshCodexModels(),
    { id: DEFAULT_OPENCODE_RUNNER_MODEL, label: "OpenRouter · DeepSeek V4 Flash 0731" },
    { id: DEFAULT_ACPX_RUNNER_MODELS.claude, label: "Claude Opus 5.5" },
    { id: "global.anthropic.claude-sonnet-4-6", label: "Amazon Bedrock · Claude Sonnet 4.6 (global)" },
  ],
  supportsLocalAgentJwt: false,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: false,
  getRuntimeCommandSpec: (config) => config.provider === "claude_managed"
    || config.provider === "aws_agentcore"
    || config.provider === "acpx"
    || config.provider === "cursor_cloud"
    ? { command: "paperclip-runnerd", detectCommand: null, installCommand: null }
    : config.provider === "opencode"
      ? buildNpmRuntimeCommandSpec(
          config,
          "opencode",
          `opencode-ai@${QUALIFIED_OPENCODE_RUNNER_VERSION}`,
        )
      : buildNpmRuntimeCommandSpec(config, "codex", "@openai/codex@0.160.0"),
  agentConfigurationDoc:
    "# Paperclip Runner\n\nAdapter: paperclip_runner\n\nRuns Codex, OpenCode, Claude Managed, AWS AgentCore, or ACPX Claude/Grok Build/Cursor/Pi through the Rust Paperclip runner and authenticated PRP transport. Pi accepts an explicit provider/model ID and uses the company credentials bound to the agent environment. GitHub Copilot requires a saved GitHub token and an explicitly selected available model. Managed providers use company-scoped qualified profiles, explicit retention acknowledgement, and spend limits.\n",
  getConfigSchema: () => ({
    fields: [
      {
        key: "provider",
        label: "Provider",
        type: "select" as const,
        default: "codex",
        options: [
          { value: "codex", label: "Codex" },
          { value: "opencode", label: `OpenCode ${QUALIFIED_OPENCODE_RUNNER_VERSION}` },
          { value: "claude_managed", label: "Claude Managed" },
          { value: "aws_agentcore", label: "AWS AgentCore" },
          { value: "acpx", label: "ACP agents" },
          { value: "cursor_cloud", label: "Cursor Cloud (experimental)" },
        ],
        hint: "Select a local provider, company-qualified managed provider, or an ACP agent.",
      },
      {
        key: "acpxAgent", label: "ACP agent", type: "select" as const, default: "claude",
        options: PAPERCLIP_RUNNER_ACPX_PROFILES.filter(profile => profile.qualified).map(profile => ({ value: profile.value, label: profile.label })),
        meta: { visibleWhen: { key: "provider", value: "acpx" } },
      },
      ...[
        { key: "repoUrl", label: "GitHub repository" },
        { key: "repoRef", label: "Starting ref" },
        { key: "prUrl", label: "Pull request URL" },
        { key: "cloudEnvName", label: "Cursor cloud environment" },
      ].map(field => ({ ...field, type: "text" as const, meta: { visibleWhen: { key: "provider", value: "cursor_cloud" } } })),
      ...[
        { key: "workOnCurrentBranch", label: "Work on current branch" },
        { key: "autoCreatePR", label: "Auto-create pull request" },
        { key: "skipReviewerRequest", label: "Skip reviewer request" },
      ].map(field => ({ ...field, type: "toggle" as const, default: false, meta: { visibleWhen: { key: "provider", value: "cursor_cloud" } } })),
      {
        key: "codexPermissionMode",
        label: "Codex permission mode",
        type: "select" as const,
        default: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.codex.defaultMode,
        options: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.codex.options.map(
          ({ value, label }) => ({ value, label }),
        ),
        hint: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.codex.description,
        meta: { visibleWhen: { key: "provider", value: "codex" } },
      },
      {
        key: "opencodePermissionMode",
        label: "OpenCode permission mode",
        type: "select" as const,
        default: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.opencode.defaultMode,
        options: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.opencode.options.map(
          ({ value, label }) => ({ value, label }),
        ),
        hint: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.opencode.description,
        meta: { visibleWhen: { key: "provider", value: "opencode" } },
      },
      {
        key: "acpxSessionMode",
        label: "Cursor mode",
        type: "select" as const,
        default: "agent",
        options: [
          { value: "agent", label: "Agent" },
          { value: "plan", label: "Plan" },
          { value: "ask", label: "Ask" },
        ],
        hint: "Select Cursor's session mode. Permissions and company approval rules still apply.",
        meta: { visibleWhen: { key: "acpxAgent", value: "cursor" } },
      },
      {
        key: "acpxPermissionMode",
        label: "ACPX permission mode",
        type: "select" as const,
        default: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.acpx.defaultMode,
        options: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.acpx.options.map(
          ({ value, label }) => ({ value, label }),
        ),
        hint: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.acpx.description,
        meta: { visibleWhen: { key: "provider", value: "acpx" } },
      },
      {
        key: "model",
        label: "Provider model",
        type: "text" as const,
        default: "",
        placeholder: DEFAULT_OPENCODE_RUNNER_MODEL,
        hint: "OpenCode uses provider/model form. ACPX Claude accepts Claude model IDs, including custom IDs.",
        meta: { visibleWhen: { key: "provider", value: "opencode" } },
      },
      {
        key: "managedProfileId",
        label: "Managed Agent profile",
        type: "text" as const,
        required: true,
        hint: "Company-scoped qualified profile ID or key.",
        meta: { visibleWhen: { key: "provider", value: "claude_managed" } },
      },
      {
        key: "maxSessionListCostUsd",
        label: "Session spend ceiling (USD)",
        type: "number" as const,
        default: 1,
        hint: "Hard ceiling for one Claude Managed session.",
        meta: { visibleWhen: { key: "provider", value: "claude_managed" } },
      },
      {
        key: "managedAgentsRetentionAcknowledged",
        label: "Acknowledge managed retention",
        type: "toggle" as const,
        default: false,
        hint: "Claude Managed is stateful beta and is not eligible for ZDR or HIPAA modes.",
        meta: { visibleWhen: { key: "provider", value: "claude_managed" } },
      },
      {
        key: "agentCoreProfileId",
        label: "AgentCore profile",
        type: "text" as const,
        required: true,
        hint: "Company-scoped qualified AgentCore profile ID or key.",
        meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
      },
      {
        key: "maxEstimatedSessionCostUsd",
        label: "Estimated session ceiling (USD)",
        type: "number" as const,
        default: 1,
        hint: "Paperclip estimate; AWS does not provide a per-session currency hard stop.",
        meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
      },
      {
        key: "maxIterations",
        label: "Maximum iterations",
        type: "number" as const,
        default: 8,
        hint: "Must be between 1 and the qualified maximum of 8.",
        meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
      },
      {
        key: "maxOutputTokens",
        label: "Maximum output tokens",
        type: "number" as const,
        default: 4_096,
        hint: "Must be between 1 and the qualified maximum of 4096.",
        meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
      },
      {
        key: "timeoutSeconds",
        label: "Invocation timeout (seconds)",
        type: "number" as const,
        default: 300,
        hint: "Must be between 1 and the qualified maximum of 300 seconds.",
        meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
      },
      {
        key: "agentCoreRetentionAcknowledged",
        label: "Acknowledge 90-day Memory retention",
        type: "toggle" as const,
        default: false,
        hint: "The qualified AgentCore profile retains short-term Memory events for 90 days.",
        meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
      },
      {
        key: "lifecycleMode",
        label: "Runner lifecycle",
        type: "select" as const,
        default: "per_turn",
        options: [
          { value: "per_turn", label: "Turn by turn" },
          { value: "warm", label: "Warm session" },
        ],
        hint: "Warm sessions retain runnerd and Codex between governed runs.",
      },
      {
        key: "idleTimeoutMs",
        label: "Warm idle timeout (ms)",
        type: "number" as const,
        default: 300_000,
        hint: "Warm sessions suspend after this much inactivity.",
        meta: { visibleWhen: { key: "lifecycleMode", value: "warm" } },
      },
    ],
  }),
  loginCapability: codexLoginCapability,
};

const cursorLocalAdapter: ServerAdapterModule = {
  type: "cursor",
  runtimeToolDelivery: "environment",
  execute: cursorExecute,
  testEnvironment: cursorTestEnvironment,
  listSkills: listCursorSkills,
  syncSkills: syncCursorSkills,
  sessionCodec: cursorSessionCodec,
  sessionManagement: getAdapterSessionManagement("cursor") ?? undefined,
  supportsToolRefreshOnResume: true,
  models: cursorModels,
  listModels: listCursorModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: true,
  getRuntimeCommandSpec: buildCursorRuntimeCommandSpec,
  agentConfigurationDoc: cursorAgentConfigurationDoc,
};

const cursorCloudAdapter: ServerAdapterModule = {
  type: "cursor_cloud",
  runtimeToolDelivery: "invocation_context",
  execute: cursorCloudExecute,
  testEnvironment: cursorCloudTestEnvironment,
  sessionCodec: cursorCloudSessionCodec,
  sessionManagement: getAdapterSessionManagement("cursor_cloud") ?? undefined,
  models: [],
  supportsLocalAgentJwt: false,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: false,
  agentConfigurationDoc: cursorCloudAgentConfigurationDoc,
  getConfigSchema: getCursorCloudConfigSchema,
};

const geminiLocalAdapter: ServerAdapterModule = {
  type: "gemini_local",
  runtimeToolDelivery: "environment",
  execute: geminiExecute,
  testEnvironment: geminiTestEnvironment,
  acp: {
    agentId: "gemini",
    skillsMode: "ephemeral",
    prerequisites: {
      nodeRange: ">=24.11.0",
      packages: ["@google/gemini-cli"],
    },
  },
  listSkills: listGeminiSkills,
  syncSkills: syncGeminiSkills,
  sessionCodec: geminiSessionCodec,
  sessionManagement: getAdapterSessionManagement("gemini_local") ?? undefined,
  supportsToolRefreshOnResume: true,
  models: geminiModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: true,
  getRuntimeCommandSpec: (config) =>
    buildNpmRuntimeCommandSpec(config, "gemini", "@google/gemini-cli"),
  agentConfigurationDoc: geminiAgentConfigurationDoc,
  getConfigSchema: getGeminiConfigSchema,
};

const grokLocalAdapter: ServerAdapterModule = {
  type: "grok_local",
  runtimeToolDelivery: "environment",
  execute: grokExecute,
  testEnvironment: grokTestEnvironment,
  listSkills: listGrokSkills,
  syncSkills: syncGrokSkills,
  sessionCodec: grokSessionCodec,
  sessionManagement: getAdapterSessionManagement("grok_local") ?? undefined,
  supportsToolRefreshOnResume: true,
  models: grokModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: true,
  getRuntimeCommandSpec: (config) => ({
    command: readConfiguredCommand(config, "grok"),
    detectCommand: readConfiguredCommand(config, "grok"),
    installCommand: null,
  }),
  agentConfigurationDoc: grokAgentConfigurationDoc,
  loginCapability: grokLoginCapability,
};

const kimiLocalAdapter: ServerAdapterModule = {
  type: "kimi_local",
  runtimeToolDelivery: "environment",
  execute: kimiExecute,
  testEnvironment: kimiTestEnvironment,
  acp: {
    agentId: "kimi",
    skillsMode: "ephemeral",
    prerequisites: {
      nodeRange: ">=20.0.0",
      packages: ["@moonshot-ai/kimi-code"],
    },
  },
  listSkills: listKimiSkills,
  syncSkills: syncKimiSkills,
  sessionCodec: kimiSessionCodec,
  sessionManagement: getAdapterSessionManagement("kimi_local") ?? undefined,
  supportsToolRefreshOnResume: true,
  models: kimiModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: true,
  getRuntimeCommandSpec: (config) =>
    buildNpmRuntimeCommandSpec(config, "kimi", "@moonshot-ai/kimi-code"),
  agentConfigurationDoc: kimiAgentConfigurationDoc,
};

const hermesGatewayAdapter: ServerAdapterModule = {
  ...createHermesGatewayServerAdapter(),
  runtimeToolDelivery: "invocation_context",
};

const hermesLocalAdapter: ServerAdapterModule = {
  ...createHermesLocalServerAdapter(),
  runtimeToolDelivery: "environment",
};

const openclawGatewayAdapter: ServerAdapterModule = {
  type: "openclaw_gateway",
  runtimeToolDelivery: "invocation_context",
  execute: openclawGatewayExecute,
  testEnvironment: openclawGatewayTestEnvironment,
  models: openclawGatewayModels,
  supportsLocalAgentJwt: false,
  supportsInstructionsBundle: false,
  requiresMaterializedRuntimeSkills: false,
  agentConfigurationDoc: openclawGatewayAgentConfigurationDoc,
};

const openCodeLocalAdapter: ServerAdapterModule = {
  type: "opencode_local",
  runtimeToolDelivery: "environment",
  execute: openCodeExecute,
  testEnvironment: openCodeTestEnvironment,
  listSkills: listOpenCodeSkills,
  syncSkills: syncOpenCodeSkills,
  sessionCodec: openCodeSessionCodec,
  models: openCodeModels,
  sessionManagement: getAdapterSessionManagement("opencode_local") ?? undefined,
  supportsToolRefreshOnResume: true,
  listModels: listOpenCodeModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: true,
  getRuntimeCommandSpec: (config) => buildNpmRuntimeCommandSpec(config, "opencode", "opencode-ai"),
  agentConfigurationDoc: openCodeAgentConfigurationDoc,
};

const piLocalAdapter: ServerAdapterModule = {
  type: "pi_local",
  runtimeToolDelivery: "environment",
  execute: piExecute,
  testEnvironment: piTestEnvironment,
  listSkills: listPiSkills,
  syncSkills: syncPiSkills,
  sessionCodec: piSessionCodec,
  sessionManagement: getAdapterSessionManagement("pi_local") ?? undefined,
  supportsToolRefreshOnResume: true,
  models: [],
  listModels: listPiModels,
  supportsLocalAgentJwt: true,
  supportsInstructionsBundle: true,
  instructionsPathKey: "instructionsFilePath",
  requiresMaterializedRuntimeSkills: true,
  getRuntimeCommandSpec: (config) =>
    buildNpmRuntimeCommandSpec(config, "pi", "@mariozechner/pi-coding-agent"),
  agentConfigurationDoc: piAgentConfigurationDoc,
};

const adaptersByType = new Map<string, ServerAdapterModule>();

// For builtin types that are overridden by an external adapter, we keep the
// original builtin so it can be restored when the override is deactivated.
const builtinFallbacks = new Map<string, ServerAdapterModule>();

// Tracks which override types are currently deactivated (paused).  When
// paused, `getServerAdapter()` returns the builtin fallback instead of the
// external.  Persisted across reloads via the same disabled-adapters store.
const pausedOverrides = new Set<string>();

function registerBuiltInAdapters() {
  for (const adapter of [
    acpxLocalAdapter,
    claudeLocalAdapter,
    codexLocalAdapter,
    paperclipRunnerAdapter,
    openCodeLocalAdapter,
    piLocalAdapter,
    cursorCloudAdapter,
    cursorLocalAdapter,
    geminiLocalAdapter,
    grokLocalAdapter,
    kimiLocalAdapter,
    hermesGatewayAdapter,
    hermesLocalAdapter,
    openclawGatewayAdapter,
    processAdapter,
    httpAdapter,
  ]) {
    adaptersByType.set(adapter.type, adapter);
  }
}

registerBuiltInAdapters();

// ---------------------------------------------------------------------------
// Load external adapter plugins (e.g. droid_local)
//
// External adapter packages export createServerAdapter() which returns a
// ServerAdapterModule. When the module provides its own sessionManagement
// it is preserved; otherwise the host falls back to the built-in registry
// lookup (so externals that override a built-in type inherit the builtin's
// policy). This brings init-time registration to at-least-as-good behavior
// as the hot-install path (routes/adapters.ts:179 -> registerServerAdapter):
// both preserve module-provided sessionManagement, and init-time additionally
// applies the registry fallback for externals overriding a built-in type.
// ---------------------------------------------------------------------------

/**
 * Merge an external adapter module with host-provided session management.
 *
 * Module-provided `sessionManagement` takes precedence. When absent, fall
 * back to the hardcoded registry keyed by adapter type (so externals that
 * override a built-in — same `type` — inherit the builtin's policy). If
 * neither is available, `sessionManagement` remains `undefined`.
 *
 * Used by both the init-time IIFE below (external-adapter load pass on
 * server start) and the hot-install path in `routes/adapters.ts`
 * (`registerWithSessionManagement`), so the two load paths resolve
 * `sessionManagement` identically.
 */
export function resolveExternalAdapterRegistration(
  externalAdapter: ServerAdapterModule,
): ServerAdapterModule {
  return {
    ...externalAdapter,
    sessionManagement:
      externalAdapter.sessionManagement
        ?? getAdapterSessionManagement(externalAdapter.type)
        ?? undefined,
  };
}

/**
 * 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 () => {
  if (isCloudManagedInstance()) return;
  try {
    const externalAdapters = await buildExternalAdapters();
    for (const externalAdapter of externalAdapters) {
      const overriding = BUILTIN_ADAPTER_TYPES.has(externalAdapter.type);
      if (overriding) {
        console.log(
          `[paperclip] External adapter "${externalAdapter.type}" overrides built-in adapter`,
        );
        // Save the original builtin for later restoration.
        const existing = adaptersByType.get(externalAdapter.type);
        if (existing && !builtinFallbacks.has(externalAdapter.type)) {
          builtinFallbacks.set(externalAdapter.type, existing);
        }
      }
      adaptersByType.set(
        externalAdapter.type,
        resolveExternalAdapterRegistration(externalAdapter),
      );
    }
  } 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 {
  assertExternalAdapterCodeAllowed();
  if (BUILTIN_ADAPTER_TYPES.has(adapter.type) && !builtinFallbacks.has(adapter.type)) {
    const existing = adaptersByType.get(adapter.type);
    if (existing) {
      builtinFallbacks.set(adapter.type, existing);
    }
  }
  adaptersByType.set(adapter.type, adapter);
}

export function unregisterServerAdapter(type: string): void {
  assertExternalAdapterCodeAllowed();
  if (type === processAdapter.type || type === httpAdapter.type) return;
  if (builtinFallbacks.has(type)) {
    pausedOverrides.delete(type);
    const fallback = builtinFallbacks.get(type);
    if (fallback) {
      adaptersByType.set(type, fallback);
    }
    return;
  }
  if (BUILTIN_ADAPTER_TYPES.has(type)) {
    return;
  }
  adaptersByType.delete(type);
}

export function requireServerAdapter(type: string): ServerAdapterModule {
  const adapter = findActiveServerAdapter(type);
  if (!adapter) {
    throw new Error(`Unknown adapter type: ${type}`);
  }
  return adapter;
}

export function getServerAdapter(type: string): ServerAdapterModule {
  return findActiveServerAdapter(type) ?? processAdapter;
}

/**
 * Memoized view of PAPERCLIP_ADAPTER_MODELS, keyed by the raw env string so
 * tests (and live env mutation) that change the variable are still observed.
 * Parsing happens at most once per distinct raw value instead of per
 * `listAdapterModels` request, and malformed values fail SOFT here: we log the
 * parse error once (per distinct raw value) and fall back to adapter-discovered
 * models rather than throwing at request time.
 */
let adapterModelsEnvCache: {
  raw: string | undefined;
  value: ReturnType<typeof parseAdapterModelsEnv>;
} | null = null;

function getDeclaredAdapterModels(): ReturnType<typeof parseAdapterModelsEnv> {
  const raw = process.env.PAPERCLIP_ADAPTER_MODELS;
  if (adapterModelsEnvCache && adapterModelsEnvCache.raw === raw) {
    return adapterModelsEnvCache.value;
  }
  let value: ReturnType<typeof parseAdapterModelsEnv> = null;
  try {
    value = parseAdapterModelsEnv(process.env);
  } catch (err) {
    console.error(
      "[paperclip] Invalid PAPERCLIP_ADAPTER_MODELS; ignoring declared model lists:",
      err,
    );
  }
  adapterModelsEnvCache = { raw, value };
  return value;
}

function declaredModelsForAdapter(type: string): { id: string; label: string }[] | null {
  const declared = getDeclaredAdapterModels()?.[type];
  return declared?.length
    ? declared.map((model) => ({ id: model.id, label: model.label ?? model.id }))
    : null;
}

export async function listAdapterModels(type: string): Promise<{ id: string; label: string }[]> {
  const declaredModels = declaredModelsForAdapter(type);
  if (declaredModels) return declaredModels;
  const adapter = findActiveServerAdapter(type);
  if (!adapter) return [];
  // The built-in Codex adapter's OpenAI discovery includes image, audio, and
  // embedding models that Codex cannot run. Use its curated list; declared
  // models above and custom adapter discovery remain authoritative.
  if (adapter === codexLocalAdapter) return adapter.models ?? [];
  if (adapter.listModels) {
    const discovered = await adapter.listModels();
    if (discovered.length > 0) return discovered;
  }
  return adapter.models ?? [];
}

export async function refreshAdapterModels(type: string): Promise<{ id: string; label: string }[]> {
  const declaredModels = declaredModelsForAdapter(type);
  if (declaredModels) return declaredModels;
  if (findActiveServerAdapter(type) === codexLocalAdapter) return listAdapterModels(type);
  const adapter = findActiveServerAdapter(type);
  if (!adapter) return [];
  if (adapter.refreshModels) {
    const refreshed = await adapter.refreshModels();
    if (refreshed.length > 0) return refreshed;
  }
  if (adapter.listModels) {
    const discovered = await adapter.listModels();
    if (discovered.length > 0) return discovered;
  }
  return adapter.models ?? [];
}

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(disabled: string[]): ServerAdapterModule[] {
  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; candidates?: string[] } | null> {
  const adapter = findActiveServerAdapter(type);
  if (!adapter?.detectModel) return null;
  const detected = await adapter.detectModel();
  if (!detected) return null;
  return {
    model: detected.model,
    provider: detected.provider,
    source: detected.source,
    ...(detected.candidates?.length ? { candidates: detected.candidates } : {}),
  };
}

// ---------------------------------------------------------------------------
// Override pause / resume
// ---------------------------------------------------------------------------

/**
 * Pause or resume an external override for a builtin adapter type.
 *
 * - `paused = true`  → subsequent calls to `getServerAdapter(type)` return
 *   the builtin fallback instead of the external adapter.  Already-running
 *   agent sessions are unaffected (they hold a reference to the module they
 *   started with).
 *
 * - `paused = false` → the external adapter is active again.
 *
 * Returns `true` if the state actually changed, `false` if the type is not
 * an override or was already in the requested state.
 */
export function setOverridePaused(type: string, paused: boolean): boolean {
  assertExternalAdapterCodeAllowed();
  if (!builtinFallbacks.has(type)) return false;
  const wasPaused = pausedOverrides.has(type);
  if (paused && !wasPaused) {
    pausedOverrides.add(type);
    console.log(`[paperclip] Override paused for "${type}" — builtin adapter restored`);
    return true;
  }
  if (!paused && wasPaused) {
    pausedOverrides.delete(type);
    console.log(`[paperclip] Override resumed for "${type}" — external adapter active`);
    return true;
  }
  return false;
}

/** Check whether the external override for a builtin type is currently paused. */
export function isOverridePaused(type: string): boolean {
  return pausedOverrides.has(type);
}

export function hasActiveAdapterOverride(type: string): boolean {
  const registered = adaptersByType.get(type);
  return builtinFallbacks.has(type) && registered !== undefined
    && registered !== builtinFallbacks.get(type) && !pausedOverrides.has(type);
}

/** Get the set of types whose overrides are currently paused. */
export function getPausedOverrides(): Set<string> {
  return pausedOverrides;
}

export function findServerAdapter(type: string): ServerAdapterModule | null {
  return adaptersByType.get(type) ?? null;
}

export function findActiveServerAdapter(type: string): ServerAdapterModule | null {
  if (pausedOverrides.has(type)) {
    const fallback = builtinFallbacks.get(type);
    if (fallback) return fallback;
  }
  return adaptersByType.get(type) ?? null;
}