Repository navigation
fix(apps): list an app's skills as soon as its links change - #31675
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: the defect is measured, the fix acts where the cache goes stale (a writer that bypasses the loader), and no existing loader registry exists to reuse. What this change shipsInventory (5 items) — 5 justifiedIntent: an app's skills should show up in the skill list and the agents' catalog as soon as the app is enabled, and drop out as soon as it is disabled or uninstalled. FIX.
[FIRST-PRINCIPLES-REVIEWED] 59a8992 Description read[DESCRIPTION-READ] be59a4ba34f707b08e043dd2dce4b5e93207a08fe332a5ab3611128e3cb24fff That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns. The bridge now clears the cache its own link writes make stale, using the same invalidation the skill loader already runs after its own edits, and skips the clear when the links file would not change. Notes
[DESIGN-REVIEWED] 59a8992 Description read[DESCRIPTION-READ] 28224caa44612b6043e8286a8b7ca3ca190e0f0614684d8605564aa8865d5c01 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
e59feed to
75f27c5
Compare
|
Backend Tests shard 2 (Linux + Windows) and the Coverage Gate on e59feed were main's red, not this diff: both failed only |
75f27c5 to
c6ad349
Compare
|
Rebased onto |
c6ad349 to
a3dfa20
Compare
|
self-added: yes
|
|
CI reds on the old head c6ad349 were not test failures: |
Enabling, disabling or uninstalling an app links or unlinks its skills under the skills root, but nothing told the open skills loaders, so GET /api/skills and the agents' catalog kept serving the pre-change list for up to the 60 s catalog TTL: an uninstalled app's skills stayed listed, a just-enabled app's were missing, and a restart soon after served the stored snapshot without them. The bridge already rebuilds .app-skill-links.json after every link change. It now compares the rebuilt body with the file and, when the link set changed, invalidates every open SkillsLoader of that skills root (new skill_live_loaders module; each loader tracks itself weakly). An unchanged set, as the boot reconcile produces, writes nothing and keeps the snapshot, so a boot pays no cold walk. Part of #26967
a3dfa20 to
59a8992
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved for the on-call. Review lanes pass on 59a8992, no conflict, no open change request.
Problem / Motivation
Goal: An app's skills appear in the skill list as soon as the app is enabled, and disappear as soon as it is disabled or uninstalled.
Enabling an app links its skills under the skills folder, and uninstalling it unlinks them, but
GET /api/skills(and the agents' skill catalog) kept serving the list it already held. Measured onorigin/mainagainst an isolated gateway with an adopted papyrus: right afterPOST /api/apps/papyrus/enablethe five papyrus skills were missing for 66 s; right afterPOST /api/apps/papyrus/uninstallthey were still listed, pointing atskills/papyrus/...paths that no longer existed. A restart shortly after an enable served the stored snapshot without the app's skills.Why it matters
Every app that ships skills hits this on every enable, disable, uninstall and reinstall, and the five adopted former built-ins (#26967) all ship skills. For up to a minute an agent can be offered a skill whose files are gone, or miss one the user just turned on, and the skills page disagrees with the app list.
Not a goal
kirocrew app enablefrom the CLI): the gateway's loaders are not reachable from there, and it still converges on the TTL as any out-of-band change does.What changed (motivation → approach → change)
Symptom: app skills lag their links by the catalog TTL. Root cause: the app bridge changes the skills root without going through a
SkillsLoader, and only a loader's own mutators clear its cached list, its stored snapshot and its disabled-apps memo.The bridge already rebuilds
.app-skill-links.jsonafter every link change. It now compares the rebuilt bytes with the file: when the link set changed (or the file is not a readable regular file), it calls the newsrc/kiro_crew/skill_live_loaders.py::invalidate_loaders_of, which runs_invalidate_iter_cache()on every open loader of that skills root, exactly as a loader's own create or delete does. EachSkillsLoaderregisters itself there, weakly, at the end of__init__insrc/kiro_crew/skills.py, and the bridges facade (src/kiro_crew/apps/bridges.py) names the new import for type checkers. An unchanged link set, which is what the boot reconcile produces when it re-links what is already linked, writes nothing and keeps the snapshot, so a gateway boot pays no cold walk for this.The skills folder is writable from inside the sandbox, so the comparison (
_holds_exactlyinsrc/kiro_crew/apps/bridges_skills.py) opens the name without following a link and without blocking, and reads it only whenfstatsays it is a regular file. A FIFO or link left at that name is atomically replaced, never waited on.The app-kit-platform and memory-skills-hooks specs, and the TTL comment in
skills_discovery.py, name the new immediate path.Backwards compatibility
Compatible: the links file keeps its JSON format and keys; it is left untouched when its content would not change. It is written as bytes, so on Windows its newlines are
\nrather than\r\n; JSON readers accept both.Removes nothing: no path, key, record or function is removed or tightened.
Tests
test/test_app_skill_links_clear_catalog.pywarms a real loader's list, then changes the links and reads again with no clock or sleep:Proof: PROVEN test/test_app_skill_links_clear_catalog.py::TestAppSkillLinksClearTheCatalog::test_a_registered_skill_is_listed_on_the_next_read, test/test_app_skill_links_clear_catalog.py::TestAppSkillLinksClearTheCatalog::test_a_deregistered_skill_is_gone_on_the_next_read, test/test_app_skill_links_clear_catalog.py::TestAppSkillLinksClearTheCatalog::test_a_fifo_at_the_links_name_is_replaced_not_waited_on (head b4184a7f0621)
Determinism: 20/20 at
-n0, 10/10 at-n 4 --dist loadgroup --max-worker-restart=2withtest_app_bridges.pyandtest_skill_catalog_snapshot.pyas co-tenants, and a shuffled order (seed 5894, 85 ids withtest_app_bridges.py) green. The FIFO test: 20/20 at-n0, 10/10 at-n 4withtest_app_bridges.py, and the file's six tests in a shuffled order (seed 31675) green.test_app_bridges.py,test_skill_catalog_snapshot.py,test_skills_composition_contract.py,test_skills.py,test_skills_bindings.py,test_skill_listing_cost.py,test_frontmatter.pyandtest_flake_pattern_ratchet.pypass.Manual verification
Isolated gateway from this branch (loopback, stub ACP backend, throwaway
KIROCREW_HOME/HOME/XDG dirs), papyrus adopted at 6ca7bc69:GET /api/skillsin the same second: 5 papyrus skills (main: 0 for 66 s);GET /api/skillsin the same second: 0 (main: still 5);GET /api/skillsright after boot: 5.Related Issues
Part of #26967
Sibling sweep
Swept: git grep -nE "_skills_dir()|skills_dir()" -- src/kiro_crew (writers of the skills root that do not go through a loader)
Sibling: src/kiro_crew/apps/bridges_skills.py -- changed here
Sibling: src/kiro_crew/dashboard/handlers/discover.py:729 -- not affected -- the provider bundle install already calls
_invalidate_iter_cacheon the dashboard loaderSibling: src/kiro_crew/dashboard_upkeep.py -- not affected -- writes scripts under an existing skill, never adds or removes a
SKILL.mdSwept: git grep -nE "read_text|read_bytes|open(" -- src/kiro_crew/apps/bridges_skills.py src/kiro_crew/skill_live_loaders.py (reads of a sandbox-writable name in this diff)
Sibling: src/kiro_crew/skill_live_loaders.py -- not affected -- opens no file; the bridge's other probes are
lstat/stat/realpath, which never open the namePattern harvest
Rule candidate: review-prompt
Pattern: a writer that changes a cached tree without going through the cache's owner must invalidate the owner's cache
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)