feat(client): Agent Skills — the FDv2 delivery transport

[XieX]

Stacked on the protocol-layer PR (xie/skills-fdv2-protocol). Third of three PRs split out of #69, and the one that makes the feature real: the network underneath the protocol reader, exported as FDv2SkillStore.

Why this shape

Skill content arrives over GET /sdk/poll and GET /sdk/stream, authenticated with the environment's server-side SDK key. These are the SDK-facing endpoints the base SDK's FDv2 data source uses, and the channel that payload signing will eventually cover. No private route is involved, and no credential other than the environment's own SDK key ships to a customer host. Standard library only, so the content path adds no dependency to a package whose sole runtime dependency is opentelemetry-api.

What's here

FDv2SkillStore. Authenticates, streams (default) or polls, carries basis across requests, sends If-None-Match and treats 304 as a first-class current answer, and serves get_object / all_objects / add_listener / remove_listener from what the protocol reader has committed. Capped jittered backoff; Retry-After honoured but clamped to max_backoff and rejected when non-finite; bounded consecutive-failure retries, where a committed payload resets the count. One network timeout, read_timeout, whose default follows the mode: 10s for a whole poll, 300s between reads on a stream. A mobile key or client-side environment ID raises from the constructor. Last known good survives every failure; diagnostics and failed report the degradation.

close interrupts the socket. The delivery thread parks in a read no flag can reach, and closing a urllib response from another thread does not unblock CPython's buffered reader, so _interrupt_read shuts the socket down underneath it. Without that every shutdown of a healthy stream blocked for the full join timeout.

Above the interface, two strings: NO_STORE_MESSAGE now names FDv2SkillStore first, since it is the first thing a user sees on a missing store and offering only the development store was wrong once a production transport existed; and watch_skills' refusal message names it as the store with a delivery transport.

Bugs found and fixed while testing the loop

Five, all sharing one shape: the store stopped delivering while continuing to report itself healthy.

• The consecutive-failure counter never reset in stream mode. _stream_once always ends by raising, so a reset on return was unreachable and failures grew for the whole process lifetime. Eleven fully successful payload transfers were enough to trip max_consecutive_failures and stop delivery for good, revocations included. A commit now resets the count, in _apply.
• A non-finite Retry-After killed the delivery thread. float("inf") parses, and Event.wait(inf) raises OverflowError from inside the recoverable-error handler. Non-finite values are rejected and every honoured delay is clamped to max_backoff.
• close() during the initial connect waited out its full join timeout. self._connection was assigned after the connect returned, so a close() in that window found nothing to interrupt. The stop flag is re-checked immediately after the assignment.
• close() blocked for the full join timeout on every healthy stream. See _interrupt_read above.
• A stream interrupted by our own close was reported as a delivery failure.

Also: connect_timeout was accepted and never used, so a poll against a black-holed host hung for 300s rather than 10. It is gone, with the request timeout now chosen by mode, and TestTimeouts measures the bound against a socket that accepts and never answers.

Tests

Rebase note. The previous push of this branch had silently reverted the protocol PR's last commit (payload identity: payloads_ignored, _is_foreign_payload, TestPayloadIdentity). Rebasing onto the updated protocol branch restored it; the full suite passes with it present.

_FakeFDv2Endpoint is an in-process ThreadingHTTPServer implementing the wire contract, so request construction and header handling are exercised over real sockets rather than mocked. Covers skill put/delete over the wire, mixed payloads, 304, basis round-tripping, reconnect/backoff in both modes, Retry-After including non-finite and oversized values, bounded retries and the reset on commit, prompt shutdown during connect and during a healthy stream, hashless envelopes end to end through the accessors, server-side-only credentials, timeouts, and watch_skills over the transport: a wire-level revocation pruning a file without a restart.

Full suite 1629 passing, 11 skipped; ruff, ruff format, and mypy clean.

Open items, none in this PR's scope

• 🔴 contentHash is not on the wire yet. Against a real environment today every skill resolves to nothing. This PR makes that loud (an error per hashless object, a summary per wholly-hashless payload, diagnostics.hashless_objects) rather than surviving it.
• 🔴 Server-side skill delivery is not deployed. The wire shape this store reads — kind skill, key <key>:<version>, generic payload — is what streamer #4681 and gonfalon #70638 emit; both are still open. No account can receive skill objects until they ship and the producer is enabled.
• 🟡 FDv2 is opt-in per account. A real environment returns 403 today; the store reports it as fatal and explains what to do.
• 🟡 mv is a guess. Resolved: the request sends no mv. That parameter selects the flag data model and the connection rejects any value but the flag default, while the generic agent-skill payload is served regardless of it. The data_model_version constructor argument is gone with it.
• 🟡 No payload signing on this channel yet, so Beta is TLS-only.
• 🟡 The connection also carries the environment's flags. Skipped and counted; a transport property, not fixable here.
• 🟡 ld-relay does not speak the FDv2 endpoints, so relay-only deployments cannot receive skills in Beta.

Nothing here has touched a real LaunchDarkly environment, because it cannot yet.

🤖 Generated with Claude Code

---

Note

Overview
Adds FDv2SkillStore, a production SkillStore that pulls agent skills over LaunchDarkly’s SDK FDv2 /sdk/poll and /sdk/stream endpoints (stdlib HTTP, background delivery thread, stream-by-default). It implements SkillStore (get_object, listeners, etc.) on top of the existing protocol reader, plus StoreDiagnostics, wait_for_skills, capped backoff with Retry-After, and close that interrupts blocked socket reads so shutdown is prompt.

Public surface: FDv2SkillStore and StoreDiagnostics are exported from the package; README documents production setup with init_client and watch_skills. Server-side SDK keys only; mobile/client credentials are rejected. Outages keep last-known-good content; accessors above the store are unchanged.

Delivery-loop fixes bundled here: reset consecutive-failure counts on successful commits / up-to-date answers (so healthy stream recycling does not stop delivery), safe handling of non-finite Retry-After, and not treating intentional close interrupts as transport failures. Removed unused connect_timeout; read_timeout is the single knob with mode-specific defaults.

Tests: in-process fake FDv2 server exercises poll/stream, basis/ETag/304, revocations, retries, timeouts, hashless payloads, and watch_skills over the transport.

^{Reviewed by Cursor Bugbot for commit 88c225e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c285ff5. Configure here.}

[andrewklatzke]

Bit of concern re: what the process is going to look like for users (if I just wanna try out skills during the trial and need to contact support for opt-in to fdnv2 etc.)

Same nit/question as on the other PR about whether we thought about making this more generic for future implementations. A lot of the stuff in skills_fdv2 seems like fairly-reusable code. Not a priority right now but we should think about it.

[andrewklatzke]

This is a lot of friction that is going to stop folks in their tracks imo - they need to contact support to opt into this? Is it on by default for new accounts?

[XieX]

I agree, it's a huge barrier. The short answer is I don't know. Mitigating it (turning it on by default for new accounts, turning it on for AgentControl signups etc) is a followup task 👍