fix(cli): warn instead of erroring when several frameworks are installed

Environments with more than one agent framework package scaffolded fine
before `--type` existed — the first discovered integration claimed the
project. Turning that into an error would be a breaking change, so the
old outcome stays: `uipath new` warns, names all the installed
frameworks and the one it picked, and scaffolds with the first
discovered. `--agent-framework` remains the way to choose deliberately.

The pick is dispatched to that framework's middleware directly, so the
warning always names the integration that actually scaffolds.
Discovery order is the entry-point order (a filesystem accident, stable
per environment); listings shown to the user stay sorted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: vldcmp-uipath

packages/uipath/docs/cli/index.md

@@ -83,9 +83,9 @@ Scaffolds a project in the current directory. `--type` selects what gets created
 |----------------------------------|------------------------|------------------------------|
 | none | coded function project | error: install an agent framework |
 | one | that framework's coded agent project | that framework's coded agent project |
-| several | error: pick one with `--agent-framework` | error: pick one with `--agent-framework` |
+| several | warns, scaffolds with the first discovered | warns, scaffolds with the first discovered |
 
-With one framework installed there is nothing to choose, so `uipath new` uses it. With several, it cannot tell which you meant and asks you to name one:
+With one framework installed there is nothing to choose, so `uipath new` uses it. With several, it warns and scaffolds with the first one discovered — pass `--agent-framework` to choose deliberately:
 
 ```shell
 uipath new my-agent --type agent --agent-framework uipath-langchain

packages/uipath/docs/core/agents.md

@@ -95,7 +95,7 @@ The example below uses LangChain. Swap `uipath-langchain` for the framework of y
 uipath new agent --type agent
 ```
 
-With several framework integrations installed in the same environment, name the one to scaffold with:
+With several framework integrations installed in the same environment, `uipath new` warns and uses the first one discovered; name the one you want instead with:
 
 ```shell
 uipath new agent --type agent --agent-framework uipath-langchain

packages/uipath/docs/core/studio_web.md

@@ -224,7 +224,7 @@ Selected tenant: Tenant1
 That's it, your agent should now be visible in Studio Web.
 
 /// info
-`uipath new` defaults to `--type auto`, which lets the installed framework integration claim the scaffold. Pass `--type agent` to require an agent project — it fails rather than creating a function project when no framework is installed. With several integrations installed, name the one to scaffold with: `uipath new agent --type agent --agent-framework uipath-langchain`.
+`uipath new` defaults to `--type auto`, which lets the installed framework integration claim the scaffold. Pass `--type agent` to require an agent project — it fails rather than creating a function project when no framework is installed. With several integrations installed, `uipath new` warns and uses the first one discovered; pick explicitly with `uipath new agent --type agent --agent-framework uipath-langchain`.
 ///
 
 #### Coded Function

packages/uipath/src/uipath/_cli/cli_new.py

@@ -62,7 +62,7 @@ def generate_uipath_json(target_directory):
 
 
 def installed_agent_frameworks() -> list[AgentFramework]:
-    """Agent frameworks that can scaffold a project in this environment."""
+    """Agent frameworks that can scaffold a project, in discovery order."""
     packages: dict[str, str] = {}
     for entry_point in importlib.metadata.entry_points(group="uipath.middlewares"):
         if entry_point.dist is not None:
@@ -73,7 +73,7 @@ def installed_agent_frameworks() -> list[AgentFramework]:
         package = packages.get(middleware.__module__.split(".")[0])
         if package is not None:
             frameworks.append(AgentFramework(package=package, scaffold=middleware))
-    return sorted(frameworks, key=lambda framework: framework.package)
+    return frameworks
 
 
 def _select_agent_framework(
@@ -85,7 +85,9 @@ def _select_agent_framework(
             return framework
 
     installed = (
-        "Installed: " + ", ".join(framework.package for framework in frameworks) + "."
+        "Installed: "
+        + ", ".join(sorted(framework.package for framework in frameworks))
+        + "."
         if frameworks
         else "No agent framework is installed."
     )
@@ -108,13 +110,15 @@ def _scaffold_agent(name: str, agent_framework: str | None) -> MiddlewareResult:
         return _select_agent_framework(installed, agent_framework).scaffold(name)
 
     if len(installed) > 1:
-        console.error(
+        first = installed[0]
+        console.warning(
             "Multiple agent frameworks are installed: "
             + ", ".join(framework.package for framework in installed)
-            + f".\nPick one with `uipath new {name} --type agent "
-            "--agent-framework <framework>`, or run "
-            f"`uipath new {name} --type function` to create a function project."
+            + f".\nScaffolding with the first one discovered: '{first.package}'. "
+            f"To pick a different one, run `uipath new {name} --type agent "
+            "--agent-framework <framework>`."
         )
