[XieX]

Fixes the must-fix-before-merge findings from the pre-release review of Agent Skills (reviewed at c27005c). There is one commit per fix, and each fix has a test that fails without it.

Fixes

1. The process exited while await store.waitForSkills() was pending (ca79d2f). The wait's setTimeout was unreffed. When LaunchDarkly is unreachable, the backoff and deadline timers (also unreffed) are the only other handles, so node exited mid-await: exit 13 under ESM top-level await, and exit 0 in CommonJS without running the next line. The wait's timer is now referenced. It is bounded by the timeout and cleared when the wait is released. The backoff and deadline timers stay unreffed.
   Test: child-process scripts, run through tsx against the source: ESM top-level await, a CommonJS async function, and a never-started store. Each asserts exit 0 and that the wait resolves false at the timeout.
2. A streamed event whose data is not JSON was dropped, and the transfer still committed (88e21c1). A corrupted delete-object kept a revoked skill served, because the reconnect sent the advanced basis. A corrupted put-object inside xfer-full revoked that skill by omission. iterSse now throws RecoverableTransportError, so the in-flight payload is abandoned and the reconnect resumes from the last committed basis. This matches js-sdk-common's PayloadStreamReader, which reports InvalidData; StreamingProcessorFDv2 then stops the source. Only the six events the reader acts on are parsed (server-intent, put-object, delete-object, payload-transferred, goodbye, error). A heart-beat or an unknown event is yielded with null data, so its data can't end the connection (4f2375f).
   Tests: commit {a:1, b:1}, then send xfer-changes with put c:1, a corrupt delete-object a:1, and payload-transferred. The test asserts that the reconnect carries basis-1, that listeners see c:1 once (from the clean retransmission), and that the retransmission revokes a. A second test commits a:1, then sends an xfer-full with a clean put b:1 and a corrupt put a:1. It asserts the reconnect carries basis-1, a is never revoked, and b reaches listeners once. iterSse framing tests cover the corrupt delete-object, plus a heart-beat and an unknown event with data: not json. Framing tests also pin the parse set (all six), and a store-level test streams a catastrophic goodbye through iterSse (7978770). Empty data on a known event is not JSON either (fe8e5ec). Read as null, a delete-object was ignored and a payload-transferred committed with no selector. Two protocol-reader tests pin the experimental-stage rule for a put or delete with no usable key: it is warned and ignored, and its transfer commits (TESTING.md §3.25, ai-sdks-monorepo#48).
3. A goodbye with catastrophe: true was fatal until start() (c71345e). Neither base JS package reads catastrophe, and the streamer sets it on its own connection-error path. It is now a recoverable disconnect. It is counted even after a completed exchange (never expected), recorded in lastError, and logged at error level whatever silent says.
   Test: the reader test that pinned the fatal reading now asserts the new outcome. A store-level test covers a commit followed by a catastrophic goodbye: the store reconnects, failed stays null, and the goodbye is logged at error level.
4. skillRefs(null) returned [] (9466bd8). inspectConfig answers config: null on any failure, so writeSkills(skillRefs(info.config), root) pruned every managed skill during an outage. A config that is not an object, null and undefined included, now throws TypeError. An object with no skills field still returns []. The TSDoc, the README pipeline example and the API table are updated.
   Test: non-object configs (null, undefined, string, number, boolean, array), plus a failed inspectConfig whose config throws.
5. Docs (fa44c1a). The README promised that ld.skills.integrity_failure would not change "outside a major release". It now says that, while the feature is experimental, the record may change in a minor release with a changelog entry under Experimental.

Cross-SDK and spec

• python-ai-sdk#148 makes the same changes. Python's skill_refs(None) now raises ValueError (JS throws TypeError), so the two SDKs agree apart from the error class, which A.12 records.
• ai-sdks-monorepo#48 carries the spec text: the catastrophic-goodbye carve-out in §3.25, the experimental-stage wording for the integrity event in §3.24 and A.12, the non-object rule in §3.20, and the non-JSON rule in §3.25.

Checks run locally

yarn build, yarn test (client: 1325 passed, 10 skipped), yarn typecheck, yarn code:check, and yarn workspace @launchdarkly/ai-server api:check. The only API-report changes are source line numbers in a comment.

🤖 Generated with Claude Code

---

Note

Overview
Addresses pre-release must-fix issues in experimental Agent Skills: safer config projection, more resilient FDv2 streaming, and process-lifetime behavior during outages.

skillRefs no longer treats a failed inspectConfig (config: null) as “no skills” — non-object configs (including null/undefined) now throw TypeError so writeSkills(skillRefs(config), …) cannot prune every managed skill during an LD outage. README/docs and tests are updated accordingly.

FDv2 SSE (iterSse) now fails the connection with RecoverableTransportError when a known protocol event’s data is missing or not JSON (instead of skipping it and still committing payload-transferred). That abandons the in-flight transfer and reconnects from the last committed basis, fixing cases where a bad delete-object left revoked skills served or a bad put-object in xfer-full revoked by omission. Only the six reader-handled events are JSON-parsed; heartbeats/unknown events stay null data.

Catastrophic goodbye is no longer fatal (delivery keeps retrying); it is always counted in connectionFailures, sets lastError, and logs at error level even when silent.

waitForSkills keeps its timeout timer referenced (other store timers stay unreffed) so Node does not exit mid-await when delivery is down and nothing else holds the event loop.

Docs clarify that ld.skills.integrity_failure may change in minor releases while Agent Skills is experimental.

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

[jeffdupont]

All four fixes match py #148, and the catastrophe and skillRefs changes look right. At fa44c1a9 I get 1306 passed and 10 skipped, and typecheck and code:check are clean. Two things should be fixed before this merges. Both are the same as on py #148, so the twins can change together. Details are inline.

1. A heart-beat or unknown event with data that is not JSON now ends the connection. I ran it: the probe is below.
2. Nothing tests a non-JSON put-object inside an xfer-full. The PR body and agents.md both claim that case.

Smaller:

• The PR body is stale. It says "Python's skill_refs(None) still returns []". py #148 (77023bb8) makes it raise, so the two SDKs agree now.
• The error class differs. JS throws TypeError and Python raises ValueError, with the same rule otherwise. Could #48 record which each SDK raises, the way A.12 does for the malformed-skills error?
• A delete that is valid JSON but the wrong shape still commits the rest of its transfer. An example is a delete-object with no usable key, which :444 warns about and ignores. So the revoked skill stays served. I checked this in Python (6 shapes) and only read the JS code, so treat the JS half as unverified. ldclient interrupts on most of these shapes. This is worth a decision in #48 rather than a change here.

[XieX]

@jeffdupont, thanks. Both fixes are in at 4f2375f, with replies inline. At that commit the client package has 1309 passed and 10 skipped, and typecheck, code:check and api:check are clean. js-ai-sdk#121 is stacked on this branch, and I've merged the new head into it (627703a).

• Stale PR body: fixed. The "Divergences" section is now "Cross-SDK and spec". It says Python raises ValueError from python-ai-sdk#148, and that the spec text lives in ai-sdks-monorepo#48.
• Error class: ai-sdks-monorepo#48's A.12 "Reference accessor" row now records it: ValueError in Python, TypeError in TypeScript, matching the §3.20 bullet.
• A delete that is valid JSON but the wrong shape: I agree it's a decision for https://github.com/launchdarkly/ai-sdks-monorepo/pull/48, not something to change here. I've left it open there.

[jeffdupont]

Re-reviewed at 4f2375fa. Both fixes are in, and every claim in your replies checks out. One small test gap (below) should be closed before merge, and then I'd approve.

At 4f2375fa the client package has 1309 passed and 10 skipped. typecheck, code:check and api:check are clean, and CI is green. Trial merges onto xie/agent-skills-feature-ac9ac7 (7fc790a) and onto main (993225f) are clean.

• Parse only known events: EVENTS_WITH_DATA (skills-fdv2.ts:83-90) is exactly the six handle cases that read data (:682-701). Data flows only from streamOnce to apply to handle, so null data for heart-beat and unknown events is safe. When I restored parse-every-event, both new cases failed.
• js-sdk-common: PayloadStreamReader in 2.25.1 attaches handlers to the same six events (dist/cjs/index.cjs:3325-3330) and reports InvalidData on a failed JSON.parse. So the parity claim in #48 holds.
• xfer-full test: if a non-JSON put-object is skipped instead of dropping the connection, only the new test fails (1 failed, 1308 passed).
• Framing tests moved to put-object: they go through framed(), which runs only the event parser, so the event name has no side effects. No coverage lost.
• PR body and README: both up to date. README.md:332 says skillRefs throws TypeError for null / undefined.

Fix before merge: nothing tests that a goodbye reaches handle with its data parsed. I removed EVENT_GOODBYE from EVENTS_WITH_DATA, and all 1309 tests still pass. A goodbye would then arrive as null, catastrophe: true would never be read (:870-889), and a catastrophic goodbye would become an uncounted recycle. That undoes c71345e. Both catastrophe tests skip the stream parser: one calls handle directly (skills-fdv2.test.ts:855), and the store test at :2350 gets already-parsed events from UnchangingRequester. EVENT_ERROR has the same gap, but there only the logged reason is lost. Inline. py #148 has the same gap.

[XieX]

@jeffdupont, thanks. The goodbye gap is closed in 7978770 (inline). Since then, fe8e5ec makes the same wrong-shape decision as python-ai-sdk#148. Empty data on one of the six known events now ends the connection, since js-sdk-common reports a known event with no data as an error. Its framing tests cover all six names, and the store test for a corrupt delete runs for both cut-short and empty data. A put or delete with no usable key stays warned and ignored for the experimental stage, as #48 §3.25 now records. Two protocol-reader tests pin that rule.

At fe8e5ec the client has 1325 passed and 10 skipped, and typecheck, code:check and api:check are clean. I've merged it into js-ai-sdk#121 (9da1400, 1337 passed).