feat: add structured reason to BudgetExceeded + Governor.snapshot

Name which bound tripped (.reason) on BudgetExceeded and expose a read-only
Governor.snapshot, so the UI can show a precise stop message. Backward
compatible: same raise sites, thresholds, and BudgetExceeded(RuntimeError) type.

Co-Authored-By: Codex <codex@openai.com>

src/core/governor.py

@@ -35,15 +35,18 @@ class Governor:
 
     def check(self, turn: int) -> None:
         if turn > self.max_turns:
-            raise BudgetExceeded(f"Turn cap {self.max_turns} reached")
+            raise BudgetExceeded(f"Turn cap {self.max_turns} reached", reason="max_turns")
         if self._total_calls >= self.max_total_calls:
-            raise BudgetExceeded(f"Total call cap {self.max_total_calls} reached")
+            raise BudgetExceeded(f"Total call cap {self.max_total_calls} reached", reason="max_total_calls")
         if self._calls_this_turn >= self.max_calls_per_turn:
-            raise BudgetExceeded(f"Per-turn call cap {self.max_calls_per_turn} reached on turn {turn}")
+            raise BudgetExceeded(
+                f"Per-turn call cap {self.max_calls_per_turn} reached on turn {turn}",
+                reason="max_calls_per_turn",
+            )
         if self.max_total_tokens is not None and self._total_tokens >= self.max_total_tokens:
-            raise BudgetExceeded(f"Total token cap {self.max_total_tokens} reached")
+            raise BudgetExceeded(f"Total token cap {self.max_total_tokens} reached", reason="max_total_tokens")
         if self.hourly_budget_usd is not None and self._spend_usd >= self.hourly_budget_usd:
-            raise BudgetExceeded(f"Spend cap ${self.hourly_budget_usd:.2f} reached")
+            raise BudgetExceeded(f"Spend cap ${self.hourly_budget_usd:.2f} reached", reason="hourly_budget_usd")
 
     def record_call(self, tokens: int = 0, cost_usd: float = 0.0) -> None:
         self._calls_this_turn += 1
@@ -72,6 +75,31 @@ class Governor:
             "spend_usd": round(self._spend_usd, 4),
         }
 
+    @property
+    def snapshot(self) -> dict[str, int | float | None]:
+        """Read-only view of the live counters alongside their configured limits.
+
+        Handy for UI surfaces that want to show "X of Y calls used" without
+        reaching into private fields."""
+        return {
+            **self.stats,
+            "max_turns": self.max_turns,
+            "max_calls_per_turn": self.max_calls_per_turn,
+            "max_total_calls": self.max_total_calls,
+            "max_total_tokens": self.max_total_tokens,
+            "hourly_budget_usd": self.hourly_budget_usd,
+        }
+
 
 class BudgetExceeded(RuntimeError):
-    pass
+    """Raised when a Governor bound trips.
+
+    Carries a structured ``reason`` naming which bound tripped (one of
+    ``max_turns`` / ``max_total_calls`` / ``max_calls_per_turn`` /
+    ``max_total_tokens`` / ``hourly_budget_usd``) while ``str(exc)`` stays a
+    human-readable message. Remains a ``RuntimeError`` subclass so existing
+    generic handlers keep working."""
+
+    def __init__(self, message: str, *, reason: str | None = None) -> None:
+        super().__init__(message)
+        self.reason = reason

tests/test_governor.py

@@ -90,3 +90,86 @@ class TestGovernorTokensAndCost:
         assert g.stats["spend_usd"] == 0.0
         assert g.max_turns == 7  # limits survive reset
         assert g.max_total_tokens == 999
+
+
+class TestBudgetExceededReason:
+    def test_reason_is_max_turns(self):
+        g = Governor(max_turns=5)
+        with pytest.raises(BudgetExceeded) as excinfo:
+            g.check(6)
+        assert excinfo.value.reason == "max_turns"
+
+    def test_reason_is_max_total_calls(self):
+        # Per-turn cap kept high so only the total-calls bound trips.
+        g = Governor(max_total_calls=2, max_calls_per_turn=100)
+        g.begin_turn(1)
+        g.record_call()
+        g.record_call()
+        with pytest.raises(BudgetExceeded) as excinfo:
+            g.check(1)
+        assert excinfo.value.reason == "max_total_calls"
+
+    def test_reason_is_max_calls_per_turn(self):
+        # Total-calls cap kept high so only the per-turn bound trips.
+        g = Governor(max_calls_per_turn=2, max_total_calls=100)
+        g.begin_turn(1)
+        g.record_call()
+        g.record_call()
+        with pytest.raises(BudgetExceeded) as excinfo:
+            g.check(1)
+        assert excinfo.value.reason == "max_calls_per_turn"
+
+    def test_reason_is_max_total_tokens(self):
+        g = Governor(max_total_tokens=100)
+        g.begin_turn(1)
+        g.record_call(tokens=150)
+        with pytest.raises(BudgetExceeded) as excinfo:
+            g.check(1)
+        assert excinfo.value.reason == "max_total_tokens"
+
+    def test_reason_is_hourly_budget_usd(self):
+        g = Governor(hourly_budget_usd=0.01)
+        g.begin_turn(1)
+        g.record_call(cost_usd=0.05)
+        with pytest.raises(BudgetExceeded) as excinfo:
+            g.check(1)
+        assert excinfo.value.reason == "hourly_budget_usd"
+
+    def test_remains_runtime_error_subclass(self):
+        # The sibling UI unit catches generically; type hierarchy must not change.
+        assert issubclass(BudgetExceeded, RuntimeError)
+        g = Governor(max_turns=1)
+        with pytest.raises(RuntimeError):
+            g.check(2)
+
+    def test_message_stays_human_readable(self):
+        g = Governor(max_turns=5)
+        with pytest.raises(BudgetExceeded) as excinfo:
+            g.check(6)
+        assert "Turn cap 5 reached" in str(excinfo.value)
+
+    def test_reason_defaults_to_none_when_constructed_directly(self):
+        exc = BudgetExceeded("manual raise")
+        assert exc.reason is None
+        assert str(exc) == "manual raise"
+
+
+class TestGovernorSnapshot:
+    def test_snapshot_includes_counters_and_limits(self):
+        g = Governor(max_turns=7, max_total_calls=50, max_total_tokens=999, hourly_budget_usd=1.5)
+        g.begin_turn(2)
+        g.record_call(tokens=40, cost_usd=0.25)
+        snap = g.snapshot
+        assert snap["total_calls"] == 1
+        assert snap["total_tokens"] == 40
+        assert snap["current_turn"] == 2
+        assert snap["max_turns"] == 7
+        assert snap["max_total_calls"] == 50
+        assert snap["max_total_tokens"] == 999
+        assert snap["hourly_budget_usd"] == 1.5
+
+    def test_snapshot_optional_limits_default_none(self):
+        g = Governor()
+        snap = g.snapshot
+        assert snap["max_total_tokens"] is None
+        assert snap["hourly_budget_usd"] is None