feat(cli): report the real exit code and really stop what uipath server runs

[robert-ursu]

Pairs with UiPath/hdens#7868, which makes the handler send the stop, act on the answer, and kill and restart the server when a job cannot be stopped.

Why

Exit codes

A failed execution inside uipath server was reported as a success, on both transports:

1. ConsoleLogger.error ends in click.get_current_context().exit(1). Under standalone_mode=False click returns that code instead of raising (click/core.py, except Exit). _run_command_isolated took the return value as the result and hard-coded ExitCode: 0. Every console.error path (runtime errors, unexpected exceptions, bad --simulation) came back as exit code 0.
2. The HTTP /jobs/{key}/start reply had no exitCode. The .NET PythonRuntimeClient reads exitCode into an int and treats a missing one as 0, so every HTTP 200 counted as a success, even when the body said success: false.

The handler usually overrides the exit code with the status in output.json or the IPC result. The exit code decides the outcome when neither exists: failures before or outside UiPathRuntimeContext, and crashes.

Stop

uipath server could not stop what it was running:

• IPC StopJob was a no-op that answered True.
• HTTP had no stop route at all.
• Cancelling the awaiting task was worse than doing nothing. When the handler's IPC connection drops, uipath-ipc cancels every in-flight handler (uipath_ipc/client/connection.py, _teardown). await asyncio.to_thread(...) raised, the lock was released and env/cwd were restored while the execution's thread kept running. The next execution then ran concurrently in a mutated process.

What: exit codes

• _server_core: an int returned by cmd.main is the exit code. run, debug and eval never return an int of their own.
• HTTP start reply: exitCode is added to every response. An unchanged handler becomes correct against this runtime with no .NET change.
• _job_api: a result status the sink does not know is reported as Faulted, not Successful. "stopped" maps to the wire's Stopped (4), which the handler already accepts.
• uipath run / uipath eval: entrypoint or eval-set discovery failure exits 1 instead of 0.

What: how an execution is stopped

run, debug and eval each drive their own event loop on the worker thread, so an execution is an event loop. They now call run_execution_loop instead of asyncio.run. It publishes the loop and its root task to the ExecutionControl carried on a ContextVar. Outside the server (uipath run on a terminal) it is asyncio.run unchanged.

stop_execution(job_key, resume_version, force) is shared by IPC StopJob and the new POST /jobs/{key}/stop (200 {"stopped": bool}).

Both a stop and a kill are cooperative and run the same sequence; a kill (forceStop: true) only has tighter windows:

1. Cancel the execution's root task. The runtime unwinds cooperatively, and UiPathRuntimeContext.__exit__ still writes the result. Wait 30 s, or 5 s for a kill.
2. Cancel every task on the execution's loop. This gives up on a clean cleanup. Wait 10 s, or 5 s for a kill.
3. Answer False if the execution still runs. It is typically blocked inside a call that cancellation cannot reach (a sync socket read, a lock wait, a busy loop with no await), and only ending the process stops it. Whether to do that is the handler's call, since the process and the execution instance belong to it.

So a stop answers within about 40 s and a kill within about 10 s, both within the handler's 60 s StopJobTimeout.

Cases that answer True:

• A queued execution (waiting for the lock) is dropped before it runs.
• An unknown job key, or a live run with a different resume version, is not running. Answering False there would invite the handler to kill a resumed run for a stop aimed at the previous one.

The lock waits for the thread

_run_command_isolated now returns or raises only once the worker thread has exited. Cancelling the caller, for example on a dropped connection, stops the execution. The CancelledError is re-raised only after that, so the lock, env and cwd are never handed on while the job still runs.

The job-scope teardown also completes before the env is restored, so the xfail in test_server_job_core.py is removed.

Outcomes

How the execution ended	ExitCode	Error
Stopped on request	143	Stopped on request
Its own code let a CancelledError escape	1 (unexpected)	The execution cancelled itself
Otherwise	click's exit code, 0 on success	Exit code: N

A stopped execution's result document still says Faulted/ERROR_CancelledError; that is written by uipath-runtime. The handler reports Stopped for an Orchestrator stop regardless of what the runtime wrote.

Worth a careful look

• The worker is a plain run_in_executor future, not a task. A task re-raises the execution's SystemExit into the server loop, and _run_command_isolated turns SystemExit into an exit code.
• An execution waiting on its own to_thread work (sync LangGraph nodes, sync HTTP clients) runs its finally at once. But the execution's asyncio.Runner does not close until that call returns. run_execution_loop withdraws the loop before the runner closes, so the sweep in step 2 cannot cancel the runner's wait on those threads, which would leak them. Such an execution answers False if the call outlives the grace.
• ExecutionControl.cancel() delivers at most once. A stop followed by a force stop is ordinary, and a second delivery would land inside the cleanup that writes output.json.

