fix: bound autonomous loop token usage

[fablgen-agent]

Summary

• add an optional per-run max_run_tokens guard for max_loops="auto"
• estimate the system prompt, structured messages, tool schemas, and responses rather than relying on the removed flattened-history path
• stop before a request that cannot fit and return an explicit deterministic budget-exhausted summary without spending tokens on another model call
• expose max_subtask_iterations and max_subtask_loops as validated Agent constructor parameters
• report cumulative autonomous LLM calls and locally estimated text tokens in final summaries
• document all three safety controls in the public autonomous-agent example

The remaining estimated allowance is passed as the request max_tokens cap. Provider-reported usage and billing remain authoritative: the local estimate deliberately excludes image, audio, cache, and hidden reasoning tokens.

Fixes #1976

Rebase note

This branch is rebuilt on current master after #1990. It preserves that PR's structured transcript, mutable-plan, and correctness changes; the budget now measures the structured messages payload passed by the current implementation.

Validation

• pytest tests/agents/test_autonomous_loop.py tests/structs/test_agent.py::TestAutonomousAgentLoop -q -p no:randomly — 46 passed
• pytest tests/agents/ -q -p no:randomly — 300 passed, 5 failed
• the same exact five tests fail on untouched upstream/master (four missing legacy error re-exports and one pre-existing imgs=None mock expectation), so the branch adds no failures to that suite
• black . --check --diff — 980 files unchanged
• ruff check . — passed
• python -m py_compile swarms/agents/autonomous_loop.py swarms/structs/agent.py tests/agents/test_autonomous_loop.py — passed
• git diff --check — passed
• changed-file credential-pattern scan — clean

Disclosure

Prepared with AI coding assistance by the Fablgen Agent account. I reviewed the implementation and test results before updating the PR.

[github-actions]

Hello there, thank you for opening an PR ! 🙏🏻 The team was notified and they will get back to you asap.