feat(governance): track-event telemetry sink for App Insights customEvents

[viswa-uipath]

Summary

Stacked on top of #133 (feat/governance-policy-fetch-hoist). Adds a new platform-mandated audit sink that emits governance evaluation telemetry to App Insights customEvents via the UiPathPlatformGovernanceProvider.track_event callable shipped in uipath-python PR #1745 (uipath-platform 0.1.74).

The runtime stays decoupled from uipath-platform — the sink takes a Callable[..., None]; the host adapts provider.track_event to it at wiring time. No new dep added to uipath-runtime.

Event vocabulary

Event	When	Per-hook count
governance.rule.denied	A rule matched and its configured action ≠ allow	one per matched-restrictive rule
governance.hook.summary	Hook end, with at least one rule evaluated or skipped	exactly one

Volume-controlled: a 50-rule pack on a chatty agent doesn't multiply per-step telemetry by 50. Passed + skipped + matched-allow rules roll into the hook summary; only denials get individual events.

Payload contract

Every event carries:

Field	Source
execution_engine	GovernanceRuntimeMetadata (default uipath_native_governance_checker, host-overridable for future engines like AGT)
agent_type	host-supplied (e.g. uipath_coded, uipath_lowcode, servicenow)
agent_framework	host-supplied (e.g. langchain)
runtime_version	auto-resolved via importlib.metadata.version(\"uipath-runtime\")
operation_id (HTTP header)	AuditEvent.trace_id → App Insights operation_Id for cross-event correlation
agent_name / hook / timestamp	from the audit event

Per-rule events add: pack, clause, rule_name, mode, evaluator_result (DENY/HITL), action_applied (mode-adjusted), duration_ms, mapped_to_uipath, detail.

Per-hook summary adds: mode, passed_count, denied_count, skipped_count, skipped_policy_names, guardrail_dispatched_count (UiPath-mapped guardrails that fell back to /runtime/govern), duration_ms, final_action.

Filter rules (accepts() + emit() defense-in-depth)

Case	track_event fires?
Any event with mode = DISABLED	❌
RULE_EVALUATION, matched = False	❌ (rolls into hook summary's passed_count)
RULE_EVALUATION, matched = True, action = allow	❌ (positive informational match, not a denial)
RULE_EVALUATION, matched = True, action ∈ {deny, escalate, audit}	✅
HOOK_END, total_rules = 0 AND skipped_count = 0	❌ (empty hook, zero operator value)
HOOK_END, total > 0 OR skipped > 0	✅

Wiring

The audit manager auto-registers the sink at construction (mirrors _register_traces_sink shape, wrapped in a broad try/except so a misconfigured wiring layer never crashes the agent):

```python
manager = AuditManager(
track_event=provider.track_event, # from PR #1745
runtime_metadata=GovernanceRuntimeMetadata(
agent_type="uipath_coded",
agent_framework="langchain",
),
)
```

If the host forgets to wire track_event, the registration logs a warning and the sink is skipped — telemetry off, runtime continues.

Count semantics

Field	Meaning
matched_rules	Raw "any check matched" count — unchanged for backward compat with the legacy traces sink
denied_count (new)	Matched AND action ≠ allow — the spec-meaning denial count
passed_count	total_rules - denied_count — includes both unmatched and matched-allow rules

Test plan

• uv run ruff check src/uipath/runtime/governance tests — clean
• uv run mypy src/uipath/runtime/governance — clean (12 source files)
• uv run pytest --no-cov — 374 passed, 1 skipped (was 326 → +49 new tests, +1 skipped pre-existing)

New test files:

• tests/test_governance_metadata.py (5) — defaults, overrides, frozen behavior, PackageNotFoundError fallback
• tests/test_track_events_sink.py (30) — filter (accepts + emit defense-in-depth) × event types × DISABLED × empty-hook × matched-allow, payload shape, mode handling, operation_id correlation
• tests/test_audit_manager_track_event_wiring.py (7) — happy path, auto-registration alongside traces sink, missing-callable warning, synthetic registration-failure recovery, opt-out
• tests/test_evaluator_telemetry.py (7) — per-rule duration, per-hook duration, skipped tracking, denied/passed counts, matched-allow contributes to passed, guardrail dispatched count

Files touched

File	Change
src/uipath/runtime/governance/_audit/metadata.py (new)	GovernanceRuntimeMetadata dataclass
src/uipath/runtime/governance/_audit/track_events.py (new)	TrackEventAuditSink
src/uipath/runtime/governance/_audit/base.py	Auto-register the sink; emit_* signature extensions (backward-compatible)
src/uipath/runtime/governance/native/evaluator.py	Per-rule + per-hook timing; skipped-rule tracking; denied/passed split

Net: 8 files, +1524 / -11.

Out of scope

• Per-rule visibility into UiPath-mapped guardrails (would be a governance.guardrail.dispatched event from the compensator). Today the per-hook guardrail_dispatched_count supports the mapped-vs-native ratio query.
• A real TelemetryProvider protocol in uipath-core — the callable indirection is sufficient for current needs.

🤖 Generated with Claude Code

Development Package

• Add this package as a dependency in your pyproject.toml:

[project]
dependencies = [
  # Exact version:
  "uipath-runtime==0.11.4.dev1001350585",

  # Any version from PR
  "uipath-runtime>=0.11.4.dev1001350000,<0.11.4.dev1001360000"
]

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

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

[radu-mocanu]

Lifecycle concern for this governed runtime: the platform/host wiring for track_event will create a disposable non-blocking dispatcher. That cleanup should be owned by the governed runtime lifecycle, not by every CLI path separately (cli_run, cli_debug, etc.).

Please add a generic runtime-owned cleanup hook, for example on_dispose: Callable[[], None] | None = None, store it on the governed runtime, and call it from dispose() in a finally after disposing the delegate:

async def dispose(self) -> None:
    try:
        await self._delegate.dispose()
    finally:
        if self._on_dispose is not None:
            self._on_dispose()

Then the platform/host PR can pass on_dispose=dispatcher.shutdown while still passing only dispatcher.dispatch to AuditManager(track_event=...). This keeps uipath-runtime decoupled from the platform dispatcher type, but ensures the existing runtime cleanup path also flushes telemetry.