feat(eval): add --simulation flag to uipath debug

[ajay-kesavan]

Summary

Mirrors the --simulation flag introduced for uipath run in #1624 onto uipath debug, so a simulation config can be passed inline (same JSON schema as simulation.json) without writing it to disk.

• Adds --simulation option + parameter to cli_debug.py
• Validates the JSON via SimulationConfig.model_validate_json (uses pydantic.ValidationError for surfacing errors)
• When --simulation is provided, builds the mocking context via build_mocking_context(simulation_config, agent_model)
• When --simulation is omitted, the existing load_simulation_config() fallback (reads simulation.json from cwd) is preserved — this is the one behavioral difference from run, which has no file-based fallback

Test plan

• ruff check and ruff format --check pass on the modified file
• Unit tests for debug --simulation (mirroring the TestRunSimulation class added to tests/cli/test_run.py in feat(eval): add runtime simulation via --simulation flag #1624) are not included in this PR — happy to add in a follow-up if reviewers want them here

Scope notes

This PR only mirrors the CLI flag. The sample (runtime-simulations-agent) and integration testcase (simulation-testcase) added in #1624 exercise uipath run and are not duplicated for debug since the underlying build_mocking_context plumbing they cover is shared.

🤖 Generated with Claude Code

[AAgnihotry]

can you please add some tests here

[ajay-kesavan]

Screen.Recording.2026-05-19.at.3.54.08.PM.mov

[ajay-kesavan]

simulation-agent.zip

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
91.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chibionos]

PR #1632 Review — --simulation flag on uipath debug

Verdict: ✅ Approve after rebase. Clean mirror of the uipath run --simulation flag (#1624). I checked out the head, ran the suite, and traced the flow.

✅ Verified working

• 18/18 tests pass (tests/cli/test_debug_simulation.py), including the 3 new TestDebugSimulationFlag tests.
• ruff check + ruff format --check clean.
• Closure capture of simulation_config into the nested execute_debug_runtime is correct.
• except (ValidationError, ValueError) matches cli_run.py exactly; the console.error() early-exit (NoReturn → SystemExit) correctly prevents reaching Middlewares.next — and the test's assert not factory_get.called confirms it.
• All five patch(...) targets resolve to real names in cli_debug's namespace.

🔵 Before merge

• Branch is CONFLICTING and bumps 2.10.67 → 2.10.68; rebase and resolve the version-line conflict (note #1674 also bumps the version).

Two minor inline observations below — nothing blocking.

---

Adversarial + deep-review pass; verified on the PR head.

[Chibionos]

🔵 exclude-newer flipped to epoch zero

exclude-newer changed from the real timestamp 2026-05-17T... to 0001-01-01T00:00:00Z. This is a uv-version artifact and is harmless, but confirm it came from an intentional uv lock regeneration rather than a stray downgrade of the uv toolchain — it can subtly change dependency resolution on the next lock.

[Chibionos]

🔵 unreachable return

console.error() is NoReturn (raises SystemExit), so this return never executes. Harmless and consistent with the existing pattern at :138; fine to leave. Flagging only so it's a conscious choice.