[XieX]

Summary

Fixes a path in the FDv2 delivery transport that could report a store holding nothing as initialized, which authorizes writeSkills('*') to prune every managed SKILL.md on disk. Found by reviewing a Bugbot comment on the Python side and checking whether this SDK shared the gap — it did, line for line, including the tests.

A poll adopted the response ETag after any body that did not throw, 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:

• payloadTransferred 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. An unrecognized intent says the opposite — the body carried objects ignoreUnderUnknownIntent dropped — so leaving that poll unconditional is also what keeps the body arriving and its warning repeating, rather than silenced behind a 304. Gating on the commit alone would have broken the steady state, since 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 isInitialized() 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 python-ai-sdk carries the identical fix in launchdarkly/python-ai-sdk#129 (where Bugbot raised it, on launchdarkly/python-ai-sdk#87).

Five tests had pinned the old behavior here, against Python's one. Three were only this side's optional changes / basis reading undefined where Python's dataclass defaults give [] / null; the new outcome states both, so the two languages return the same object. The other two were real, and the second is the clearest evidence this drifted rather than being designed:

• releases waitForSkills on a 304 before any payload justified it as "a reconnect with a cached basis", which this transport has no mechanism for — basis and etag both start null with no injection point.
• A JS-only lifecycle test asserted a 304 counts as initialized — the payload held is confirmed current, over a store holding no payload. It now exercises the 304 this store can actually reach, offering an etag it earned.

Test plan

• yarn build && yarn test — full workspace green; client 1040 passed, 10 skipped
• tsc --noEmit and biome check 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 payloadTransferred 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 waitForSkills false and isInitialized() false without recording a failure

🤖 Generated with Claude Code

---

Note

Overview
Fixes FDv2 skill delivery so an empty store is never treated as initialized, which would let writeSkills('*') prune every managed SKILL.md on disk.

ProtocolReader.payloadTransferred now reports a commit only when a pending set was actually applied. Transfers that apply nothing—none intent, unknown intent codes, lone transfers, or declined foreign payloads—return no commit, no “up-to-date” signal on the transfer event, and do not adopt the payload selector as the resume basis.

Polling adopts the response ETag only after a body completes an exchange (a commit or a none intent on its own event). Bodies that announce transfers the SDK cannot apply no longer lend their etag to the next request.

HTTP 304 no longer calls markFirstPayload: it confirms content already held, it does not establish a first payload or release waitForSkills when nothing was ever committed.

packages/client/agents.md documents these three invariants. Tests are updated and expanded to pin the corrected behavior (including rejecting a standalone 304 before any payload and blocking etag/If-None-Match after unapplied bodies).

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

[jeffdupont]

Approving the fix. It matches python #129 line for line, and the spec's three 304 assertions (TESTING.md §3.25) are all here.

Before merge: this conflicts with the base now that #108 has landed (3 hunks in skills-fdv2.ts, 1 in agents.md), and the green CI is from before #108. I trial-merged 2709c66 into 43bfbc8, resolving every .ts hunk to this branch's side as python's daaf208c did. Dropping foreign || from basis is safe because the applied early return covers it. Result: vitest 1199 passed / 10 skipped, tsc and biome clean, #108's none-intent tests passing alongside. With the base's skills-fdv2.ts restored, 4 of the 5 new or rewritten tests fail. One trap: the 304 hunk's base side is this.markFirstPayload(), so taking it reinstates the bug.

One test gap, in both SDKs. §3.25 asks for all four no-commit shapes, and the loop here (and python's test_a_transfer_that_applied_nothing_is_not_a_commit) covers three. The declined foreign payload is missing. I put back the old foreign behaviour (applied without !foreign, basis keeping foreign ||), and the full suite still passed, because the foreign tests assert only basis. Could the foreign shape join the loop here, with a matching follow-up on the python side?