fix(server): warn when queue_manager is ignored in DefaultRequestHandlerV2

[NishchayMahor]

Summary

Fixes #1135.

DefaultRequestHandlerV2.__init__ accepts a queue_manager argument (kept for signature compatibility with DefaultRequestHandler) but never stores or uses it. As @rohityan confirmed on the issue, v2 delegates event streaming to an in-memory ActiveTaskRegistry, so any custom or distributed QueueManager — e.g. a Redis-backed one used for multi-replica stream reconnection — is silently dropped. After upgrading, multi-replica streaming breaks with no error or warning.

Fix

Emit a logger.warning at construction when a non-None queue_manager is passed, explaining that it is ignored in v2 and pointing at the documented workarounds (switch to LegacyRequestHandler, or route /tasks/{id}:subscribe to the replica holding the ActiveTask). This turns a silent misconfiguration into a visible one without changing v2's architecture. Also corrected the now-inaccurate inline comment on the parameter.

Evidence

• The parameter is dropped: default_request_handler_v2.py __init__ binds agent_executor/task_store/etc. but has no self._queue_manager = queue_manager (contrast default_request_handler.py:123, which does store it and uses it at lines 209/313/503/611).
• v2 uses the registry instead: self._active_task_registry = ActiveTaskRegistry(...).

Testing

Added two tests to tests/server/request_handlers/test_default_request_handler_v2.py:

• test_init_warns_when_queue_manager_passed — asserts a WARNING mentioning queue_manager is logged (fails on main, passes with the fix).
• test_init_no_warning_without_queue_manager — asserts no such warning in the default case.

uv run pytest tests/server/request_handlers/            # 195 passed

ruff check, ruff format --check, and ty check all clean on the changed files.

This change was developed with AI assistance; I verified the root cause and behavior against the code paths cited above, reviewed every line, and ran the tests.

[github-actions]

🧪 Code Coverage (vs main)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/server/request_handlers/default_request_handler_v2.py	94.17%	94.20%	🟢 +0.03%
Total	92.97%	92.97%	⚪️ 0.00%

Generated by coverage-comment.yml

[chopmob-cloud]

Confirmed the root cause on current main: DefaultRequestHandlerV2 still accepts queue_manager in its signature (84) but never stores or uses it, since V2 drives streaming through ActiveTaskRegistry (108). A caller passing a Redis-backed QueueManager gets it dropped with no signal, which is the exact failure in the issue. Warning on a non-None value is a reasonable stopgap given that actually honoring a distributed manager in V2 is an architectural change, and it does satisfy the issue's stated bar (either the parameter works, or passing one warns).

One suggestion to make the warning land where it matters. logger.warning surfaces in server logs, but the point of the issue is that this is easy to miss, especially across replicas. warnings.warn(..., DeprecationWarning, stacklevel=2) would put the signal at the caller's construction site, make it catchable and filterable in test suites, and read as a deprecation of the parameter rather than a runtime log line. Emitting both (the DeprecationWarning plus the existing log) would cover interactive and headless callers. Since the parameter is being kept only for backward compatibility, stating that deprecation in the docstring would also carry it into the generated API docs.

Tests and CI are green. This is a clean interim fix; the warnings.warn form would match the issue's raises-or-warns framing a little more faithfully.