Repository navigation
Bound the catalog refresh, keep unavailable connections in the file, scope listings before a refresh (0.3.14) - #26
Merged
Conversation
…scope listings before a refresh (0.3.14)
Two defects found while accepting the 0.7.9 Codex release:
- A forced catalog refresh took 773 s and wrote the scope empty without naming the
connection unavailable. readProjectToolCatalog now runs within one budget
(budgetMs, default DEFAULT_PROJECT_REFRESH_BUDGET_MS = 300 s): a connection whose
read fails, or is not read before the budget runs out, stays in the catalog
marked `unavailable: { at, code, message }` with its earlier tools, so a scope
whose connections exist is never written empty and healthy. The mark lives in the
file, so state() and the mcp-catalog action report it from any process, not only
the one that ran the refresh; a successful read or update() clears it. A refresh
aborts its dispatcher's signal when it returns, so a read the budget left behind
cannot keep a socket.
- A fresh Codex server's first tools/list listed every cached scope because the
backend was learned only from a refresh. createProjectToolCatalog takes `backend`
and offers ready(), which resolves it without a network request the way
auth-status does (environment, shared preferences, default); until the backend is
known a listing is empty, never another backend's tools.
Tests cover the written mark and its clearing, the budget (hung reads, retained
tools, released signal), the empty-until-known listing and ready(); the mcp-catalog
test checks that the next process sees the mark. ADR 0004 and the README record the
behaviour.
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
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
Fixes the two registry defects found while accepting the Codex 0.7.9 release (recorded in that release's acceptance notes), as devtools 0.3.14. Design record updated in
docs/adr/0004-shared-project-tool-registry.md.readProjectToolCatalogruns within one budget (budgetMs, defaultDEFAULT_PROJECT_REFRESH_BUDGET_MS= 300 s). A connection whose read fails, or is not read before the budget runs out, stays in the catalog markedunavailable: { at, code, message }with its earlier tools. The mark is persisted inproject-tool-catalog.json, sostate()/view()and themcp-catalogaction report it from any process (the Claude Desktop hook runs one worker per action and previously could never see a refresh'sunavailable). A successful read orupdate()clears it. A refresh aborts its dispatcher's signal when it returns, so a read left behind by the budget cannot hold a socket. Observed before the fix: a 773 s forced refresh that wrote the scope empty and reported nothing.createProjectToolCatalogacceptsbackendand offersready(), which resolves the host's backend without a network request the wayauth-statusdoes (process environment, shared preferences, default). Until the backend is known a listing is empty, never another backend's tools. Observed before the fix: a fresh Codex server's firsttools/listcarried 144 tools from two backends.Additive API only: new
budgetMs/backendoptions,ready(),ProjectToolUnavailable,DEFAULT_PROJECT_REFRESH_BUDGET_MS;unavailableon connection records andstate().connections[].unavailable. Tool names, the file format (new optional field) andmcp-callare unchanged.Testing
npm test: 184 pass (3 new registry tests; one existing test rewritten for the empty-until-known listing; themcp-catalogtest now checks that the next process sees the mark).node scripts/check-release.cjs,node scripts/check-docs.cjspass.codex/registry-defects): the shared catalog on the workstation holds three connections across two backends; a fresh server's firsttools/listreturned 103 tools = 16 + the 87 of its own backend only.Release
Tag
v0.3.14on the merge commit runs the release workflow, which publishes to npm. The Codex consumer (mainsequence-codex-pluginbranchcodex/registry-defects, 0.7.12) pins 0.3.14 by a local pack integrity for its test run and must be re-pinned from the registry after publishing (npm packis not byte-reproducible across machines). Claude Desktop needs only a pin bump; its hook already passes an explicit backend tomcp-catalog.🤖 Generated with Claude Code