feat: add on_heartbeat_ack callback and close_connection method

[AlexanderZ-Band]

Summary

In short: adds two abilities band-sdk-python needs to build a heartbeat "watchdog" — a way to get notified when the server confirms a heartbeat (on_heartbeat_ack), and a way to force a reconnect without permanently shutting the client down (close_connection). While building it, found and fixed two real bugs: an oversized close reason could crash the client, and a forced reconnect wasn't guaranteed to actually happen (it depended on a code the remote server echoes back, not something we control) — both fixed. Also cleaned up a few duplicated magic numbers/strings into shared, named constants.

Part of INT-1323 — band-sdk-core (band-ai/band-sdk-core#60, merged) added a shared heartbeat_interval/dead_threshold policy that band-sdk-python will use to drive a watchdog against this client. Today there's no public way to observe heartbeat-ack liveness or force a reconnect from outside: phx responses are routed straight to a private callback (protocol_handler.py:158-161), and the only public teardown method, shutdown(), permanently ends the client.

• on_heartbeat_ack: Callable[[], None] | None — new constructor callback, mirrors on_reconnect/on_disconnect. Fires from the existing _handle_heartbeat_response right after _pending_heartbeat_ref clears; exceptions are caught and logged, same as the other two callbacks. Rejects an async callback passed by mistake (closes the coroutine and logs it as an error) instead of silently discarding it, since — unlike on_reconnect/on_disconnect — this one runs inline on the message-routing hot path and must stay synchronous and fast.
• close_connection(reason: str) — new public method. Verified shutdown() doesn't fit a watchdog's "close and let it reconnect" need: it cancels the supervisor task and transitions to CLOSED permanently. Also verified (correcting an earlier assumption) that band-sdk-python's auto_reconnect=False only guards its initial connect retry loop — once connected, the same PHXChannelsClient instance's own supervisor loop owns every subsequent reconnect, so there's no outer loop to rebuild it. close_connection closes just the current socket with a close code (4000, RFC 6455 §7.4.2 private-use range) outside _classify_disconnect's special-cased codes, so the existing reconnect classification decides what happens next — no new disconnect-handling branch.
  • The reason is truncated to fit RFC 6455 §5.5.1's 125-byte close-frame cap (123 bytes after the 2-byte code) before being sent — a realistic watchdog message could otherwise raise an uncaught ProtocolError.
  • A forced close now always reconnects, regardless of what close code the remote happens to echo back. _classify_disconnect reads the code the remote echoes, not the one we sent — a server that doesn't echo 4000 (e.g. answering 1000) could silently defeat close_connection under the default reconnect_on_normal_close=False. A _forced_close_pending flag now bypasses classification entirely for a close we initiated ourselves.

Also, while reviewing: reconnect_controller.py's close-code branches (1000, 1001, 1008, 1012, 1013) now use websockets.frames.CloseCode instead of raw ints; extracted _invoke_callback_safely for the on_reconnect/on_disconnect try/except-log duplication; added a shared PHOENIX_TOPIC constant (phx_messages.py) instead of the "phoenix" literal duplicated in protocol_handler.py/supervisor.py.

Test plan

• uv run pytest — 114 passed
• uv run ruff check / uv run ruff format --check — clean
• uv run pyrefly check / uv run pyright — 0 errors

Note

Supersedes #53, which was opened as a cross-repo PR from a personal fork (AlexanderZ-Band) because I didn't have write access to this repo at the time. Now that I do, this reopens the same branch/commits as a same-repo PR instead.

[linear-code]

INT-1323

[amit-gazal-band]

LGTM. One non-blocking finding worth a follow-up:

close_connection() can leave _forced_close_pending stuck True, causing the wrong reconnect decision on a later disconnect.

• close_connection() sets _forced_close_pending = True then calls await connection.close(...) with no exception handling — unlike the equivalent close in _cleanup_connection, which is wrapped in try/except Exception.
• The flag is only reset once the current disconnect cycle runs to completion (lines ~290–291).
• If connection.close() raises before that cycle completes (e.g. cancellation during shutdown, a non-ConnectionClosed error), the exception propagates and the flag stays True.
• On the next disconnect — even a legitimate server-initiated close (policy violation, or a normal close with reconnect_on_normal_close=False) — the supervisor takes the forced_close branch instead of running _classify_disconnect, reconnecting unconditionally and silently overriding the configured reconnect policy.

Suggest wrapping the connection.close() call in close_connection() in try/except like _cleanup_connection, and/or resetting _forced_close_pending on the exception path.