Testing

• uv run pytest tests/cli: 1521 passed, 1 skipped, with coverage on as in CI.
• ruff check, ruff format --check and mypy are clean.
• New tests are in tests/cli/test_server_cancellation.py (18). They use click commands shaped like the real ones and cover:
  • a running execution stops, its cleanup runs and the lock is freed;
  • a stop that arrives before the execution has a loop is applied when it gets one;
  • a repeated or forced stop does not abort a slow cleanup;
  • a force stop gives up within its own, shorter window;
  • an execution waiting on a nested thread stops once that call returns;
  • an uninterruptible execution answers False and keeps the lock until its thread exits;
  • a self-inflicted cancel is a fault;
  • a queued execution is dropped, and cancelling a queued execution's caller does not leak the lock;
  • a stop for another resume version leaves the live run alone;
  • a cancelled caller stops the execution and waits for its thread, keeping the lock and the execution's env meanwhile;
  • IPC StopJob stops a running RunJob;
  • the HTTP stop route stops a running /start and validates its body.
• Exit-code tests:
  • a real click command that calls ConsoleLogger.error reports exit code 1 through _run_command_isolated;
  • an execution started over HTTP whose entrypoint raises replies success: false, exitCode: 1;
  • an unknown result status maps to Faulted, and "stopped" to Stopped;
  • discovery failures exit 1.
• Version 2.14.32 → 2.14.33.

🤖 Generated with Claude Code

Development Packages

uipath

[project]
dependencies = [
  # Exact version (copy-paste ready):
  "uipath==2.14.33.dev1018427770",

  # Any version from this PR (uncomment to use a range instead):
  # "uipath>=2.14.33.dev1018420000,<2.14.33.dev1018430000",
]

[[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" }

[github-actions]

🚨 Heads up: uipath-integrations cross-tests are FAILING 🚨

Your changes may break one or more integrations in uipath-integrations-python:

• uipath-openai-agents
• uipath-google-adk
• uipath-agent-framework
• uipath-llamaindex
• uipath-pydantic-ai

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

[Copilot]

Copilot review overview

🟡 Changes recommended

A cancellation race can incorrectly report self-cancellation as an externally requested stop, and HTTP stop validation has type-safety gaps.

Review effort: Balanced
Findings: 3 · 1

Open (4)

• Track cancellation delivery before classifying late stops · New
• Reject boolean resumeVersion values · New
• Validate forceStop is boolean · New
• Document run_in_executor usage accurately · New

What changed in this PR

Improves CLI server exit-code reporting and adds cooperative job cancellation across HTTP and IPC transports.

Changes:

• Propagates real Click exit codes and maps runtime statuses safely.
• Adds shared execution control and stop endpoints.
• Expands cancellation, transport, and discovery-failure tests.

File	Description
packages/​uipath/​pyproject.toml	Bumps package version.
packages/​uipath/​uv.lock	Updates locked package version.
packages/​uipath/​src/​uipath/​_cli/​_execution_control.py	Adds cross-thread execution cancellation.
packages/​uipath/​src/​uipath/​_cli/​_server_core.py	Tracks, stops, and reports executions.
packages/​uipath/​src/​uipath/​_cli/​_job_api.py	Maps stopped and unknown statuses.
packages/​uipath/​src/​uipath/​_cli/​cli_server.py	Adds HTTP stop and exit-code responses.
packages/​uipath/​src/​uipath/​_cli/​cli_server_ipc.py	Implements IPC job stopping.
packages/​uipath/​src/​uipath/​_cli/​cli_run.py	Enables controlled run cancellation.
packages/​uipath/​src/​uipath/​_cli/​cli_eval.py	Enables controlled evaluation cancellation.
packages/​uipath/​src/​uipath/​_cli/​cli_debug.py	Enables controlled debug cancellation.
packages/​uipath/​tests/​cli/​test_server_cancellation.py	Covers cancellation behavior and transports.
packages/​uipath/​tests/​cli/​test_server.py	Tests HTTP exit codes.
packages/​uipath/​tests/​cli/​test_server_job_core.py	Tests core outcomes and teardown ordering.
packages/​uipath/​tests/​cli/​test_server_ipc.py	Updates IPC stop and mock coverage.
packages/​uipath/​tests/​cli/​test_run.py	Verifies discovery failures exit nonzero.
packages/​uipath/​tests/​cli/​test_job_api.py	Tests new status mappings.
packages/​uipath/​tests/​cli/​eval/​test_eval_discovery.py	Verifies evaluation discovery failures.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

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

See analysis details on SonarQube Cloud

[github-actions]

🚨 Heads up: uipath-langchain cross-tests are FAILING 🚨

Your changes may break the uipath-langchain-python integration.

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →