-
Notifications
You must be signed in to change notification settings - Fork 0
feat(cli): persistent skill cache to skip prpm install on repeat launches #124
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
khaliqgant
wants to merge
4
commits into
main
Choose a base branch
from
feat/persistent-skill-cache
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
5232fbd
feat(cli): persistent skill cache to skip prpm install on repeat laun…
09caf5b
fix(cli): avoid duplicate 'Setting up sandbox mount' line on mount ca…
2afd176
feat(cli): opt-in upstream drift detection for the skill cache
9ab2ba7
fix(cli): address PR #124 review — refresh-clean, install lock, never…
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| { | ||
| "id": "traj_47ulsb0rwbid", | ||
| "version": 1, | ||
| "task": { | ||
| "title": "Persistent skill cache + upstream drift detection" | ||
| }, | ||
| "status": "completed", | ||
| "startedAt": "2026-05-15T20:47:56.786Z", | ||
| "agents": [ | ||
| { | ||
| "name": "claude-skill-cache", | ||
| "role": "lead", | ||
| "joinedAt": "2026-05-15T20:47:56.808Z" | ||
| } | ||
| ], | ||
| "chapters": [ | ||
| { | ||
| "id": "chap_p2cn73gpqanw", | ||
| "title": "Initial work", | ||
| "agentName": "claude-skill-cache", | ||
| "startedAt": "2026-05-15T20:47:56.808Z", | ||
| "events": [ | ||
| { | ||
| "ts": 1778878092151, | ||
| "type": "decision", | ||
| "content": "Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/: Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/", | ||
| "raw": { | ||
| "question": "Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/", | ||
| "chosen": "Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/", | ||
| "alternatives": [ | ||
| { | ||
| "option": "Per-session install (status quo", | ||
| "reason": "" | ||
| }, | ||
| { | ||
| "option": "slow); global shared plugin dir (skill collisions across personas); TTL-only cache (still pays install on expiry)", | ||
| "reason": "" | ||
| } | ||
| ], | ||
| "reasoning": "The reported slowness was npx prpm install / npx skills add re-running every launch. A persistent dir keyed by a stable fingerprint lets repeat launches skip the install entirely. Local .md sources fold their content hash in so edits auto-invalidate without a version bump." | ||
| }, | ||
| "significance": "high" | ||
| }, | ||
| { | ||
| "ts": 1778878092386, | ||
| "type": "decision", | ||
| "content": "Never auto-invalidate on the source-key fingerprint; cover all three harnesses: Never auto-invalidate on the source-key fingerprint; cover all three harnesses", | ||
| "raw": { | ||
| "question": "Never auto-invalidate on the source-key fingerprint; cover all three harnesses", | ||
| "chosen": "Never auto-invalidate on the source-key fingerprint; cover all three harnesses", | ||
| "alternatives": [ | ||
| { | ||
| "option": "Daily TTL on the fingerprint; claude-only scope with mount harnesses as follow-up", | ||
| "reason": "" | ||
| } | ||
| ], | ||
| "reasoning": "User explicitly chose 'never auto-invalidate' for the fingerprint layer and 'all harnesses now' when asked. Claude reuses the cache dir as --plugin-dir; opencode/codex mirror it into the relayfile mount before launch (mount-ignored patterns stop syncback)." | ||
| }, | ||
| "significance": "high" | ||
| }, | ||
| { | ||
| "ts": 1778878111454, | ||
| "type": "decision", | ||
| "content": "Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open: Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open", | ||
| "raw": { | ||
| "question": "Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open", | ||
| "chosen": "Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open", | ||
| "alternatives": [ | ||
| { | ||
| "option": "Manual --refresh-skills only (user must remember); always-check (slows every launch); coarse repo-HEAD commit SHA for github (over-invalidates monorepos)", | ||
| "reason": "" | ||
| } | ||
| ], | ||
| "reasoning": "User asked how a new upstream skill version is consumed when the source string is unchanged. Explored prpm info / registry HTTP API (latest_version.version) and skill.sh — both expose cheap version probes. A 24h TTL keeps most launches network-free; only the daily check launch pays ~150-500ms parallel probes. Fail-open so a flaky registry never blocks a launch." | ||
| }, | ||
| "significance": "high" | ||
| }, | ||
| { | ||
| "ts": 1778878111681, | ||
| "type": "decision", | ||
| "content": "Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match: Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match", | ||
| "raw": { | ||
| "question": "Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match", | ||
| "chosen": "Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match", | ||
| "alternatives": [ | ||
| { | ||
| "option": "repos/<o>/<r>/commits?per_page=1 repo-HEAD (1 call", | ||
| "reason": "" | ||
| }, | ||
| { | ||
| "option": "but any push invalidates); re-download SKILL.md and hash (heavier", | ||
| "reason": "" | ||
| }, | ||
| { | ||
| "option": "needs path anyway)", | ||
| "reason": "" | ||
| } | ||
| ], | ||
| "reasoning": "skill.sh writes skills-lock.json with skillPath + computedHash per skill. Building the Contents API URL from skillPath gives per-file drift (a monorepo of 50 skills doesn't invalidate on an unrelated commit). The blob SHA is also the ETag, so If-None-Match returns 304 with no body — cheapest possible check." | ||
| }, | ||
| "significance": "high" | ||
| }, | ||
| { | ||
| "ts": 1778878111884, | ||
| "type": "decision", | ||
| "content": "Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version: Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version", | ||
| "raw": { | ||
| "question": "Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version", | ||
| "chosen": "Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version", | ||
| "alternatives": [ | ||
| { | ||
| "option": "Hard v2 cutover (invalidates all caches); separate sidecar file for upstream metadata (more files to keep consistent)", | ||
| "reason": "" | ||
| } | ||
| ], | ||
| "reasoning": "Bumping the marker schema must not invalidate every cache entry in the wild. readSkillCacheMarker accepts v1+v2 and upgrades v1 in place with no upstream records (next drift pass captures identity). The fingerprint's internal 'v' stays 1 so existing dirs keep resolving." | ||
| }, | ||
| "significance": "high" | ||
| }, | ||
| { | ||
| "ts": 1778878613570, | ||
| "type": "reflection", | ||
| "content": "Verified end-to-end against live prpm.dev + api.github.com: cache miss records resolved version; in-TTL launches skip probing; --check-upstream detects a tampered stale version (1.0.0→1.1.3) and reinstalls; marker self-heals; --no-check-upstream bypasses. GitHub 304 If-None-Match path confirmed.", | ||
| "significance": "high" | ||
| } | ||
| ], | ||
| "endedAt": "2026-05-15T20:58:19.304Z" | ||
| } | ||
| ], | ||
| "commits": [], | ||
| "filesChanged": [], | ||
| "projectId": "/Users/khaliqgant/Projects/AgentWorkforce/workforce", | ||
| "tags": [], | ||
| "_trace": { | ||
| "startRef": "09caf5b8db32f9d1c2c71735b7e231a7efc7ff8e", | ||
| "endRef": "09caf5b8db32f9d1c2c71735b7e231a7efc7ff8e" | ||
| }, | ||
| "completedAt": "2026-05-15T20:58:19.304Z", | ||
| "retrospective": { | ||
| "summary": "Extended the persistent skill-cache PR with opt-in upstream drift detection. Marker bumped to schema v2 (v1 read-compatible) recording per-skill upstream identity (prpm resolved version / GitHub blob SHA). TTL-gated (24h default) parallel probes on launch flip a cache hit to a reinstall when upstream moved; fail-open on any probe error. Added --check-upstream/--no-check-upstream + AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL. 22 new unit tests (mocked HTTP) + verified end-to-end against live prpm.dev and api.github.com.", | ||
| "approach": "Reused installer lockfiles (prpm.lock version, skills-lock.json skillPath) for precise per-file identity; conditional GET (If-None-Match) for the cheapest GitHub check; mutable cache-hit flag downgraded by an awaited drift probe before the install decision.", | ||
| "confidence": 0.86 | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| # Trajectory: Persistent skill cache + upstream drift detection | ||
|
|
||
| > **Status:** ✅ Completed | ||
| > **Confidence:** 86% | ||
| > **Started:** May 15, 2026 at 10:47 PM | ||
| > **Completed:** May 15, 2026 at 10:58 PM | ||
|
|
||
| --- | ||
|
|
||
| ## Summary | ||
|
|
||
| Extended the persistent skill-cache PR with opt-in upstream drift detection. Marker bumped to schema v2 (v1 read-compatible) recording per-skill upstream identity (prpm resolved version / GitHub blob SHA). TTL-gated (24h default) parallel probes on launch flip a cache hit to a reinstall when upstream moved; fail-open on any probe error. Added --check-upstream/--no-check-upstream + AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL. 22 new unit tests (mocked HTTP) + verified end-to-end against live prpm.dev and api.github.com. | ||
|
|
||
| **Approach:** Reused installer lockfiles (prpm.lock version, skills-lock.json skillPath) for precise per-file identity; conditional GET (If-None-Match) for the cheapest GitHub check; mutable cache-hit flag downgraded by an awaited drift probe before the install decision. | ||
|
|
||
| --- | ||
|
|
||
| ## Key Decisions | ||
|
|
||
| ### Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/ | ||
| - **Chose:** Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/ | ||
| - **Rejected:** Per-session install (status quo, slow); global shared plugin dir (skill collisions across personas); TTL-only cache (still pays install on expiry) | ||
| - **Reasoning:** The reported slowness was npx prpm install / npx skills add re-running every launch. A persistent dir keyed by a stable fingerprint lets repeat launches skip the install entirely. Local .md sources fold their content hash in so edits auto-invalidate without a version bump. | ||
|
|
||
| ### Never auto-invalidate on the source-key fingerprint; cover all three harnesses | ||
| - **Chose:** Never auto-invalidate on the source-key fingerprint; cover all three harnesses | ||
| - **Rejected:** Daily TTL on the fingerprint; claude-only scope with mount harnesses as follow-up | ||
| - **Reasoning:** User explicitly chose 'never auto-invalidate' for the fingerprint layer and 'all harnesses now' when asked. Claude reuses the cache dir as --plugin-dir; opencode/codex mirror it into the relayfile mount before launch (mount-ignored patterns stop syncback). | ||
|
|
||
| ### Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open | ||
| - **Chose:** Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open | ||
| - **Rejected:** Manual --refresh-skills only (user must remember); always-check (slows every launch); coarse repo-HEAD commit SHA for github (over-invalidates monorepos) | ||
| - **Reasoning:** User asked how a new upstream skill version is consumed when the source string is unchanged. Explored prpm info / registry HTTP API (latest_version.version) and skill.sh — both expose cheap version probes. A 24h TTL keeps most launches network-free; only the daily check launch pays ~150-500ms parallel probes. Fail-open so a flaky registry never blocks a launch. | ||
|
|
||
| ### Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match | ||
| - **Chose:** Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match | ||
| - **Rejected:** repos/<o>/<r>/commits?per_page=1 repo-HEAD (1 call, but any push invalidates); re-download SKILL.md and hash (heavier, needs path anyway) | ||
| - **Reasoning:** skill.sh writes skills-lock.json with skillPath + computedHash per skill. Building the Contents API URL from skillPath gives per-file drift (a monorepo of 50 skills doesn't invalidate on an unrelated commit). The blob SHA is also the ETag, so If-None-Match returns 304 with no body — cheapest possible check. | ||
|
|
||
| ### Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version | ||
| - **Chose:** Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version | ||
| - **Rejected:** Hard v2 cutover (invalidates all caches); separate sidecar file for upstream metadata (more files to keep consistent) | ||
| - **Reasoning:** Bumping the marker schema must not invalidate every cache entry in the wild. readSkillCacheMarker accepts v1+v2 and upgrades v1 in place with no upstream records (next drift pass captures identity). The fingerprint's internal 'v' stays 1 so existing dirs keep resolving. | ||
|
|
||
| --- | ||
|
|
||
| ## Chapters | ||
|
|
||
| ### 1. Initial work | ||
| *Agent: claude-skill-cache* | ||
|
|
||
| - Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/: Content-addressed cache keyed by (harness, sorted skill sources, local-file SHA) under ~/.agentworkforce/workforce/cache/plugins/<fp>/ | ||
| - Never auto-invalidate on the source-key fingerprint; cover all three harnesses: Never auto-invalidate on the source-key fingerprint; cover all three harnesses | ||
| - Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open: Add opt-in upstream drift detection: prpm registry GET + GitHub Contents API blob SHA, TTL-gated (24h default), fail-open | ||
| - Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match: Precise per-file GitHub blob SHA via skills-lock.json skillPath, not coarse repo-HEAD; conditional GET with If-None-Match | ||
| - Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version: Marker schema v2, v1 read-compatible; fingerprint content-version pinned to 1 independent of marker version | ||
| - Verified end-to-end against live prpm.dev + api.github.com: cache miss records resolved version; in-TTL launches skip probing; --check-upstream detects a tampered stale version (1.0.0→1.1.3) and reinstalls; marker self-heals; --no-check-upstream bypasses. GitHub 304 If-None-Match path confirmed. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2: Avoid committing a user-specific absolute filesystem path in
projectId; use a stable, repo-agnostic identifier instead.Prompt for AI agents
Tip: Review your code locally with the cubic CLI to iterate faster.