Summary

Three-layer wiring that lets the agent runtime consume UiPath governance through protocols owned by uipath-core, with the HTTP implementation hidden in uipath-platform and registered at CLI startup.

• uipath-core — declares GovernancePolicyProvider / GovernanceCompensationProvider protocols plus a module-level default-provider registry (set_/get_/reset_default_*_provider). Owns the wire-format models PolicyContext, PolicyResponse, FiredRule, GovernRequest.
• uipath-platform — adds GovernanceService (sdk.governance) wrapping the org-scoped agenticgovernance_ ingress: retrieve_policy() and compensate() (plus async variants), satisfying both core protocols via get_policy(context) and compensate(request). Adds public resolve_trace_id(fallback) helper in common/_base_service.py so callers can capture the trace id on the hook thread before hopping to a background pool.
• uipath CLI — _governance_setup.register_governance_providers() instantiates GovernanceService and registers it as the default policy + compensation provider. Wired into cli_run / cli_debug startup. No-op when UIPATH_URL / UIPATH_ACCESS_TOKEN are unset (dev machines) or when UiPath() construction fails — governance must never block agent execution.
• Bumps: uipath-core 0.5.20 → 0.5.21, uipath-platform 0.1.71 → 0.1.73, uipath 2.11.6 → 2.11.7.

Motivation

Replaces hand-rolled urllib HTTP in uipath-runtime-python PRs #121 and #123 per radu-mocanu's review comment: "tenant/org/access token etc. are platform concerns. The runtime's concern is just managing the policies."

The runtime can't import uipath-platform (dependency direction is the other way), so the protocols and default-provider registry live in uipath-core. The CLI binds the concrete platform implementation in at startup; the runtime never reaches across the layer boundary.

After this lands, the runtime gives up urllib, the browser-UA WAF workaround, manual UIPATH_ACCESS_TOKEN reads, manual org/tenant resolution, and the import-time uipath-platform dependency — BaseService provides all of that, and the runtime depends only on uipath-core protocols.

Design choices

• Three-leg triangle (core protocols / platform impl / CLI wiring) rather than a direct uipath-platform import from runtime. Keeps uipath-core as the lowest layer; lets tests swap in fakes via set_default_*_provider.
• runtime_checkable Protocols — any object exposing get_policy(context) / compensate(request) satisfies the contract. GovernanceService happens to be the platform-backed implementation but isn't load-bearing on the runtime side.
• Fail-open registration — missing creds or construction failure leaves the registry empty; the runtime falls back to "no provider → no policies", same end state as before this PR.
• URL composed directly (not via RequestSpec + Endpoint): the agenticgovernance_ ingress uses {origin}/{org_id_uuid}/agenticgovernance_/... — the org UUID, not the slug UiPathUrl.scope_url produces. Documented in _build_org_scoped_request.
• is_conversational: bool | None rather than an enum: matches the runtime's existing _agent_is_conversational flag. The True/False/None → conversational/autonomous/omit wire mapping is an implementation detail of the service.
• resolve_trace_id returns the value, doesn't mutate headers: the existing _inject_trace_context only injects the header. Compensation needs the id in the request body, and must resolve on the hook thread before the pool hop because OpenTelemetry context is thread-local.
• @cached_property on sdk.governance: matches buckets/attachments/folders. Avoids fresh httpx.Client/AsyncClient per access in the background compensation loop.
• PolicyResponse.mode: Optional[EnforcementMode] with lenient coercion: a @field_validator(mode="before") maps unknown wire values to None instead of raising, so a server-side mode addition can't break agent startup.

What stays in uipath-runtime-python

The runtime keeps submit_compensation's bounded thread pool, in-flight semaphore, drop-on-saturation, atexit shutdown, and disabled_guardrails(...) domain helper. The worker resolves the registered provider via get_default_compensation_provider() and calls provider.compensate(GovernRequest(...)).

Test plan

• ruff check . / ruff format --check . — clean
• mypy src tests — clean
• pytest --no-cov — full suite green
• 18 uipath-core tests (tests/governance/test_providers.py): protocol conformance (runtime_checkable accept/reject), PolicyContext defaults + extra-field tolerance, PolicyResponse defaults + parsing all three known EnforcementMode values + unknown-mode coercion to None, GovernRequest wire aliases (camelCase + intentional snake_case src_timestamp, optional job-context fields excluded when None), registry set/get/clear/reset, end-to-end dispatch.
• 26 uipath-platform tests (tests/services/test_governance_service.py): policy fetch happy path, default field handling, header + bearer wiring, agentType query param (parameterized True/False), missing org/tenant validation errors, HTTP errors, async; compensate payload aliasing, job-context auto-fill, caller override precedence, caller empty-string preserved over env, omitted keys, HTTP error, missing org id, async; GovernanceService satisfies both protocols via get_policy / get_policy_async / compensate; 5 resolve_trace_id cases.
• 5 uipath CLI tests (tests/cli/test_governance_setup.py): no-op when UIPATH_URL / UIPATH_ACCESS_TOKEN missing (each independently), both registered to the same GovernanceService instance when both set, re-registration overwrites the previous provider, construction failure swallowed silently.
• Integration: runtime-side PRs tracer: fix lint #121/cli: pack should include mermaid files #123 to be refactored to consume the registered protocols instead of inline urllib — separate PRs.

🤖 Generated with Claude Code

Development Packages

uipath-core

[project]
dependencies = [
  # Exact version (copy-paste ready):
  "uipath-core==0.5.21.dev1017386862",

  # Any version from this PR (uncomment to use a range instead):
  # "uipath-core>=0.5.21.dev1017380000,<0.5.21.dev1017390000",
]

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

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

uipath

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

  # Any version from this PR (uncomment to use a range instead):
  # "uipath>=2.11.7.dev1017380000,<2.11.7.dev1017390000",
]

[[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" }
uipath-platform = { index = "testpypi" }
uipath-core = { index = "testpypi" }

[tool.uv]
override-dependencies = ["uipath-platform==0.1.73.dev1017386862", "uipath-core==0.5.21.dev1017386862"]

uipath-platform

[project]
dependencies = [
  # Exact version (copy-paste ready):
  "uipath-platform==0.1.73.dev1017386862",

  # Any version from this PR (uncomment to use a range instead):
  # "uipath-platform>=0.1.73.dev1017380000,<0.1.73.dev1017390000",
]

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

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

[tool.uv]
override-dependencies = ["uipath-core==0.5.21.dev1017386862"]