feat(ble-proxy): pluggable connect_strategy hook for MatterBleProxy

[Apollon77]

Summary

• Adds an optional connect_strategy callable to MatterBleProxy so embedders can plug in bleak_retry_connector.establish_connection (or any other connection helper) without making it a hard dependency of the library.
• New public helper matter_ble_proxy.default_connect_strategy(target, on_disconnect, timeout_ms) keeps the plain-Bleak behavior for the standalone CLI.
• _handle_connect delegates to the strategy; existing TimeoutError / generic-Exception → connection_failed mapping is preserved, so error semantics on the wire don't change.

Generic hook, not HA-specific. Connection establishment is already the library's responsibility (_handle_connect constructs the BleakClient and calls .connect()); the hook makes that one step pluggable so any embedder — bleak-retry-connector users, custom connection pools, telemetry wrappers — can supply their own helper. Home Assistant is the first consumer; the library stays dependency-free.

Why

Home Assistant's habluetooth.wrappers warns whenever BleakClient.connect() runs outside bleak_retry_connector.establish_connection. During BLE proxy pairing through HA you see:

habluetooth.wrappers C8:8B:A4:F7:57:32: BleakClient.connect() called without
  bleak-retry-connector. For reliable connection establishment, use
  bleak_retry_connector.establish_connection().

Functionally pairing succeeds, but we lose adapter path scoring + the retry policy HA uses everywhere else. With this hook the HA integration can pass establish_connection while the library stays Bleak-only.

Strategy contract

ConnectStrategy = Callable[
    [BLEDevice | str, Callable[[BleakClient], None], int],
    Awaitable[BleakClient],
]

Strategy receives (target, disconnected_callback, timeout_ms) and returns a connected BleakClient. The library applies no extra timeout — the strategy owns its retry/timeout policy.

Follow-up

The Home Assistant matter integration PR (home-assistant/core#171384) will pin to the released version of this change and pass an establish_connection-backed strategy from homeassistant/components/matter/ble_proxy.py.

Test plan

• npm run python-ble-proxy:lint
• npm run python-ble-proxy:typecheck
• npm run python-ble-proxy:test (12 passed, including 6 new in test_connect_strategy.py)
• npm run python-ble-proxy:build
• Real-device pairing through HA against a 0.7.2 build of the library — verifies the warning is gone end to end (deferred to the HA-side PR once the lib release is out)

[Copilot]

Pull request overview

Adds a pluggable BLE connection hook to the Python BLE proxy client so embedders (notably Home Assistant) can supply a custom connection-establishment routine (e.g., bleak_retry_connector.establish_connection) without introducing a hard dependency, while keeping the existing on-the-wire error semantics intact.

Changes:

• Introduces connect_strategy (optional) on MatterBleProxy, defaulting to a new default_connect_strategy.
• Refactors _handle_connect to delegate connection establishment to the selected strategy while preserving TimeoutError / generic exception → connection_failed mappings.
• Adds unit tests covering default vs custom strategy behavior and error mapping.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
python_ble_proxy/matter_ble_proxy/client.py	Adds default_connect_strategy, threads optional connect_strategy through MatterBleProxy, and delegates _handle_connect to it while keeping existing error mapping.
python_ble_proxy/matter_ble_proxy/init.py	Exposes default_connect_strategy as part of the public package API.
python_ble_proxy/tests/test_connect_strategy.py	Adds unit tests validating strategy wiring, invocation, and error mapping behavior.

[mxssmu]

Independent validation on macOS 26.5.1 arm64, Node v26.3.1, Python 3.13.14: clean build;
TS suite 244/244; python_ble_proxy 12/12 including the 6 new connect_strategy tests.
Merges cleanly onto main, v1.1.2, and v1.1.7, and combines cleanly with #704. We run a
~47-node HA Matter deployment with a reproducible post-C3 BLE-proxy failure class and
can field-test the bleak_retry_connector.establish_connection strategy once the HA
consumer lands.

[Apollon77]

As also posted in the other issue ... try HA 2026.7 please and report back

[mxssmu]

@Apollon77 Reported back on #704 with full detail
(#704 (comment)): summary -- HA Core 2026.7.0b1 + add-on 9.0.3 (matterjs-server 1.1.2), 6
factory-fresh Govee H6013 today. 3 of 6 commissioned fine over the BLE-proxy path
(2026.07 is a real improvement -- we saw 0/4 on 1.1.1/1.1.2), but the other 3 failed every
one of roughly 15 attempts, device-sticky, latterly with No commissionable device was discovered while the ESPHome proxies saw their 0xFFF6 advertisements all along; the same 3
then commissioned 3/3 over IP (network_only) in 15-41 s. So the class this PR and #704
target is narrower on 2026.7.0b1 but still alive. Happy to rerun on 2026.7 final and to
field-test the connect_strategy once the HA consumer lands.

[Apollon77]

Yes and repeated: Issue discussion on PRs is wrong place and do not double post please. Thanks