Detect UCP version drift and explain stale-CLI failures - #45
Draft
gil-- wants to merge 2 commits into
Draft
Conversation
Both profiles the CLI sends in meta["ucp-agent"].profile (valid-with-capabilities for the global catalog, personal_agent for merchant checkout) move from 2026-04-08 to 2026-08-25, pinned via a single UCP_VERSION constant in src/constants.ts. The skill reference docs use the new profile URLs, and the shipping destination example carries the explicit "type": "shipping_address" discriminator that 2026-08-25 introduced. Request shapes are unchanged between the two releases: MCP method names, the meta.ucp-agent / idempotency-key definitions, the message and payment schemas, and the checkout status enum all diff clean. Catalog responses gain optional actions[] and policies[] fields. Shopify's global catalog extension now requires protocol >= 2026-08-25. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
UCP servers negotiate down to the release named in the agent profile, so a stale shop-cli never learns it is behind until the server drops that release and every call fails with "Tool not found". Surface drift using the data the servers already publish, without adding network calls to ordinary commands: - `shop --version` prints the UCP release alongside the package version. - New `shop version [--check] [--shop-domain]` compares the pinned release against a host's /.well-known/ucp manifest (current / outdated / unsupported / ahead / unknown) and prints the upgrade command. - MCP JSON-RPC errors include the server's message/data; a "Tool not found" is checked against the manifest and explained as a dropped release (or attributed to a custom --profile-url). - A one-time stderr `# Notice` when a server negotiates a different release. - SKILL.md guidance to run `shop version --check` at session start. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
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
1 participant
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
Follow-up to #44. Many agents install
shop-clionce and never update, and UCP servers drop old releases after a few months. Today a stale CLI fails with an opaqueMCP search_catalog returned an error, and nothing in the CLI tells the agent (or user) that the fix is to upgrade. This PR surfaces UCP version drift using only data the servers already publish, with no new network calls on the hot path and no npm registry lookups.shop --versionnow prints the UCP release too:0.1.2 (UCP 2026-08-25).shop version [--check] [--shop-domain <domain>]prints{ cli, ucp }. With--checkit fetches/.well-known/ucpfrom the global catalog (or a merchant) and classifies the pinned release against the server'sversion/supported_versionsascurrent,outdated,unsupported,ahead, orunknown, with a message and the upgrade command. A failed manifest fetch degrades tounknownrather than erroring.message/data(e.g.Invalid params: Tool not found: search_catalog). A "Tool not found" for a tool this CLI is built against is checked against the host's manifest (non-fatal) and explained as a dropped release with the upgrade command, or, when a custom--profile-urlis in use, attributed to that profile.ucp.versionthan the CLI requested, a one-time# Noticegoes to stderr. stdout stays clean JSON/markdown.shop version --checkat session start and on "Tool not found", and what each status means. README lists the new command. Minor changeset.Why this design
UCP negotiation always goes down to the release named in the agent profile, so a successful response can never reveal that the CLI is behind; only the server's discovery manifest can (
ucp.version+ucp.supported_versions). Fetching that manifest on every call would add latency to every command, so the check is explicit (shop version --check) or triggered only on the failure it explains ("Tool not found"). Checking npm for a newer package was considered and rejected: it is an extra third-party call on every run and it cannot say whether the installed release still works.Verification
Live against production:
pnpm typecheck,pnpm test(128 tests, 20 new intests/ucp-version-check.test.ts),pnpm buildall pass.ucpblock, so no notices fire, and only "Tool not found" errors trigger a manifest fetch.Notes
update-ucp-2026-08-25); the diff shows both until Update UCP agent profiles to the 2026-08-25 release #44 merges. Only the top commit belongs to this PR.--checkand the "Tool not found" path are the only places that make a manifest request; ordinary search/checkout calls are unchanged.🤖 Generated with Claude Code