feat(agent): add max_turns and max_token_budget execution limits

[rshriharripriya]

Summary

Closes #2124

• Add max_turns parameter to Agent.__init__ — caps the number of event loop cycles per invocation; stops with stop_reason="max_turns" when reached
• Add max_token_budget parameter to Agent.__init__ — caps cumulative input+output tokens per invocation; stops with stop_reason="max_token_budget" when reached
• Both default to None (no limit), fully backwards compatible
• Add "max_turns" and "max_token_budget" to the StopReason Literal in types/event_loop.py
• Counters are stored on the agent instance and reset at the start of each invocation in stream_async; in-flight tool calls always complete before a limit is enforced

Test plan

• test_max_turns_stops_loop — max_turns=1 stops before entering a second cycle triggered by a tool call
• test_max_turns_allows_exactly_n_cycles — max_turns=2 allows exactly 2 cycles
• test_max_turns_none_is_unbounded — max_turns=None (default) runs to natural completion
• test_max_turns_resets_between_invocations — counter resets on each new invocation
• test_max_token_budget_stops_when_exceeded — budget of 0 triggers immediately after first model call
• test_max_token_budget_none_is_unbounded — max_token_budget=None (default) runs to natural completion
• test_max_token_budget_resets_between_invocations — token counter resets on each new invocation
• All 666 existing unit tests pass with no regressions
• ruff check and ruff format --check pass on all changed files
• mypy reports no issues on all changed source files

[harishvadali]

Thank you for the MR. Looking forward to this as we are currently using hooks to configure the max turns.

[rshriharripriya]

@srbhsrkr thank you so much for your feedback

[srbhsrkr]

PTAL.

[srbhsrkr]

One minor correctnss concern -> the early-exit guard fires before checking agent._interrupt_state.activated and _has_tool_use_in_latest_message. Those 2 paths execute the model at stop_reason = "tool_use" without incrementing _invocation_turn_count. This means a sequence like:

cycle 1: tool_use (no model call) → counter stays 0
cycle 2: model call → counter becomes 1

this could burn an extra cycle past max_turns=1 in interrupt/existing-tool-use scenarios. This is an edge case and may be acceptable, but it's worth a comment acknowledging the behavior or a test covering it.
invocation_state["request_state"] at early exit, by line 123–124 of event_loop.py, request_state is initialized before the try block where the limit checks now live, so invocation_state["request_state"] is always present when the EventLoopStopEvent is yielded. Safe.

The _retry_strategy attribute name inconsistency, the existing mock fixture in test_event_loop.py sets mock.retry_strategy (no underscore prefix) while agent.py stores it as self._retry_strategy. This is a pre-existing issue, not introduced by this PR.

[rshriharripriya]

Added a comment at the branch point making it explicit that neither the interrupt nor existing-tool-use path increments _invocation_turn_count (no model call = no turn consumed), and added test_max_turns_skipped_model_cycle_does_not_consume_turn to pin that behaviour.

Also caught two small things on the final pass: stale stop_reason examples in the stream_async/call docstrings weren't listing the two new stop reasons, and test_max_token_budget_stops_when_counter_already_at_limit wasn't using apply_execution_limit_defaults like the rest of the file. Both fixed.

I learned a lot from this one, Thanks for the review, really appreciated!

[srbhsrkr]

LGTM. Please address that 1 minor correctness comment shared.