feat(federation): auto-refresh example descriptions from upstream#37
Merged
Merged
Conversation
Example entries (status='example') that track a real external manifest were preserved verbatim across syncs, so when upstream bumped tool.version + description, the registry drifted. Surfaced 2026-06-02 after drknowhow/deep-research v0.2.0 ship — registry still framed the Python reference impl as "lands in v0.2.0" (future tense) for ~hour after upstream had it. Per-entry opt-in: an example carries `auto_refresh_from_upstream: true` to have its `description` (and `capabilities`) refreshed from `tool.description` / `tool.tags` at `manifest_url` on every sync. The refresh fails soft — flaky upstream surfaces as a warning, entry preserved unchanged. Self-hosted spec-mirrored examples (gmail-*, muninn-flowing, vi-federation) leave the flag off and stay verbatim; hand-curated wording survives. Flagged: deep-research + yep-memory. Both descriptions in manifests.json re-synced to current upstream wording so the next nightly run is a no-op diff. Tests: 3 new — refresh replaces, no-flag preserves, fetch-failure fails soft with warning. All 31 federation pipeline tests pass. Follow-on to #36 (manual touch-up). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR adds an opt-in mechanism to keep certain registry “example” entries from drifting by re-pulling their human-facing description (and capability tags) from the upstream install-manifest during federation sync runs.
Changes:
- Add
auto_refresh_from_upstreamhandling inscripts/sync_from_publishers.pyto refreshdescription/capabilitiesfor preserved example entries from upstreamtool.description/tool.tags, with soft-failure warnings. - Add pytest coverage + a new upstream manifest fixture to validate refresh, non-refresh, and soft-failure behavior.
- Update
manifests.jsonto opt-indeep-research(andyep-memory) and to re-sync their descriptions to current upstream wording.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
scripts/sync_from_publishers.py |
Implements the opt-in refresh logic and warning behavior during sync. |
tests/test_federation_pipeline.py |
Adds end-to-end tests for the new opt-in refresh semantics. |
tests/fixtures/https_example.com__refreshable.v0.4.json |
Provides an upstream manifest fixture used by the new tests. |
manifests.json |
Updates descriptions and adds auto_refresh_from_upstream flags to selected entries. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+121
to
+123
| upstream_tags = tool.get("tags") | ||
| if isinstance(upstream_tags, list) and upstream_tags: | ||
| refreshed["capabilities"] = list(upstream_tags) |
Comment on lines
135
to
+139
| "publisher_kind": "https", | ||
| "publisher_id": "yepgent.com", | ||
| "trust_tier": "verified" | ||
| } | ||
| }, | ||
| "auto_refresh_from_upstream": true |
Comment on lines
+109
to
+112
| try: | ||
| doc = json.loads(raw) | ||
| except (ValueError, TypeError) as e: | ||
| return entry, f"{entry.get('id')}: invalid JSON at {url}: {e}; description unchanged" |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
status='example') with a real upstreammanifest_urlused to drift when upstream bumpedtool.description— they were preserved verbatim across syncs. Surfaced after drknowhow/deep-research v0.2.0 ship: registry kept framing the Python reference impl as "lands in v0.2.0" (future tense).auto_refresh_from_upstream: trueflag. When set,sync_from_publishersfetches the manifest and overwritesdescription(andcapabilities) fromtool.description/tool.tags. Spec-mirrored examples (gmail-*, muninn-flowing, vi-federation) leave the flag off and stay verbatim.deep-research+yep-memory. Both descriptions inmanifests.jsonre-synced to current upstream wording so the next nightly run is a no-op.Provenance
drknowhow/deep-researchtool.version: 0.2.0(PR #2) merged 2026-06-02T10:37:59Z.Test plan
tests/test_federation_pipeline.py:test_auto_refresh_replaces_description_and_tags— refresh path overwrites description + capabilities from upstream.test_auto_refresh_absent_flag_preserves_verbatim— without flag, hand-curated description survives.test_auto_refresh_fails_soft_on_missing_upstream— fetch failure → entry preserved + warning surfaced.python scripts/validate_manifests_index.py— ok.python scripts/build_registry_pages.py --check— no drift.🤖 Generated with Claude Code