feat(client): Agent Skills — the FDv2 delivery protocol, without the network

[XieX]

Stacked on the watch_skills PR (xie/skills-watch). Second of three PRs split out of #69; the transport that puts a connection underneath this follows.

The half of the delivery transport that has no I/O: identifying a skill object on the wire, translating it into the raw object shape the SkillStore interface defines, holding it by (key, objectVersion), and applying a payload's events as one consistent commit. Splitting it out lets the three decisions that matter most be reviewed without a socket in the way.

Three things worth reviewing closely

1. The skill's version is in the object's key; version is the payload's. Each version of a skill is its own object on the wire, identified as <key>:<version> (pdf-extraction:3), and that is the only place the skill's version appears. The event's version is the payload's, and confusing the two fails silently: the object verifies, the hash matches, and the caller gets content under a version number that means nothing. The wire key is split in exactly one place (_split_wire_key), both the put and the delete translation go through it, and TestVersionTranslation asserts it in both directions. A key that will not split cleanly is held rather than dropped — version-less, or with the offending text as its version — so verification withholds it with invalid_version under a key the caller recognises; only a key with nothing before the delimiter is dropped.

2. Changes commit at payload-transferred, not per object. A payload version is the unit of consistency. A half-applied full transfer would publish a state the server never described and would briefly empty the store, which, with pruning on, is the difference between a reconcile and deleting a customer's skill files. An interrupted transfer leaves last known good intact, and listeners fire once per commit.

3. A hashless object is held, not dropped. Dropping it at the transport would report absent, indistinguishable from "no such skill", and would let a prune delete the last known-good copy on disk. Holding it means verification withholds it with missing_content_hash, which is diagnosable: an ERROR per (key, version), deduped per reader rather than per process so two stores never quieten each other, a summary per wholly-hashless payload, and a StoreDiagnostics.hashless_objects counter. There is deliberately no fallback that synthesises a hash from the delivered content.

Also here

• Skills are kind == "skill"; everything else is ignored, not rejected. Object kinds on the SDK-facing channel are open strings and the agent-skill payload is classified generic, so a skill arrives under the kind its producer registered — the bare category name — with no category or objectVersion field (streamer #4681, gonfalon #70638). An environment's assignment carries its flag payload alongside its agent-skill payload, so flag and segment objects arrive as a matter of course. Erroring on them would turn a normal payload into a permanent reconnect loop.
• _SkillObjectSet holds several versions of one key, with lookup semantics identical to InMemorySkillStore down to the fall-through to a version-less entry. Its opaque snapshot keys are spelt <key>:<version>, the same as the wire, and a test pins that round trip. TestInterfaceParity asserts the two resolve identically.
• _require_server_side_credential refuses a mobile key or client-side environment ID. Its tests arrive with the store constructor that calls it.

Nothing here is exported yet; the store exports it. The module imports nothing from the feature but the version validator.

Tests

test_skills_fdv2.py drives _ProtocolReader directly: identification, version translation, full and change transfers, interruption, revocation, tombstones, mixed payloads, unknown kinds and events, error and goodbye, and the hashless dedupe across readers. The wire builders it introduces are shared with the transport PR's fake endpoint.

🤖 Generated with Claude Code

---

Note

Overview
Adds skills_fdv2.py, a stdlib-only layer below SkillStore that parses LaunchDarkly FDv2 events without sockets. It maps wire put-object/delete-object into the raw store shape, keeps skills in _SkillObjectSet, and applies updates atomically in _ProtocolReader at payload-transferred (not per object).

The critical wire rule is key = skillKey:objectVersion while the event’s version is the payload revision and is dropped—confusing them would silently serve the wrong pinned version. Non-kind == "skill" objects (flags, segments) are ignored, not errors. Foreign payload full transfers are declined once skills’ payload id is known, so a flag xfer-full cannot wipe held skills (and trigger prune). Hashless skills are retained for verification to withhold with missing_content_hash, with StoreDiagnostics and loud logging. _require_server_side_credential rejects mobile/client credentials (for the upcoming networked store).

agents.md documents the transport contract; skills_core clarifies SKILL_OBJECT_KIND vs wire kind. test_skills_fdv2.py (~900 lines) exercises the reader, version translation, payload identity, and parity with InMemorySkillStore. Nothing is exported or wired from accessors yet—that’s the follow-on transport PR.

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ 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 0f797c0. Configure here.}