fix(client): a 304 confirms a payload rather than establishing one

[XieX]

Summary

Fixes a path in the FDv2 delivery transport that could report a store holding nothing as initialized, which authorizes write_skills("*") to prune every managed SKILL.md on disk. Raised by Bugbot on #87 (comment r4146430929); verified reachable, and traced to two claims that were wider than what happened.

A poll adopted the response ETag after any body that did not raise, and a 304 published a first payload unconditionally. Between them, a body this SDK could not apply — a future intentCode, or a payload-transferred with no recognized intent — lent its etag to the next request, and the 304 that answered it reported the empty committed set as current: initialized, healthy, and with nothing in a 304 to notice it on.

Three claims narrowed:

• payload-transferred reports a commit only when it applied a pending set. A none intent builds none, nor does an unrecognized intentCode, and a foreign payload's contents are declined — those transfers now report nothing, where they reported a commit. They no longer adopt the selector of a payload that was never applied either, which on its own left a store resuming from content it does not hold while every diagnostic read healthy.
• A poll adopts the response ETag only from a body that completed an exchange: a committed payload, or a none intent, which is the server saying the content held is what the etag describes. Gating on the commit alone would have broken the steady state — the none body's etag is how a poll goes from a tiny 200 every interval to a bodiless 304.
• A 304 no longer publishes a first payload. It confirms the payload the store holds; the exchange it stands in for, the none intent, does not publish one either.

Not a new rule: TESTING.md §3.25 already defines is_initialized() as true "once a payload has committed", and §3.21/§3.22 turn prune suppression on it. The spec gains the bullets that were missing for the poll path in launchdarkly/ai-sdks-monorepo#34, and js-ai-sdk carries the identical fix in launchdarkly/js-ai-sdk#104.

test_a_304_before_any_payload_still_releases_wait_for_skills justified the old behavior as "a reconnect with a cached basis", which this transport has no mechanism for — _basis and _etag both start as None with no injection point — so a 304 reaching a store that holds nothing takes a server answering a request that carried no etag at all. It now fails closed, and the test asserts that.

Test plan

• pytest — 2164 passed, 11 skipped
• ruff check / ruff format --check / mypy packages/*/src clean
• New: a body under an unrecognized intent leaves the next request carrying no If-None-Match, the store uninitialized, nothing held, and no selector adopted
• New: all four shapes that reach payload-transferred with no pending set report neither a commit nor an up-to-date answer, and still count the transfer
• Rewritten: a 304 answering a request that carried no etag leaves wait_for_skills false and is_initialized() false without recording a failure
• The over-cap poll test was leaning on the same path for its "delivery carries on" assertion; its retry now gets a real payload

🤖 Generated with Claude Code

---

Note

Overview
Fixes FDv2 poll/stream handling so an empty or unapplied store cannot become is_initialized() and authorize write_skills("*") to prune every managed skill on disk.

payload-transferred now commits (and adopts resume basis) only when a pending set was actually applied—none, unknown intent codes, foreign payloads, and lone transfers with nothing pending report no commit, no up-to-date signal, and no basis.

Polling stops treating HTTP 304 as publishing the first payload; it only confirms content already held. Response ETags are adopted only after a poll body completed an exchange (a real commit or a none intent on its own event). _apply returns that completion flag so bodies the SDK declined cannot lend an etag to a later 304.

agents.md documents the three coupled rules. Tests are updated for the old 304-boot behavior and add coverage for the unrecognized-intent → etag → false-healthy chain.

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