Personal-kit API gaps for AgentKit kit publish/sync #88

Activity

1. mrgoonie

   self-assigned this

   on Oct 15, 2026
2. mrgoonie commented on Oct 16, 2026

   

   mrgoonie

   on Oct 16, 2026

   ContributorAuthor

   More actions

   Status of every item, from the code on main plus #94. #94 references this issue but does not close it.

   #	Item	Decision
   1	Composition metadata	Done in #94
   2	If-Match / 412	Done in #94
   3	Overlay on a foundation (shared) skill	Deferred
   4	@agentkit/* bases	Owner/ops decision, options below
   5	Session proposals	Already exposed by #83, nothing to add
   6	Pin any published, non-yanked base	Already supported, now tested and documented in #94
   7	extends: skillx:<kit>	Declined as a new server feature: parent already covers a kit, and a release base depends on item 4

   1. Composition (done). A revision document may carry an optional composition: {extends, include?, resolutions?}. It mirrors the AgentKit manifest extends/include and the agentkit.skill-overlay-resolution/v1 records.

   • Validation is strict and nothing is reordered.
   • It is part of the revision digest. A document without it keeps its old digest, and the existing golden vector is unchanged. The new vector is packages/contracts/src/fixtures/personal-kit-composition-golden.json.
   • SkillX stores it verbatim and never interprets it.
   • Rebase and conflict-resolution revisions drop it, because they move the pins it describes.

   2. If-Match (done). Every generation-guarded write accepts If-Match: "g<n>" (the kit ETag) or a bare <n>.

   • A stale value gives 412 kit.generation_conflict.
   • The body expectedGeneration still works and keeps its 409.
   • If both are sent, they must agree; otherwise the request gets a 400.

   3. Overlay on a foundation skill (deferred). The refusal does not come from lineage. It is the shared-alias guard, overlay.shared_alias.

   • The guard always treats ak-/ak: skills as shared, plus the identities in SKILLX_SHARED_SKILL_ALIASES. Every other @agentkit/* skill can already be overlaid in place (see kit-revisions.test.ts).
   • feat(personal-kits): immutable lineage, structured overlays and conflict-safe foundation rebase #55 lineage is a kit-to-kit parent chain. It has no notion of several foundation owners of one alias, so it can't decide precedence for a shared skill cheaply.
   • The guard mirrors AgentKit's own rule (its contract section 7.4: "fork it instead"). Relaxing it needs AgentKit to define precedence for a shared alias first.
   • Revisit once AgentKit specifies that. Until then, the fork path is the supported answer.

   4. @agentkit/* bases (owner/ops decision). Bases resolve only through SkillX releases. Options:

   • (a) Mirror the releases on SkillX (recommended).

     • An operator provisions the @agentkit publisher with POST /api/v1/publishers (admin secret).
     • AgentKit CI publishes each foundation with a scoped releases:publish:@agentkit key.
     • This needs SKILLX_RELEASES_API on in production, migration 0012 applied, and a D1 backup before any apply.
     • No code change is needed.

   • (b) Accept a signed AgentKit release manifest as a base.

     • This adds a second trust root, with key distribution and rotation, and either byte storage or fetch-on-verify for composition digests.
     • Large, and duplicates (a).

   • (c) Status quo. AgentKit keeps failing safe.

     No action was taken here.

   5. Session proposals. #83 serves them on the same personal-kit API AgentKit already uses: POST /api/v1/kits/@h/k/proposals/validate, POST .../proposals, GET .../revisions/:id/proposal and POST .../revisions/:id/review (web session only), behind SKILLX_PERSONAL_KITS_API. The envelope is skillx.kit-proposal/v1, and the policy is shared via #87. Consuming it is AgentKit G4 slice 4.

   6. Pins on older releases. loadPinnedBase already resolves any release the owner can read, by package, version and digest. It never compared against the newest release.

   • feat(kits): If-Match preconditions and composition metadata for personal kits #94 adds a test: an older release stores, activates and locks with no warning.
   • A yanked pin still stores, with a warning, so existing kits keep working. New pins should still avoid yanked versions.
   • If AgentKit saw "must be current", the constraint was on its side.

   7. extends: skillx:<kit> (declined as a new server feature).

   • For a SkillX personal kit, the document's parent: {kit, revisionDigest} already expresses it: one parent, depth 4, and a foreign parent must be public and activated.
   • For a SkillX release foundation (the AgentKit skillx: + releaseDigest form), the entries already pin releases. What is missing is a published foundation, which is item 4.
   • composition.extends now accepts the skillx form as metadata, so AgentKit can record it.

   AgentKit follow-ups (bestagentkits/agentkit#2278):

   • Send If-Match: "g<n>" and map 412 like 409 (exit 6).
   • Emit and read composition, and compare against the new golden vector.
   • Map extends: skillx:<kit> to parent.
   • Keep the fork path for shared skills.
   • Take up proposals in G4.