Merge branch 'main' into custom-username

Co-authored-by: openhands <openhands@all-hands.dev>

.github/workflows/welcome-good-first-issue.yml

@@ -45,6 +45,7 @@ jobs:
                     "This issue has been labeled as **good first issue**, which means it's a great place to get started with the OpenHands project.\n\n" +
                     "If you're interested in working on it, feel free to! No need to ask for permission.\n\n" +
                     "Be sure to check out our [development setup guide](" + repoUrl + "/blob/main/Development.md) to get your environment set up, and follow our [contribution guidelines](" + repoUrl + "/blob/main/CONTRIBUTING.md) when you're ready to submit a fix.\n\n" +
+                    "Feel free to join our developer community on [Slack](dub.sh/openhands). You can ask for [help](https://openhands-ai.slack.com/archives/C078L0FUGUX), [feedback](https://openhands-ai.slack.com/archives/C086ARSNMGA), and even ask for a [PR review](https://openhands-ai.slack.com/archives/C08D8FJ5771).\n\n" +
                     "🙌 Happy hacking! 🙌\n\n" +
                     "<!-- auto-comment:good-first-issue -->"
             });

LICENSE

@@ -1,7 +1,12 @@
-The MIT License (MIT)
+Portions of this software are licensed as follows:
+* All content that resides under the enterprise/ directory is licensed under the license defined in "enterprise/LICENSE".
+* Content outside of the above mentioned directories or restrictions above is available under the MIT license as defined below.
+
 =====================
 
-Copyright © 2023
+The MIT License (MIT)
+
+Copyright © 2025
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

docs/usage/troubleshooting/troubleshooting.mdx

