feat(cli): shared host-side governance bootstrap for run and debug

[viswa-uipath]

Summary

Extracts the governance-bootstrap helpers used by uipath run into a shared _cli/_governance_bootstrap.py module and wires the same path into uipath debug, so both commands stamp identical audit + telemetry events. Adds a CLI-side YAML → PolicyIndex compiler so the runtime layer never has to depend on pyyaml or the wire policy format.

GovernanceBootstrap dataclass

resolve_governance() returns a frozen GovernanceBootstrap (with evaluator / policy_index / enforcement_mode / dispose fields plus a wrap_runtime() method) or None when governance should not fire. Callers hand the base runtime to bootstrap.wrap_runtime(delegate, agent_name=..., runtime_id=...) and call bootstrap.dispose() from a finally block — no manual UiPathGovernedRuntime construction, no tuple unpacking.

Factory-declared identity

Wire labels for governance / App Insights come from UiPathRuntimeFactorySettings — never from the CLI:

• agent_framework: str | None — factory declares its framework identity (e.g. "langgraph")
• agent_type: str | None — factory declares the coarse type (e.g. "uipath_coded", "uipath_lowcode")

Both flow: factory.get_settings() → CLI → GovernanceRuntimeMetadata verbatim. Missing values default to "unknown" at the metadata boundary. is_coded_agent and low-code filename detection are removed entirely.

Eval telemetry consumes the same source: EvalSetRunCreatedEvent carries agent_type populated from the factory; EvalTelemetrySubscriber forwards it verbatim to the App Insights AgentType dimension.

Error handling

Governance is optional — a failing bootstrap must not crash the run. Every step in resolve_governance() that can raise (policy fetch, policy compile, dispatcher init, compensator / audit-manager / evaluator construction) is caught; the CLI logs a warning and runs un-governed. If a failure lands after the dispatcher spawns its background thread and registers its atexit hook, the recovery path calls dispose() to unregister and shut down so no thread leaks.

dispose() runs from CLI finally blocks, so it swallows and debug-logs both atexit.unregister and dispatcher-shutdown errors — it must never mask the primary exception. Safe to call more than once: the dispatcher's shutdown early-returns on repeat calls and atexit.unregister is a no-op for missing handlers.

cli_debug parity

cli_debug calls resolve_governance() after factory.get_settings(), computes governance_runtime_id once (ctx.conversation_id or ctx.job_id or "default"), passes the evaluator into factory.new_runtime and wraps via bootstrap.wrap_runtime — matching cli_run's shape exactly.

Runtime dependency

Depends on uipath-runtime shipping UiPathRuntimeFactorySettings.agent_framework and .agent_type. The pin will be bumped in a follow-up commit.

Adapter follow-ups (outside this PR)

Each third-party factory should declare its own wire labels in get_settings() — until they do, their governance/App Insights emits "unknown":

Repo	agent_framework	agent_type
uipath-agents-python (low-code)	your choice	"uipath_lowcode"
uipath-langchain-python	"langgraph"	"uipath_coded"
uipath-integrations-python/*	e.g. "llamaindex", "openai_agents", "pydantic_ai", "google_adk", "agent_framework"	"uipath_coded"

Test plan

• tests/cli/test_governance_bootstrap.py — feature-flag gate, policy fetch / compile failures, dispose contract, wrap_runtime, error-path cleanup, agent_type / agent_framework forwarding
• tests/cli/_governance/test_yaml_index.py — every supported check type + pack/rule plumbing
• tests/cli/eval/test_eval_telemetry.py — agent_type forwarded from event to App Insights
• Full CLI suite + functions + eval regression — passes end-to-end once the runtime pin bumps

🤖 Generated with Claude Code

Development Packages

uipath

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

  # Any version from this PR (uncomment to use a range instead):
  # "uipath>=2.12.5.dev1017780000,<2.12.5.dev1017790000",
]

[[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 →

[radu-mocanu]

shouldn t we apply the governance to evals as well?

[radu-mocanu]

Overall blocking concern: this PR crosses package boundaries by making the public uipath CLI know about product/runtime identities and framework adapter discovery. uipath-python should not reference or special-case the low-code runtime, and it should not infer framework identity from framework-specific files or constants.

The clean contract is to add framework: str = "unknown" to UiPathRuntimeFactorySettings in uipath-runtime. Each registered factory should provide its own value at the existing entry-point factory seam: framework adapters set their framework (langchain, llamaindex, etc.), the functions runtime sets functions, and the low-code runtime can set low_code from its own package. The CLI should only read factory_settings.framework and forward it into GovernanceRuntimeMetadata, defaulting to unknown when settings are absent.

[Copilot]

Pull request overview

This PR extracts host-side governance bootstrapping into a shared CLI module and reuses it from both uipath run and uipath debug, so they fetch/compile policy and stamp identical audit + telemetry events. It also adds a CLI-side YAML → PolicyIndex compiler and updates dependencies/tests accordingly.

Changes:

• Added shared governance bootstrap module (_cli/_governance_bootstrap.py) and wired it into both cli_run and cli_debug.
• Added CLI-side governance helpers (_cli/_governance/yaml_index.py) to compile YAML policies into a runtime PolicyIndex.
• Added comprehensive tests for governance bootstrap and YAML compilation, and bumped package/dependency versions (including pyyaml).

Reviewed changes

Copilot reviewed 10 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/uipath/uv.lock	Updates lockfile for new/updated dependencies (runtime bump, PyYAML/types, etc.).
packages/uipath/pyproject.toml	Bumps uipath version and updates dependencies (incl. uipath-runtime and pyyaml).
packages/uipath/src/uipath/_cli/_governance_bootstrap.py	New shared governance bootstrap used by both run/debug paths.
packages/uipath/src/uipath/_cli/_governance/init.py	New CLI governance helper package export.
packages/uipath/src/uipath/_cli/_governance/yaml_index.py	New YAML policy compiler producing PolicyIndex for the runtime.
packages/uipath/src/uipath/_cli/cli_run.py	Wires shared governance bootstrap into uipath run and manages teardown.
packages/uipath/src/uipath/_cli/cli_debug.py	Wires shared governance bootstrap into uipath debug and manages teardown.
packages/uipath/src/uipath/_cli/_utils/_common.py	Adds shared is_coded_agent() helper used for consistent agent-type labeling.
packages/uipath/src/uipath/_cli/_evals/_telemetry.py	Reuses is_coded_agent() for consistent telemetry labeling.
packages/uipath/tests/cli/test_governance_bootstrap.py	New tests covering feature-flag gating, policy fetch/compile branches, cleanup contract, and conversational flag read.
packages/uipath/tests/cli/_governance/test_yaml_index.py	New tests covering YAML policy parsing and check-type compilation.
packages/uipath/tests/cli/_governance/init.py	Initializes governance test package.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[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 →

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud