fix(sdk/python): keep rate limiter jitter off the global random state - #1078

Summary

StatelessRateLimiter._calculate_backoff_delay calls random.seed(self._container_seed + attempt)
before drawing jitter. That seeds the module-level generator, so every rate-limit retry resets
the random stream of the whole host process to a value derived from HOSTNAME and the pid. After an
agent hits one 429, every later random.random() / choice() / shuffle() / sample() in the
application returns a repeatable sequence instead of continuing the stream the caller seeded —
silently, and identically in every container that shares the hostname/pid shape.

Drawing from a private random.Random instance removes the side effect. The jitter values are
unchanged: CPython's module-level random.uniform delegates to a module-level Random seeded
through the same path, so random.seed(x) + random.uniform(...) and
random.Random(x).uniform(...) produce the same number — verified bit-for-bit across 240
seed/attempt/range combinations by comparing float.hex(). Backoff timing, retry counts, and the
per-container jitter distribution all behave exactly as before; the seed just stops leaking into
global state, which also stops concurrent callers from drawing jitter off a seed another caller
installed. The Go and TypeScript limiters already isolate their jitter generator this way, so this
brings Python in line with them (details under Related issues / PRs).

It also degrades the SDK's own jitter. rate_limiter.py is the only module that seeds the global
generator, but two other retry paths draw from it: client.py:1295 (_next_poll_interval,
random.uniform(0.8, 1.2)) and harness/_runner.py:415/:423 (transient-error backoff,
random.uniform(-delay * 0.25, delay * 0.25)). After one rate-limited LLM call, both produce a
deterministic sequence derived from the container seed — so containers sharing a hostname/pid shape
poll and back off in lockstep, which is exactly what that jitter is there to prevent.

This is on by default: AIConfig.enable_rate_limit_retry is Field(default=True)
(agentfield/types.py:497) and agent_ai.py:605-609 re-forces it when unset, so the path is
agent.chat(...) → execute_with_retry → _calculate_backoff_delay → global reseed.

Reproducer against main:

import random
from agentfield.rate_limiter import StatelessRateLimiter

random.seed(1234); before = random.random()
random.seed(1234)
StatelessRateLimiter(jitter_factor=0.25)._calculate_backoff_delay(0)
assert random.random() == before   # fails today

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Docs only
• Tests only
• CI / tooling
• Breaking change

Test plan

Two tests added to sdk/python/tests/test_rate_limiter_core.py. Both fail on main and pass with
the fix; neither needs network, credentials, or a coding-agent binary.

• test_calculate_backoff_leaves_global_random_state_alone — snapshots three global draws, calls
  _calculate_backoff_delay, and asserts the stream continued unchanged.
• test_execute_with_retry_leaves_global_random_state_alone — the same assertion through the public
  execute_with_retry path against a real 429 (two retries, jitter_factor=0.25, asyncio.sleep
  monkeypatched), so the contract is pinned at the API callers actually use.

Commands run locally (Windows, CPython 3.13.12 in an isolated venv, pip install -e ".[dev]" plus
ruff==0.15.22 at the version sdk-python.yml pins):

• cd sdk/python && python -m pytest tests/test_rate_limiter_core.py --no-cov → 12 passed
  (10 pre-existing + 2 new; both new tests fail before the source change)
• cd sdk/python && python -m pytest --ignore=tests/test_agent_mesh.py --no-cov →
  9 failed, 2392 passed, 6 skipped on Windows/CPython 3.13.12. The identical command on
  unmodified main gives 9 failed, 2390 passed, 6 skipped with a byte-identical set of
  failing test ids, so the +2 passed is exactly the two new tests and nothing regressed. Those 9
  are pre-existing Windows-host failures ('gbk' codec can't decode from pathlib.read_text,
  and b'inline\r' != b'inline\n' CRLF assertions) that pass on CI's ubuntu-latest.
  tests/test_agent_mesh.py is excluded because it hangs on this host at ~8% — verified to hang
  identically on unmodified main, so it is an environment issue, not a regression.
• cd sdk/python && python -m mypy --config-file mypy.ini agentfield/ → Success: no issues found
  in 81 source files
• cd sdk/python && python -m ruff check . → All checks passed
• cd sdk/python && python -m ruff format --diff agentfield/rate_limiter.py tests/test_rate_limiter_core.py
  → 2 files already formatted (no reformatting noise added)

Test coverage

• I ran tests for the surface(s) I changed locally.
• New code paths are covered by tests in this PR (no bare additions).
• If I removed code, I updated coverage-baseline.json — not applicable, no source lines were
  removed, so no surface percentage can drop.
• The coverage gate check is green in CI before requesting review — I cannot run
  ./scripts/coverage-summary.sh locally because it measures all five surfaces and this machine
  has no Go, Bun, or Docker engine. Leaving this for CI rather than claiming it.

agentfield.rate_limiter is already in the pytest --cov list, so it is a gated surface. The only
changed executable statements are rng = random.Random(...) and jitter = rng.uniform(...) — the
other four added lines are comments — and both execute on every jittered backoff, covered by the
pre-existing test_calculate_backoff_applies_jitter_and_max_cap and the two new tests.

That pre-existing test is also why this survived: it computes its expectation with
random.Random(limiter._container_seed + attempt) and compares only the returned number, which is
identical either way. Nothing asserted on the global state.

Checklist

• I have read docs/CONTRIBUTING.md and docs/DEVELOPMENT.md.
• Commits are signed and follow conventional-commits style. — the subject follows
  conventional-commits; the commit is not signed, as I have no signing key configured. Flagging
  it rather than ticking the box.
• I have linked any related issues — none: this was found by reading the module, there is no
  existing issue for it.

Related issues / PRs

No open issue or PR covers this. git log --all -- sdk/python/agentfield/rate_limiter.py shows the
file has only ever been touched by #265 (default tuning) and the original Haxen→AgentField rename.
Checking every remote ref, rate_limiter.py is either the current main blob or the pre-#265 blob,
and no ref anywhere contains random.Random in that file — so nothing in flight addresses it.

The Go and TypeScript SDKs already do this correctly, with the same containerSeed + attempt
seeding, so this is a parity fix rather than a design change:

• sdk/go/ai/rate_limiter.go:321 — rng := rand.New(rand.NewSource(r.containerSeed + int64(attempt))),
  a private generator, with the math/rand package-level functions deliberately unused.
• sdk/typescript/src/ai/RateLimiter.ts:172 — _createJitterRng(seed) returns a local LCG closure,
  called as this._createJitterRng(this._containerSeed + attempt).

The jitter formula matches too: random.uniform(-r, r) is -r + 2r·u = r·(2u − 1), exactly the
(rng() * 2 - 1) * jitterRange both other SDKs use. Python is the only one drawing it from global
state.

I read the Go and TypeScript limiters but did not run them (no Go or Bun toolchain here), so this PR
changes and tests Python only.