feat: debug functions

[cristipufu]

Description

The Three Main Pieces

1. _capture_frame_locals: "Take a snapshot of variables"
   When the code pauses at a breakpoint, you want to see what your variables look like. This function grabs all the local variables from the current point in execution and makes a safe copy. Simple things (strings, numbers, lists) are kept as-is. Anything complex gets converted to a string with repr() so it won't cause problems when sent over the network.

2. BreakpointController: "The traffic light"
   The code runs on a background thread.
   A trace function (_trace_callback) is hooked into Python via sys.settrace. This is a special Python mechanism that lets you get notified every single time a new line of code is about to run.
   When that line matches one of your breakpoints, the thread pauses (using threading.Event.wait()), takes a snapshot of variables, and puts a message in a queue saying "hey, I hit a breakpoint!"
   The outside world reads that message, shows it to the user, and eventually calls resume() to let the thread continue.

3. UiPathDebugFunctionsRuntime: "The wrapper"

It wraps another runtime (the "real" one that actually runs user code) and adds debugging on top. The key idea:

• No breakpoints? Just pass everything through to the inner runtime. No overhead.
• Breakpoints set? Create a BreakpointController, run the inner runtime inside a traced thread, and yield breakpoint events back to the caller.
• Resuming? Tell the existing controller to keep going and wait for the next event.

How Breakpoints Are Specified

Users pass breakpoints as strings:

• "42" → pause at line 42 of the main file
• "main.py:42" → pause at line 42 of main.py
• "*" → step mode, pause on every single line (like "step into" in a debugger)

Notes

• sys.settrace is a low-level Python feature: it literally lets you install a callback that Python calls before executing each line. It's how debuggers like pdb work under the hood. The "call" event means "a function is being entered" (and the callback decides whether to trace inside it), while "line" means "a new line is about to execute" (where we check for breakpoints).
• Step mode pauses on every line of project code and traces into function calls:
  • call event: Decides whether to trace into a function. In step mode, it enters all project files but skips third-party code.
  • line event: Pauses execution on every line of every project file, captures local variables, and waits for a resume signal.
  • _is_project_file() ensures only user code is traced, preventing stepping into standard library or dependency internals.

Development Package

• Use uipath pack --nolock to get the latest dev build from this PR (requires version range).
• Add this package as a dependency in your pyproject.toml:

[project]
dependencies = [
  # Exact version:
  "uipath==2.8.3.dev1012804637",

  # Any version from PR
  "uipath>=2.8.3.dev1012800000,<2.8.3.dev1012810000"
]

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true

[tool.uv.sources]
uipath = { index = "testpypi" }

[tool.uv]
override-dependencies = [
    "uipath>=2.8.3.dev1012800000,<2.8.3.dev1012810000",
]