+        return first.scaffold(name)
 
     return Middlewares.next("new", name)
 
@@ -137,8 +141,8 @@ def _scaffold_agent(name: str, agent_framework: str | None) -> MiddlewareResult:
     "agent_framework",
     default=None,
     help="Agent framework to scaffold with, named by its package (e.g. "
-    "`uipath-langchain`). Only valid together with `--type agent`; needed "
-    "when several frameworks are installed, optional otherwise.",
+    "`uipath-langchain`). Only valid together with `--type agent`; picks "
+    "which framework scaffolds when several are installed.",
 )
 @track_command("new")
 def new(name: str, project_type: str, agent_framework: str | None):

packages/uipath/tests/cli/test_new.py

@@ -183,30 +183,38 @@ def test_new_type_agent_without_a_framework_errors(
                 assert not os.path.exists("main.py")
                 assert not os.path.exists("uipath.json")
 
-    def test_new_multiple_frameworks_installed_require_a_choice(
+    def test_new_multiple_frameworks_warn_and_use_the_first_discovered(
         self, runner: CliRunner, temp_dir: str
     ) -> None:
-        """Several frameworks installed must not resolve by registration order."""
+        """Several frameworks installed: warn, then scaffold with the first.
+
+        Erroring here would break environments that scaffolded fine before
+        `--type` existed, so the old behaviour stays the default and the
+        warning points at `--agent-framework` for choosing explicitly.
+        """
         with runner.isolated_filesystem(temp_dir=temp_dir):
             for extra_args in ([], ["--type", "auto"], ["--type", "agent"]):
+                first = _framework("uipath-llamaindex")
+                other = _framework("uipath-langchain")
                 with (
                     patch("uipath._cli.cli_new.Middlewares.next") as mock_middleware,
                     patch(
                         "uipath._cli.cli_new.installed_agent_frameworks",
-                        return_value=[
-                            _framework("uipath-langchain"),
-                            _framework("uipath-llamaindex"),
-                        ],
+                        return_value=[first, other],
                     ),
                 ):
                     result = runner.invoke(cli, ["new", "my_agent"] + extra_args)
-                    assert result.exit_code == 1
+                    assert result.exit_code == 0
                     assert "Multiple agent frameworks are installed" in result.output
-                    assert "uipath-langchain, uipath-llamaindex" in result.output
+                    # listed in discovery order, so the first named is the pick
+                    assert "uipath-llamaindex, uipath-langchain" in result.output
+                    assert "first one discovered: 'uipath-llamaindex'" in result.output
                     assert "--agent-framework" in result.output
-                    assert "--type function" in result.output
-                    assert not os.path.exists("main.py")
+                    _scaffold_of(first).assert_called_once_with("my_agent")
+                    _scaffold_of(other).assert_not_called()
                     mock_middleware.assert_not_called()
+                    # claimed by the framework: no base function scaffold
+                    assert not os.path.exists("uipath.json")
 
     def test_agent_framework_scaffolds_with_the_chosen_one_only(
         self, runner: CliRunner, temp_dir: str