@@ -46,7 +46,14 @@ When running on Linux, you might run into the error `ERROR:root:<class 'httpx.Co
 
 **Resolution**
 
-* Add the `--network host` to the docker run command.
+If you installed Docker from your distribution’s package repository (e.g., docker.io on Debian/Ubuntu), be aware that
+these packages can sometimes be outdated or include changes that cause compatibility issues. try reinstalling Docker
+[using the official instructions](https://docs.docker.com/engine/install/) to ensure you are running a compatible version.
+
+If that does not solve the issue, try incrementally adding the following parameters to the docker run command:
+* `--network host`
+* `-e SANDBOX_USE_HOST_NETWORK=true`
+* `-e DOCKER_HOST_ADDR=127.0.0.1`
 
 ### Internal Server Error. Ports are not available
 

enterprise/LICENSE

@@ -0,0 +1,89 @@
+# PolyForm Free Trial License 1.0.0
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose.  However, you may only make changes or
+new works based on the software according to [Changes and New
+Works License](#changes-and-new-works-license), and you may
+not distribute copies of the software.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## Free Trial
+
+Use of the software for more than 30 days per calendar year is not allowed without a commercial license.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+If you violate any of these terms, or do anything with the
+software not covered by your licenses, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

frontend/__tests__/components/features/microagent-management/microagent-management.test.tsx

@@ -2545,64 +2545,6 @@ describe("MicroagentManagement", () => {
         screen.queryByTestId("learn-this-repo-trigger"),
       ).not.toBeInTheDocument();
     });
-
-    it("should handle API call for branches when learn this repo modal opens", async () => {
-      // Mock branch API
-      const branchesSpy = vi
-        .spyOn(OpenHands, "getRepositoryBranches")
-        .mockResolvedValue({
-          branches: [
-            { name: "main", commit_sha: "abc123", protected: false },
-            { name: "develop", commit_sha: "def456", protected: false },
-          ],
-          has_next_page: false,
-          current_page: 1,
-          per_page: 30,
-          total_count: 2,
-        });
-
-      // Mock other APIs
-      const getRepositoryMicroagentsSpy = vi.spyOn(
-        OpenHands,
-        "getRepositoryMicroagents",
-      );
-      const searchConversationsSpy = vi.spyOn(OpenHands, "searchConversations");
-      getRepositoryMicroagentsSpy.mockResolvedValue([]);
-      searchConversationsSpy.mockResolvedValue([]);
-
-      // Test with direct Redux state that has modal visible
-      renderWithProviders(<RouterStub />, {
-        preloadedState: {
-          metrics: {
-            cost: null,
-            max_budget_per_task: null,
-            usage: null,
-          },
-          microagentManagement: {
-            selectedMicroagentItem: null,
-            addMicroagentModalVisible: false,
-            updateMicroagentModalVisible: false,
-            learnThisRepoModalVisible: true, // Modal should be visible
-            selectedRepository: {
-              id: "1",
-              full_name: "test-org/test-repo",
-              git_provider: "github",
-              is_public: true,
-              owner_type: "user",
-              pushed_at: "2021-10-01T12:00:00Z",
-            },
-            personalRepositories: [],
-            organizationRepositories: [],
-            repositories: [],
-          },
-        },
-      });
-
-      // The branches API should be called when the modal is visible
-      await waitFor(() => {
-        expect(branchesSpy).toHaveBeenCalledWith("test-org/test-repo");
-      });
-    });
   });
 
   // Learn something new button functionality tests

frontend/src/api/open-hands.ts

@@ -31,6 +31,7 @@ import { SuggestedTask } from "#/components/features/home/tasks/task.types";
 import { extractNextPageFromLink } from "#/utils/extract-next-page-from-link";
 import { RepositoryMicroagent } from "#/types/microagent-management";
 import { BatchFeedbackData } from "#/hooks/query/use-batch-feedback";
+import { SubscriptionAccess } from "#/types/billing";
 
 class OpenHands {
   private static currentConversation: Conversation | null = null;
@@ -433,6 +434,13 @@ class OpenHands {
     return data.credits;
   }
 
+  static async getSubscriptionAccess(): Promise<SubscriptionAccess | null> {
+    const { data } = await openHands.get<SubscriptionAccess | null>(
+      "/api/billing/subscription-access",
+    );
+    return data;
+  }
+
   static async getGitUser(): Promise<GitUser> {
     const response = await openHands.get<GitUser>("/api/user/info");
 

frontend/src/api/open-hands.types.ts

@@ -49,13 +49,11 @@ export interface GetConfigResponse {
   APP_SLUG?: string;
   GITHUB_CLIENT_ID: string;
   POSTHOG_CLIENT_KEY: string;
-  STRIPE_PUBLISHABLE_KEY?: string;
   PROVIDERS_CONFIGURED?: Provider[];
   AUTH_URL?: string;
   FEATURE_FLAGS: {
     ENABLE_BILLING: boolean;
     HIDE_LLM_SETTINGS: boolean;
-    HIDE_MICROAGENT_MANAGEMENT?: boolean;
     ENABLE_JIRA: boolean;
     ENABLE_JIRA_DC: boolean;
     ENABLE_LINEAR: boolean;

frontend/src/components/features/microagent-management/microagent-management-content.tsx

@@ -288,7 +288,6 @@ export function MicroagentManagementContent() {
       conversationInstructions: formData.query,
       repository: {
         name: repositoryName,
-        branch: formData.selectedBranch,
         gitProvider,
       },
       createMicroagent,

frontend/src/components/features/microagent-management/microagent-management-learn-this-repo-modal.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useSelector } from "react-redux";
 import { FaCircleInfo } from "react-icons/fa6";
@@ -10,13 +10,6 @@ import { RootState } from "#/store";
 import XIcon from "#/icons/x.svg?react";
 import { cn, getRepoMdCreatePrompt } from "#/utils/utils";
 import { LearnThisRepoFormData } from "#/types/microagent-management";
-import { Branch } from "#/types/git";
-import { useRepositoryBranches } from "#/hooks/query/use-repository-branches";
-import {
-  BranchDropdown,
-  BranchLoadingState,
-  BranchErrorState,
-} from "../home/repository-selection";
 
 interface MicroagentManagementLearnThisRepoModalProps {
   onConfirm: (formData: LearnThisRepoFormData) => void;
@@ -32,47 +25,11 @@ export function MicroagentManagementLearnThisRepoModal({
   const { t } = useTranslation();
 
   const [query, setQuery] = useState<string>("");
-  const [selectedBranch, setSelectedBranch] = useState<Branch | null>(null);
 
   const { selectedRepository } = useSelector(
     (state: RootState) => state.microagentManagement,
   );
 
-  // Add a ref to track if the branch was manually cleared by the user
-  const branchManuallyClearedRef = useRef<boolean>(false);
-
-  const {
-    data: branches,
-    isLoading: isLoadingBranches,
-    isError: isBranchesError,
-  } = useRepositoryBranches(selectedRepository?.full_name || null);
-
-  const branchesItems = branches?.map((branch) => ({
-    key: branch.name,
-    label: branch.name,
-  }));
-
-  // Auto-select main or master branch if it exists.
-  useEffect(() => {
-    if (
-      branches &&
-      branches.length > 0 &&
-      !selectedBranch &&
-      !isLoadingBranches
-    ) {
-      // Look for main or master branch
-      const mainBranch = branches.find((branch) => branch.name === "main");
-      const masterBranch = branches.find((branch) => branch.name === "master");
-
-      // Select main if it exists, otherwise select master if it exists
-      if (mainBranch) {
-        setSelectedBranch(mainBranch);
-      } else if (masterBranch) {
-        setSelectedBranch(masterBranch);
-      }
-    }
-  }, [branches, isLoadingBranches, selectedBranch]);
-
   const onSubmit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
 
@@ -83,7 +40,6 @@ export function MicroagentManagementLearnThisRepoModal({
 
     onConfirm({
       query: finalQuery,
-      selectedBranch: selectedBranch?.name || "",
     });
   };
 
@@ -95,66 +51,9 @@ export function MicroagentManagementLearnThisRepoModal({
 
     onConfirm({
       query: finalQuery,
-      selectedBranch: selectedBranch?.name || "",
     });
   };
 
-  const handleBranchSelection = (key: React.Key | null) => {
-    const selectedBranchObj = branches?.find((branch) => branch.name === key);
-    setSelectedBranch(selectedBranchObj || null);
-    // Reset the manually cleared flag when a branch is explicitly selected
-    branchManuallyClearedRef.current = false;
-  };
-
-  const handleBranchInputChange = (value: string) => {
-    // Clear the selected branch if the input is empty or contains only whitespace
-    // This fixes the issue where users can't delete the entire default branch name
-    if (value === "" || value.trim() === "") {
-      setSelectedBranch(null);
-      // Set the flag to indicate that the branch was manually cleared
-      branchManuallyClearedRef.current = true;
-    } else {
-      // Reset the flag when the user starts typing again
-      branchManuallyClearedRef.current = false;
-    }
-  };
-
-  // Render the appropriate UI for branch selector based on the loading/error state
-  const renderBranchSelector = () => {
-    if (!selectedRepository) {
-      return (
-        <BranchDropdown
-          items={[]}
-          onSelectionChange={() => {}}
-          onInputChange={() => {}}
-          isDisabled
-          wrapperClassName="max-w-full w-full"
-          label={t(I18nKey.REPOSITORY$SELECT_BRANCH)}
-        />
-      );
-    }
-
-    if (isLoadingBranches) {
-      return <BranchLoadingState wrapperClassName="max-w-full w-full" />;
-    }
-
-    if (isBranchesError) {
-      return <BranchErrorState wrapperClassName="max-w-full w-full" />;
-    }
-
-    return (
-      <BranchDropdown
-        items={branchesItems || []}
-        onSelectionChange={handleBranchSelection}
-        onInputChange={handleBranchInputChange}
-        isDisabled={false}
-        selectedKey={selectedBranch?.name}
-        wrapperClassName="max-w-full w-full"
-        label={t(I18nKey.REPOSITORY$SELECT_BRANCH)}
-      />
-    );
-  };
-
   return (
     <ModalBackdrop onClose={onCancel}>
       <ModalBody
@@ -200,9 +99,6 @@ export function MicroagentManagementLearnThisRepoModal({
           onSubmit={onSubmit}
           className="flex flex-col gap-6 w-full"
         >
-          <div data-testid="branch-selector-container">
-            {renderBranchSelector()}
-          </div>
           <label
             htmlFor="query-input"
             className="flex flex-col gap-2 w-full text-sm font-normal"
@@ -245,16 +141,9 @@ export function MicroagentManagementLearnThisRepoModal({
             variant="primary"
             onClick={handleConfirm}
             testId="confirm-button"
-            isDisabled={
-              isLoading ||
-              isLoadingBranches ||
-              !selectedBranch ||
-              isBranchesError
-            }
+            isDisabled={isLoading}
           >
-            {isLoading || isLoadingBranches
-              ? t(I18nKey.HOME$LOADING)
-              : t(I18nKey.MICROAGENT$LAUNCH)}
+            {isLoading ? t(I18nKey.HOME$LOADING) : t(I18nKey.MICROAGENT$LAUNCH)}
           </BrandButton>
         </div>
       </ModalBody>

frontend/src/components/features/sidebar/sidebar.tsx

@@ -37,9 +37,6 @@ export function Sidebar() {
   const shouldHideLlmSettings =
     config?.FEATURE_FLAGS.HIDE_LLM_SETTINGS && config?.APP_MODE === "saas";
 
-  const shouldHideMicroagentManagement =
-    config?.FEATURE_FLAGS.HIDE_MICROAGENT_MANAGEMENT;
-
   React.useEffect(() => {
     if (shouldHideLlmSettings) return;
 
@@ -83,11 +80,9 @@ export function Sidebar() {
               }
               disabled={settings?.EMAIL_VERIFIED === false}
             />
-            {!shouldHideMicroagentManagement && (
-              <MicroagentManagementButton
-                disabled={settings?.EMAIL_VERIFIED === false}
-              />
-            )}
+            <MicroagentManagementButton
+              disabled={settings?.EMAIL_VERIFIED === false}
+            />
           </div>
 
           <div className="flex flex-row md:flex-col md:items-center gap-[26px] md:mb-4">

frontend/src/hooks/query/use-subscription-access.ts

@@ -0,0 +1,18 @@
+import { useQuery } from "@tanstack/react-query";
+import { useConfig } from "./use-config";
+import OpenHands from "#/api/open-hands";
+import { useIsOnTosPage } from "#/hooks/use-is-on-tos-page";
+
+export const useSubscriptionAccess = () => {
+  const { data: config } = useConfig();
+  const isOnTosPage = useIsOnTosPage();
+
+  return useQuery({
+    queryKey: ["user", "subscription_access"],
+    queryFn: OpenHands.getSubscriptionAccess,
+    enabled:
+      !isOnTosPage &&
+      config?.APP_MODE === "saas" &&
+      config?.FEATURE_FLAGS?.ENABLE_BILLING,
+  });
+};

frontend/src/i18n/translation.json

@@ -11984,20 +11984,20 @@
     "uk": "Бажаєте, щоб OpenHands розпочав нову розмову, щоб допомогти вам зрозуміти цей репозиторій?"
   },
   "MICROAGENT_MANAGEMENT$WHAT_YOU_WOULD_LIKE_TO_KNOW_ABOUT_THIS_REPO": {
-    "en": "What would you like to know about this repository?",
-    "ja": "このリポジトリについて何を知りたいですか？",
-    "zh-CN": "您想了解此存储库的哪些内容？",
-    "zh-TW": "您想了解此存儲庫的哪些內容？",
-    "ko-KR": "이 저장소에 대해 무엇을 알고 싶으신가요?",
-    "no": "Hva vil du vite om dette depotet?",
-    "it": "Cosa vorresti sapere su questo repository?",
-    "pt": "O que você gostaria de saber sobre este repositório?",
-    "es": "¿Qué te gustaría saber sobre este repositorio?",
-    "ar": "ماذا تريد أن تعرف عن هذا المستودع؟",
-    "fr": "Que souhaitez-vous savoir sur ce dépôt ?",
-    "tr": "Bu depo hakkında ne bilmek istersiniz?",
-    "de": "Was möchten Sie über dieses Repository wissen?",
-    "uk": "Що ви хотіли б дізнатися про цей репозиторій?"
+    "en": "What would you like to know about this repository? (optional)",
+    "ja": "このリポジトリについて知りたいことは何ですか？（任意）",
+    "zh-CN": "您想了解此存储库的哪些内容？（可选）",
+    "zh-TW": "您想了解此存儲庫的哪些內容？（選填）",
+    "ko-KR": "이 저장소에 대해 무엇을 알고 싶으신가요? (선택 사항)",
+    "no": "Hva vil du vite om dette depotet? (valgfritt)",
+    "it": "Cosa vorresti sapere su questo repository? (opzionale)",
+    "pt": "O que você gostaria de saber sobre este repositório? (opcional)",
+    "es": "¿Qué te gustaría saber sobre este repositorio? (opcional)",
+    "ar": "ماذا ترغب في معرفته عن هذا المستودع؟ (اختياري)",
+    "fr": "Que souhaitez-vous savoir sur ce dépôt ? (facultatif)",
+    "tr": "Bu depo hakkında ne bilmek istersiniz? (isteğe bağlı)",
+    "de": "Was möchten Sie über dieses Repository wissen? (optional)",
+    "uk": "Що ви хотіли б дізнатися про цей репозиторій? (необов'язково)"
   },
   "MICROAGENT_MANAGEMENT$DESCRIBE_WHAT_TO_KNOW_ABOUT_THIS_REPO": {
     "en": "Describe what you would like to know about this repository.",

frontend/src/mocks/handlers.ts

@@ -169,7 +169,6 @@ export const handlers = [
       APP_MODE: mockSaas ? "saas" : "oss",
       GITHUB_CLIENT_ID: "fake-github-client-id",
       POSTHOG_CLIENT_KEY: "fake-posthog-client-key",
-      STRIPE_PUBLISHABLE_KEY: "",
       FEATURE_FLAGS: {
         ENABLE_BILLING: false,
         HIDE_LLM_SETTINGS: mockSaas,

frontend/src/routes/settings.tsx

@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { NavLink, Outlet, redirect } from "react-router";
 import { useTranslation } from "react-i18next";
 import SettingsIcon from "#/icons/settings.svg?react";
@@ -8,6 +9,7 @@ import { Route } from "./+types/settings";
 import OpenHands from "#/api/open-hands";
 import { queryClient } from "#/query-client-config";
 import { GetConfigResponse } from "#/api/open-hands.types";
+import { useSubscriptionAccess } from "#/hooks/query/use-subscription-access";
 
 const SAAS_ONLY_PATHS = [
   "/settings/user",
@@ -62,10 +64,22 @@ export const clientLoader = async ({ request }: Route.ClientLoaderArgs) => {
 function SettingsScreen() {
   const { t } = useTranslation();
   const { data: config } = useConfig();
+  const { data: subscriptionAccess } = useSubscriptionAccess();
 
   const isSaas = config?.APP_MODE === "saas";
   // this is used to determine which settings are available in the UI
-  const navItems = isSaas ? SAAS_NAV_ITEMS : OSS_NAV_ITEMS;
+  const navItems = useMemo(() => {
+    const items = [];
+    if (isSaas) {
+      if (subscriptionAccess) {
+        items.push({ to: "/settings", text: "SETTINGS$NAV_LLM" });
+      }
+      items.push(...SAAS_NAV_ITEMS);
+    } else {
+      items.push(...OSS_NAV_ITEMS);
+    }
+    return items;
+  }, [isSaas, !!subscriptionAccess]);
 
   return (
     <main

frontend/src/types/billing.tsx

@@ -0,0 +1,6 @@
+export type SubscriptionAccess = {
+  status: "ACTIVE" | "DISABLED";
+  start_at: string;
+  end_at: string;
+  created_at: string;
+};

frontend/src/types/microagent-management.tsx

@@ -22,5 +22,4 @@ export interface MicroagentFormData {
 
 export interface LearnThisRepoFormData {
   query: string;
-  selectedBranch: string;
 }

openhands/microagent/microagent.py

@@ -2,7 +2,7 @@ import io
 import re
 from itertools import chain
 from pathlib import Path
-from typing import Union
+from typing import ClassVar, Union
 
 import frontmatter
 from pydantic import BaseModel
@@ -23,6 +23,31 @@ class BaseMicroagent(BaseModel):
     source: str  # path to the file
     type: MicroagentType
 
+    PATH_TO_THIRD_PARTY_MICROAGENT_NAME: ClassVar[dict[str, str]] = {
+        '.cursorrules': 'cursorrules',
+        'agents.md': 'agents',
+        'agent.md': 'agents',
+    }
+
+    @classmethod
+    def _handle_third_party(
+        cls, path: Path, file_content: str
+    ) -> Union['RepoMicroagent', None]:
+        # Determine the agent name based on file type
+        microagent_name = cls.PATH_TO_THIRD_PARTY_MICROAGENT_NAME.get(path.name.lower())
+
+        # Create RepoMicroagent if we recognized the file type
+        if microagent_name is not None:
+            return RepoMicroagent(
+                name=microagent_name,
+                content=file_content,
+                metadata=MicroagentMetadata(name=microagent_name),
+                source=str(path),
+                type=MicroagentType.REPO_KNOWLEDGE,
+            )
+
+        return None
+
     @classmethod
     def load(
         cls,
@@ -40,11 +65,10 @@ class BaseMicroagent(BaseModel):
         # Otherwise, we will rely on the name from metadata later
         derived_name = None
         if microagent_dir is not None:
-            # Special handling for .cursorrules files which are not in microagent_dir
-            if path.name == '.cursorrules':
-                derived_name = 'cursorrules'
-            else:
-                derived_name = str(path.relative_to(microagent_dir).with_suffix(''))
+            # Special handling for files which are not in microagent_dir
+            derived_name = cls.PATH_TO_THIRD_PARTY_MICROAGENT_NAME.get(
+                path.name.lower()
+            ) or str(path.relative_to(microagent_dir).with_suffix(''))
 
         # Only load directly from path if file_content is not provided
         if file_content is None:
@@ -61,15 +85,10 @@ class BaseMicroagent(BaseModel):
                 type=MicroagentType.REPO_KNOWLEDGE,
             )
 
-        # Handle .cursorrules files
-        if path.name == '.cursorrules':
-            return RepoMicroagent(
-                name='cursorrules',
-                content=file_content,
-                metadata=MicroagentMetadata(name='cursorrules'),
-                source=str(path),
-                type=MicroagentType.REPO_KNOWLEDGE,
-            )
+        # Handle third-party agent instruction files
+        third_party_agent = cls._handle_third_party(path, file_content)
+        if third_party_agent is not None:
+            return third_party_agent
 
         file_io = io.StringIO(file_content)
         loaded = frontmatter.load(file_io)
@@ -276,31 +295,44 @@ def load_microagents_from_dir(
 
     # Load all agents from microagents directory
     logger.debug(f'Loading agents from {microagent_dir}')
-    if microagent_dir.exists():
-        # Collect .cursorrules file from repo root and .md files from microagents dir
-        cursorrules_files = []
-        if (microagent_dir.parent.parent / '.cursorrules').exists():
-            cursorrules_files = [microagent_dir.parent.parent / '.cursorrules']
 
+    # Always check for .cursorrules and AGENTS.md files in repo root, regardless of whether microagents_dir exists
+    special_files = []
+    repo_root = microagent_dir.parent.parent
+
+    # Check for .cursorrules
+    if (repo_root / '.cursorrules').exists():
+        special_files.append(repo_root / '.cursorrules')
+
+    # Check for AGENTS.md (case-insensitive)
+    for agents_filename in ['AGENTS.md', 'agents.md', 'AGENT.md', 'agent.md']:
+        agents_path = repo_root / agents_filename
+        if agents_path.exists():
+            special_files.append(agents_path)
+            break  # Only add the first one found to avoid duplicates
+
+    # Collect .md files from microagents directory if it exists
+    md_files = []
+    if microagent_dir.exists():
         md_files = [f for f in microagent_dir.rglob('*.md') if f.name != 'README.md']
 
-        # Process all files in one loop
-        for file in chain(cursorrules_files, md_files):
-            try:
-                agent = BaseMicroagent.load(file, microagent_dir)
-                if isinstance(agent, RepoMicroagent):
-                    repo_agents[agent.name] = agent
-                elif isinstance(agent, KnowledgeMicroagent):
-                    # Both KnowledgeMicroagent and TaskMicroagent go into knowledge_agents
-                    knowledge_agents[agent.name] = agent
-            except MicroagentValidationError as e:
-                # For validation errors, include the original exception
-                error_msg = f'Error loading microagent from {file}: {str(e)}'
-                raise MicroagentValidationError(error_msg) from e
-            except Exception as e:
-                # For other errors, wrap in a ValueError with detailed message
-                error_msg = f'Error loading microagent from {file}: {str(e)}'
-                raise ValueError(error_msg) from e
+    # Process all files in one loop
+    for file in chain(special_files, md_files):
+        try:
+            agent = BaseMicroagent.load(file, microagent_dir)
+            if isinstance(agent, RepoMicroagent):
+                repo_agents[agent.name] = agent
+            elif isinstance(agent, KnowledgeMicroagent):
+                # Both KnowledgeMicroagent and TaskMicroagent go into knowledge_agents
+                knowledge_agents[agent.name] = agent
+        except MicroagentValidationError as e:
+            # For validation errors, include the original exception
+            error_msg = f'Error loading microagent from {file}: {str(e)}'
+            raise MicroagentValidationError(error_msg) from e
+        except Exception as e:
+            # For other errors, wrap in a ValueError with detailed message
+            error_msg = f'Error loading microagent from {file}: {str(e)}'
+            raise ValueError(error_msg) from e
 
     logger.debug(
         f'Loaded {len(repo_agents) + len(knowledge_agents)} microagents: '

openhands/runtime/plugins/vscode/__init__.py

@@ -15,6 +15,8 @@ from openhands.runtime.plugins.requirement import Plugin, PluginRequirement
 from openhands.runtime.utils.system import check_port_available
 from openhands.utils.shutdown_listener import should_continue
 
+RUNTIME_USERNAME = os.getenv('RUNTIME_USERNAME')
+
 
 @dataclass
 class VSCodeRequirement(PluginRequirement):
@@ -37,7 +39,7 @@ class VSCodePlugin(Plugin):
             )
             return
 
-        if username not in ['root', 'openhands']:
+        if username not in filter(None, [RUNTIME_USERNAME, 'root', 'openhands']):
             self.vscode_port = None
             self.vscode_connection_token = None
             logger.warning(

openhands/runtime/utils/bash.py

@@ -20,6 +20,8 @@ from openhands.events.observation.commands import (
 from openhands.runtime.utils.bash_constants import TIMEOUT_MESSAGE_TEMPLATE
 from openhands.utils.shutdown_listener import should_continue
 
+RUNTIME_USERNAME = os.getenv('RUNTIME_USERNAME')
+
 
 def split_bash_commands(commands: str) -> list[str]:
     if not commands.strip():
@@ -193,7 +195,7 @@ class BashSession:
     def initialize(self) -> None:
         self.server = libtmux.Server()
         _shell_command = '/bin/bash'
-        if self.username in ['root', 'openhands']:
+        if self.username in list(filter(None, [RUNTIME_USERNAME, 'root', 'openhands'])):
             # This starts a non-login (new) shell for the given user
             _shell_command = f'su {self.username} -'
 

openhands/runtime/utils/command.py

@@ -1,3 +1,5 @@
+import os
+
 from openhands.core.config import OpenHandsConfig
 from openhands.core.logger import openhands_logger as logger
 from openhands.runtime.plugins import PluginRequirement
@@ -12,6 +14,9 @@ DEFAULT_PYTHON_PREFIX = [
 ]
 DEFAULT_MAIN_MODULE = 'openhands.runtime.action_execution_server'
 
+RUNTIME_USERNAME = os.getenv('RUNTIME_USERNAME')
+RUNTIME_UID = os.getenv('RUNTIME_UID')
+
 
 def get_action_execution_server_startup_command(
     server_port: int,
@@ -26,7 +31,10 @@ def get_action_execution_server_startup_command(
     sandbox_config = app_config.sandbox
     logger.debug(f'app_config {vars(app_config)}')
     logger.debug(f'sandbox_config {vars(sandbox_config)}')
-    logger.debug(f'override_user_id {override_user_id}')
+    logger.debug(f'RUNTIME_USERNAME {RUNTIME_USERNAME}, RUNTIME_UID {RUNTIME_UID}')
+    logger.debug(
+        f'override_username {override_username}, override_user_id {override_user_id}'
+    )
 
     # Plugin args
     plugin_args = []
@@ -40,10 +48,15 @@ def get_action_execution_server_startup_command(
             '--browsergym-eval-env'
         ] + sandbox_config.browsergym_eval_env.split(' ')
 
-    username = override_username or (
-        'openhands' if app_config.run_as_openhands else 'root'
+    username = (
+        override_username
+        or RUNTIME_USERNAME
+        or ('openhands' if app_config.run_as_openhands else 'root')
     )
-    user_id = override_user_id or (1000 if app_config.run_as_openhands else 0)
+    user_id = (
+        override_user_id or RUNTIME_UID or (1000 if app_config.run_as_openhands else 0)
+    )
+    logger.debug(f'username {username}, user_id {user_id}')
 
     base_cmd = [
         *python_prefix,

openhands/server/config/server_config.py

@@ -13,7 +13,6 @@ class ServerConfig(ServerConfigInterface):
     enable_billing = os.environ.get('ENABLE_BILLING', 'false') == 'true'
     hide_llm_settings = os.environ.get('HIDE_LLM_SETTINGS', 'false') == 'true'
     # This config is used to hide the microagent management page from the users for now. We will remove this once we release the new microagent management page.
-    hide_microagent_management = True
     settings_store_class: str = (
         'openhands.storage.settings.file_settings_store.FileSettingsStore'
     )
@@ -44,7 +43,6 @@ class ServerConfig(ServerConfigInterface):
             'FEATURE_FLAGS': {
                 'ENABLE_BILLING': self.enable_billing,
                 'HIDE_LLM_SETTINGS': self.hide_llm_settings,
-                'HIDE_MICROAGENT_MANAGEMENT': self.hide_microagent_management,
             },
         }
 

tests/unit/microagent/test_microagent_utils.py

@@ -364,3 +364,184 @@ def test_load_microagents_with_cursorrules(temp_microagents_dir_with_cursorrules
     assert cursorrules_agent.name == 'cursorrules'
     assert 'Always use TypeScript for new files' in cursorrules_agent.content
     assert cursorrules_agent.type == MicroagentType.REPO_KNOWLEDGE
+
+
+@pytest.fixture
+def temp_dir_with_cursorrules_only():
+    """Create a temporary directory with only .cursorrules file (no .openhands/microagents directory)."""
+    with tempfile.TemporaryDirectory() as temp_dir:
+        root = Path(temp_dir)
+
+        # Create .cursorrules file in repository root
+        cursorrules_content = """Always use Python for new files.
+Follow PEP 8 style guidelines."""
+        (root / '.cursorrules').write_text(cursorrules_content)
+
+        # Note: We intentionally do NOT create .openhands/microagents directory
+        yield root
+
+
+def test_load_cursorrules_without_microagents_dir(temp_dir_with_cursorrules_only):
+    """Test loading .cursorrules file when .openhands/microagents directory doesn't exist.
+
+    This test reproduces the bug where .cursorrules is only loaded when
+    .openhands/microagents directory exists.
+    """
+    # Try to load from non-existent microagents directory
+    microagents_dir = temp_dir_with_cursorrules_only / '.openhands' / 'microagents'
+
+    repo_agents, knowledge_agents = load_microagents_from_dir(microagents_dir)
+
+    # This should find the .cursorrules file even though microagents_dir doesn't exist
+    assert len(repo_agents) == 1  # Only .cursorrules
+    assert 'cursorrules' in repo_agents
+    assert len(knowledge_agents) == 0
+
+    # Check .cursorrules agent
+    cursorrules_agent = repo_agents['cursorrules']
+    assert isinstance(cursorrules_agent, RepoMicroagent)
+    assert cursorrules_agent.name == 'cursorrules'
+    assert 'Always use Python for new files' in cursorrules_agent.content
+    assert cursorrules_agent.type == MicroagentType.REPO_KNOWLEDGE
+
+
+def test_agents_md_file_load():
+    """Test loading AGENTS.md file as a RepoMicroagent."""
+    agents_content = """# Project Setup
+
+## Setup commands
+
+- Install deps: `npm install`
+- Start dev server: `npm run dev`
+- Run tests: `npm test`
+
+## Code style
+
+- TypeScript strict mode
+- Single quotes, no semicolons
+- Use functional patterns where possible"""
+
+    agents_path = Path('AGENTS.md')
+
+    # Test loading AGENTS.md file directly
+    agent = BaseMicroagent.load(agents_path, file_content=agents_content)
+
+    # Verify it's loaded as a RepoMicroagent
+    assert isinstance(agent, RepoMicroagent)
+    assert agent.name == 'agents'
+    assert agent.content == agents_content
+    assert agent.type == MicroagentType.REPO_KNOWLEDGE
+    assert agent.metadata.name == 'agents'
+    assert agent.source == str(agents_path)
+
+
+def test_agents_md_case_insensitive():
+    """Test that AGENTS.md loading is case-insensitive."""
+    agents_content = """# Development Guide
+
+Use TypeScript for all new files."""
+
+    test_cases = ['AGENTS.md', 'agents.md', 'AGENT.md', 'agent.md']
+
+    for filename in test_cases:
+        agents_path = Path(filename)
+        agent = BaseMicroagent.load(agents_path, file_content=agents_content)
+
+        assert isinstance(agent, RepoMicroagent)
+        assert agent.name == 'agents'
+        assert agent.content == agents_content
+        assert agent.type == MicroagentType.REPO_KNOWLEDGE
+
+
+@pytest.fixture
+def temp_dir_with_agents_md_only():
+    """Create a temporary directory with only AGENTS.md file (no .openhands/microagents directory)."""
+    with tempfile.TemporaryDirectory() as temp_dir:
+        root = Path(temp_dir)
+
+        # Create AGENTS.md file in repository root
+        agents_content = """# Development Guide
+
+## Setup commands
+
+- Install deps: `poetry install`
+- Start dev server: `poetry run python app.py`
+- Run tests: `poetry run pytest`
+
+## Code style
+
+- Python 3.12+
+- Follow PEP 8 guidelines
+- Use type hints everywhere"""
+        (root / 'AGENTS.md').write_text(agents_content)
+
+        # Note: We intentionally do NOT create .openhands/microagents directory
+        yield root
+
+
+def test_load_agents_md_without_microagents_dir(temp_dir_with_agents_md_only):
+    """Test loading AGENTS.md file when .openhands/microagents directory doesn't exist."""
+    # Try to load from non-existent microagents directory
+    microagents_dir = temp_dir_with_agents_md_only / '.openhands' / 'microagents'
+
+    repo_agents, knowledge_agents = load_microagents_from_dir(microagents_dir)
+
+    # This should find the AGENTS.md file even though microagents_dir doesn't exist
+    assert len(repo_agents) == 1  # Only AGENTS.md
+    assert 'agents' in repo_agents
+    assert len(knowledge_agents) == 0
+
+    # Check AGENTS.md agent
+    agents_agent = repo_agents['agents']
+    assert isinstance(agents_agent, RepoMicroagent)
+    assert agents_agent.name == 'agents'
+    assert 'Install deps: `poetry install`' in agents_agent.content
+    assert agents_agent.type == MicroagentType.REPO_KNOWLEDGE
+
+
+@pytest.fixture
+def temp_dir_with_both_cursorrules_and_agents():
+    """Create a temporary directory with both .cursorrules and AGENTS.md files."""
+    with tempfile.TemporaryDirectory() as temp_dir:
+        root = Path(temp_dir)
+
+        # Create .cursorrules file
+        cursorrules_content = """Always use Python for new files.
+Follow PEP 8 style guidelines."""
+        (root / '.cursorrules').write_text(cursorrules_content)
+
+        # Create AGENTS.md file
+        agents_content = """# Development Guide
+
+## Setup commands
+
+- Install deps: `poetry install`
+- Run tests: `poetry run pytest`"""
+        (root / 'AGENTS.md').write_text(agents_content)
+
+        yield root
+
+
+def test_load_both_cursorrules_and_agents_md(temp_dir_with_both_cursorrules_and_agents):
+    """Test loading both .cursorrules and AGENTS.md files when .openhands/microagents doesn't exist."""
+    # Try to load from non-existent microagents directory
+    microagents_dir = (
+        temp_dir_with_both_cursorrules_and_agents / '.openhands' / 'microagents'
+    )
+
+    repo_agents, knowledge_agents = load_microagents_from_dir(microagents_dir)
+
+    # This should find both files
+    assert len(repo_agents) == 2  # .cursorrules + AGENTS.md
+    assert 'cursorrules' in repo_agents
+    assert 'agents' in repo_agents
+    assert len(knowledge_agents) == 0
+
+    # Check both agents
+    cursorrules_agent = repo_agents['cursorrules']
+    assert isinstance(cursorrules_agent, RepoMicroagent)
+    assert 'Always use Python for new files' in cursorrules_agent.content
+
+    agents_agent = repo_agents['agents']
+    assert isinstance(agents_agent, RepoMicroagent)
+    assert 'Install deps: `poetry install`' in agents_agent.content