feat: add uipath trace CLI command for trajectory visualization

Add a new `uipath trace` command that reads JSONL trace files (from
`uipath run --trace-file` or `uipath eval --trace-file`) and eval
verbose JSON output, rendering a Rich span tree showing the agent's
execution trajectory.

Features:
- Span tree with timing, status icons, and smart labels (LLM/tool/generic)
- Key attributes displayed by default (input, output, tokens, model name)
- `--full` mode shows all attributes with no truncation
- `--no-input`/`--no-output` for structural overview
- `--name` filter prunes the tree to matching spans + ancestors
- `--contains` extracts full subtrees where any descendant matches,
  useful for finding specific eval runs across a trace file
- `--span-type` and `--status` filters
- `--eval-id` to pick a specific evaluation from verbose JSON output
- Auto-detects JSONL vs eval JSON format

Includes 66 tests covering loading, tree building, filtering, rendering,
and CLI integration.

Author: DragosBobolea

README.md

@@ -26,6 +26,7 @@ This [quickstart guide](https://uipath.github.io/uipath-python/) walks you throu
     -   [Authentication](#authentication)
     -   [Initialize a Project](#initialize-a-project)
     -   [Debug a Project](#debug-a-project)
+    -   [Visualize Traces](#visualize-traces)
     -   [Package a Project](#package-a-project)
     -   [Publish a Package](#publish-a-package)
 -   [Project Structure](#project-structure)
@@ -155,6 +156,18 @@ uipath run ENTRYPOINT [INPUT]
 
 Executes a Python script with the provided JSON input arguments.
 
+### Visualize Traces
+
+```bash
+# Capture a trace
+uipath run main '{"query": "hello"}' --trace-file traces.jsonl
+
+# Visualize the agent trajectory
+uipath trace traces.jsonl
+```
+
+Renders a tree view of the agent's execution showing tool calls, LLM invocations, inputs/outputs, and timing. Also works with eval traces (`uipath eval --trace-file`) — use `--contains "function_name"` to find specific runs across an eval set.
+
 ### Package a Project
 
 ```bash

packages/uipath/README.md

@@ -26,6 +26,7 @@ This [quickstart guide](https://uipath.github.io/uipath-python/) walks you throu
     -   [Authentication](#authentication)
     -   [Initialize a Project](#initialize-a-project)
     -   [Debug a Project](#debug-a-project)
+    -   [Visualize Traces](#visualize-traces)
     -   [Package a Project](#package-a-project)
     -   [Publish a Package](#publish-a-package)
 -   [Project Structure](#project-structure)
@@ -155,6 +156,18 @@ uipath run ENTRYPOINT [INPUT]
 
 Executes a Python script with the provided JSON input arguments.
 
+### Visualize Traces
+
+```bash
+# Capture a trace
+uipath run main '{"query": "hello"}' --trace-file traces.jsonl
+
+# Visualize the agent trajectory
+uipath trace traces.jsonl
+```
+
+Renders a tree view of the agent's execution showing tool calls, LLM invocations, inputs/outputs, and timing. Also works with eval traces (`uipath eval --trace-file`) — use `--contains "function_name"` to find specific runs across an eval set.
+
 ### Package a Project
 
 ```bash

packages/uipath/docs/cli/index.md

@@ -143,6 +143,43 @@ uipath run agent '{\"topic\":\"uipath\"}'
 ```
 ---
 
+::: mkdocs-click
+    :module: uipath._cli
+    :command: trace
+    :depth: 1
+    :style: table
+
+Visualize an agent execution trace. Reads JSONL trace files produced by `uipath run --trace-file` or `uipath eval --trace-file`, and renders a span tree showing the agent's trajectory.
+
+<!-- termynal -->
+
+```shell
+> uipath trace traces.jsonl
+Trace abcdef12…34567890
+└── agent (12.5s) ✓
+    ├── input: {"messages": [{"role": "user", "content": "Book a flight..."}]}
+    ├── LLM (gpt-4o) (2.2s) ✓
+    │   └── tokens: prompt=847, completion=156, total=1003
+    ├── 🔧 search_flights (1.7s) ✓
+    │   ├── input: {"origin": "SFO", "destination": "NRT"}
+    │   └── output: {"flights": [...]}
+    ├── LLM (gpt-4o) (1.8s) ✓
+    │   └── tokens: prompt=1456, completion=203, total=1659
+    └── 🔧 book_flight (1.2s) ✓
+        └── output: {"confirmation": {"booking_ref": "BK-UA837"}}
+9 spans total
+```
+
+/// tip
+Use `--contains` to search across eval traces and extract full agent trajectories where a specific function was called:
+```console
+uipath eval main eval-set.json --trace-file traces.jsonl
+uipath trace traces.jsonl --contains "get_random*"
+```
+///
+
+---
+
 ::: mkdocs-click
     :module: uipath._cli
     :command: pack

packages/uipath/src/uipath/_cli/__init__.py

@@ -45,6 +45,7 @@
     "server": "cli_server",
     "register": "cli_register",
     "debug": "cli_debug",
+    "trace": "cli_trace",
     "assets": "services.cli_assets",
     "buckets": "services.cli_buckets",
     "context-grounding": "services.cli_context_grounding",