Merge branch 'main' into feat/add-memory-space-resource-overwrite

Author: mjnovice

packages/uipath/docs/cli/index.md

@@ -308,3 +308,92 @@ Processing: uipath.json
 File 'uipath.json' is up to date
 ✓  Project pulled successfully
 ```
+---
+
+::: mkdocs-click
+    :module: uipath._cli
+    :command: debug
+    :depth: 1
+    :style: table
+
+Runs your agent under the debug runtime, with a debug bridge attached. Locally, the bridge is the interactive **console** (read commands from stdin, stop at breakpoints). In the cloud, the bridge is **SignalR** (driven by Studio Web / Orchestrator). The `--attach` flag lets you override that default, including `none` for executors that need the debug command's surrounding behavior (bindings fetch, state streaming) but cannot speak the interactive debug protocol.
+
+### Attach modes
+
+| Mode | When to use |
+|------|-------------|
+| `signalr` | Remote runs driven by Studio Web / Orchestrator. Default when `job_id` is set. |
+| `console` | Local interactive debugging from the terminal. Default when no `job_id`. |
+| `none` | Run under the debug command without attaching a debugger. No wait-for-start gate, no breakpoints, no step mode. |
+
+/// info
+`--attach` selects the **debug bridge**. It's unrelated to `--debug`, which starts a `debugpy` server for Python-level breakpoints in your IDE. The two can be combined.
+///
+
+<!-- termynal -->
+
+```shell
+> uipath debug main '{"message": "test"}'
+Debug Mode Commands
+  c, continue     Continue until next breakpoint
+  s, step         Step to next node
+  b <node>        Set breakpoint at <node>
+  l, list         List all breakpoints
+  r <node>        Remove breakpoint at <node>
+  h, help         Show help
+  q, quit         Exit debugger
+▶ START
+> b analyze_sentiment
+✓ Breakpoint set at: analyze_sentiment
+> c
+────────────────────────────────────────
+■ BREAKPOINT analyze_sentiment (before)
+Next: analyze_sentiment
+────────────────────────────────────────
+> s
+● analyze_sentiment
+> c
+✓ Execution completed
+```
+---
+
+::: mkdocs-click
+    :module: uipath._cli
+    :command: eval
+    :depth: 1
+    :style: table
+
+Runs an evaluation set against your agent. Entry point and eval set are auto-discovered from the project if not passed explicitly. Evaluations run in parallel (see `--workers`) and, unless `--no-report` is passed, results are reported back to Studio Web when `UIPATH_PROJECT_ID` is set.
+
+### Common flags
+
+| Flag | Purpose |
+|------|---------|
+| `--eval-ids` | Run only a subset of evaluations by id. |
+| `--workers` | Parallel workers for running evaluations (default 1). |
+| `--no-report` | Skip reporting results back to UiPath. |
+| `--enable-mocker-cache` | Cache LLM mocker responses across runs. |
+| `--input-overrides` | Per-eval input overrides, merged into the eval's input. |
+| `--trace-file` | Write OpenTelemetry traces to a JSONL file for offline inspection. |
+| `--resume` | Resume evaluation from a previous suspended state. |
+
+<!-- termynal -->
+
+```shell
+> uipath eval
+⠋ Running evaluations ...
+  Weather in Paris
+  LLM Judge Output       0.7
+  Tool Call Arguments    1.0
+  Tool Call Count        1.0
+  Tool Call Order        1.0
+
+Evaluation Results
+┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
+┃  Evaluation        ┃  LLM Judge Output  ┃  Tool Call Args    ┃  Tool Call Count   ┃  Tool Call Order   ┃
+┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
+│  Weather in Paris  │               0.7  │               1.0  │               1.0  │               1.0  │
+├────────────────────┼────────────────────┼────────────────────┼────────────────────┼────────────────────┤
+│  Average           │               0.7  │               1.0  │               1.0  │               1.0  │
+└────────────────────┴────────────────────┴────────────────────┴────────────────────┴────────────────────┘
+```

packages/uipath/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "uipath"
-version = "2.10.53"
+version = "2.10.54"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
 dependencies = [
   "uipath-core>=0.5.8, <0.6.0",
-  "uipath-runtime>=0.10.0, <0.11.0",
+  "uipath-runtime>=0.10.1, <0.11.0",
   "uipath-platform>=0.1.13, <0.2.0",
   "click>=8.3.1",
   "httpx>=0.28.1",

packages/uipath/src/uipath/_cli/_debug/_bridge.py

@@ -19,9 +19,15 @@
     UiPathRuntimeResult,
     UiPathRuntimeStatus,
 )
-from uipath.runtime.debug import UiPathDebugProtocol, UiPathDebugQuitError
+from uipath.runtime.debug import (
+    DetachedDebugBridge,
+    UiPathDebugProtocol,
+    UiPathDebugQuitError,
+)
 from uipath.runtime.events import UiPathRuntimeStateEvent, UiPathRuntimeStatePhase
 
+DebugAttachMode = Literal["signalr", "console", "none"]
+
 logger = logging.getLogger(__name__)
 
 
@@ -871,18 +877,27 @@ def get_remote_debug_bridge(context: UiPathRuntimeContext) -> UiPathDebugProtoco
 
 
 def get_debug_bridge(
-    context: UiPathRuntimeContext, verbose: bool = True
+    context: UiPathRuntimeContext,
+    verbose: bool = True,
+    attach: DebugAttachMode | None = None,
 ) -> UiPathDebugProtocol:
     """Factory to get appropriate debug bridge based on context.
 
     Args:
         context: The runtime context containing debug configuration.
         verbose: If True, console bridge shows all state updates. If False, only breakpoints.
+        attach: Explicit attach mode. When None, falls back to
+            ``context.job_id``-based selection.
 
     Returns:
         An instance of UiPathDebugBridge suitable for the context.
     """
-    if context.job_id:
+    if attach == "none":
+        return DetachedDebugBridge()
+    if attach == "signalr":
         return get_remote_debug_bridge(context)
-    else:
+    if attach == "console":
         return ConsoleDebugBridge(verbose=verbose)
+    if context.job_id:
+        return get_remote_debug_bridge(context)
+    return ConsoleDebugBridge(verbose=verbose)

packages/uipath/src/uipath/_cli/cli_debug.py

@@ -1,10 +1,11 @@
 import asyncio
 import logging
+from typing import cast, get_args
 
 import click
 
 from uipath._cli._chat._bridge import get_chat_bridge
-from uipath._cli._debug._bridge import get_debug_bridge
+from uipath._cli._debug._bridge import DebugAttachMode, get_debug_bridge
 from uipath._cli._utils._debug import setup_debugging
 from uipath._cli._utils._studio_project import StudioClient
 from uipath.core.tracing import UiPathTraceManager
@@ -64,6 +65,15 @@
     default=5678,
     help="Port for the debug server (default: 5678)",
 )
+@click.option(
+    "--attach",
+    type=click.Choice(list(get_args(DebugAttachMode)), case_sensitive=False),
+    default=None,
+    help=(
+        "Debugger attach mode. Defaults to 'signalr' for cloud runs, "
+        "'console' for local runs."
+    ),
+)
 @track_command("debug")
 def debug(
     entrypoint: str | None,
@@ -74,13 +84,18 @@ def debug(
     output_file: str | None,
     debug: bool,
     debug_port: int,
+    attach: str | None,
 ) -> None:
     """Debug the project."""
     input_file = file or input_file
     # Setup debugging if requested
     if not setup_debugging(debug, debug_port):
         console.error(f"Failed to start debug server on port {debug_port}")
 
+    attach_mode: DebugAttachMode | None = (
+        cast(DebugAttachMode, attach.lower()) if attach else None
+    )
+
     result = Middlewares.next(
         "debug",
         entrypoint,
@@ -90,6 +105,7 @@ def debug(
         output_file=output_file,
         debug=debug,
         debug_port=debug_port,
+        attach=attach_mode,
     )
 
     if result.error_message:
@@ -141,7 +157,9 @@ async def execute_debug_runtime():
 
                         async def execute_debug_runtime():
                             chat_runtime: UiPathRuntimeProtocol | None = None
-                            debug_bridge: UiPathDebugProtocol = get_debug_bridge(ctx)
+                            debug_bridge: UiPathDebugProtocol = get_debug_bridge(
+                                ctx, attach=attach_mode
+                            )
 
                             runtime = await factory.new_runtime(
                                 entrypoint,

packages/uipath/tests/cli/test_debug_bridge_selection.py

@@ -0,0 +1,64 @@
+"""Tests for `get_debug_bridge()` selection matrix.
+
+Locks in the non-breaking-change contract: absence of `attach` preserves the
+legacy `job_id`-based selection. Explicit `attach` overrides that selection.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from uipath._cli._debug._bridge import (
+    ConsoleDebugBridge,
+    SignalRDebugBridge,
+    get_debug_bridge,
+)
+from uipath.runtime import UiPathRuntimeContext
+from uipath.runtime.debug import DetachedDebugBridge
+
+
+def _ctx(**overrides) -> UiPathRuntimeContext:
+    return UiPathRuntimeContext(**overrides)
+
+
+def test_attach_none_returns_detached_bridge_without_job_id():
+    bridge = get_debug_bridge(_ctx(), attach="none")
+    assert isinstance(bridge, DetachedDebugBridge)
+
+
+def test_attach_none_returns_detached_bridge_even_when_job_id_set(monkeypatch):
+    """'none' wins over job_id — this is the whole point of the flag."""
+    monkeypatch.setenv("UIPATH_URL", "https://cloud.uipath.com")
+    bridge = get_debug_bridge(_ctx(job_id="job-123"), attach="none")
+    assert isinstance(bridge, DetachedDebugBridge)
+
+
+def test_attach_signalr_forces_signalr_bridge(monkeypatch):
+    monkeypatch.setenv("UIPATH_URL", "https://cloud.uipath.com")
+    bridge = get_debug_bridge(_ctx(job_id="job-123"), attach="signalr")
+    assert isinstance(bridge, SignalRDebugBridge)
+
+
+def test_attach_console_forces_console_bridge_even_when_job_id_set(monkeypatch):
+    monkeypatch.setenv("UIPATH_URL", "https://cloud.uipath.com")
+    bridge = get_debug_bridge(_ctx(job_id="job-123"), attach="console")
+    assert isinstance(bridge, ConsoleDebugBridge)
+
+
+def test_legacy_selection_signalr_when_job_id_set_and_no_attach(monkeypatch):
+    """Non-breaking change assertion: absence of `attach` preserves today's behavior."""
+    monkeypatch.setenv("UIPATH_URL", "https://cloud.uipath.com")
+    bridge = get_debug_bridge(_ctx(job_id="job-123"))
+    assert isinstance(bridge, SignalRDebugBridge)
+
+
+def test_legacy_selection_console_when_no_job_id_and_no_attach():
+    """Non-breaking change assertion: absence of `attach` preserves today's behavior."""
+    bridge = get_debug_bridge(_ctx())
+    assert isinstance(bridge, ConsoleDebugBridge)
+
+
+def test_attach_signalr_without_job_id_raises():
+    """Explicit signalr without job_id is a user error — surface it loudly."""
+    with pytest.raises(ValueError, match="UIPATH_URL and UIPATH_JOB_KEY"):
+        get_debug_bridge(_ctx(), attach="signalr")