mcpx: Phase 1 of #1601 — surface ttlMs/cacheScope in mcpclient and expire the pool catalogue cache (modern era)

Phase 1 of design #1601 (mcpx client cache hints). Design doc: files/designs/code-mcpx-client-cache-hints.md in the keep-the-four-repos-healthy goal workspace.

Scope

Surface upstream ttlMs/cacheScope in the client and make the pool's catalogue cache expire for modern upstreams.

internal/mcpclient: add ttlMs/cacheScope to toolsListResult, resourcesListResult, resourceTemplatesListResult, promptsListResult. Fix resourceTemplatesListResult.NextCursor to *string and page resources/templates/list in ListResources (PG-02/PG-07). Add hint-returning list variants used by the pool; keep ListTools/ListResources/ListPrompts signatures as wrappers over them.
Hint aggregation per list: TTL = minimum ttlMs across pages; scope = private if any page says private. ListResources aggregates across both its calls (resources/list + templates/list).
internal/pool: store a deadline + scope beside schemaAt (earliest deadline among tools/resources/prompts). Schemas() serves the cache only while fresh for a modern-era pool and otherwise falls through to RefreshSchemas. Legacy-era pools keep a zero deadline — behaviour byte-for-byte today's (cache until list_changed / refresh / restart).
Retire conformance gaps caching-ttl-zero-stale, caching-ttl-positive-fresh, caching-ttl-absent-zero, caching-ttl-negative-zero, caching-stale-refetch (internal/conformance/coverage_stateful.go).

Evidence (main `33a4e67`, 2026-10-28)

List result types carry no hint fields (internal/mcpclient/client.go ~L183, ~L204, ~L209, ~L1117); list methods return bare slices.
Pool.Schemas (internal/pool/pool.go ~L815) returns the cache forever once schemaAt is set.
Conformance gaps at internal/conformance/coverage_stateful.go:113-121 (origin mcpx client: cannot reach a conformant 2026-07-28 server dezren39/darwin-nix#200).
Server side already emits the hints (internal/mcpserver/server.go ~L690-740) — this phase is client-only.

Acceptance

Fake modern upstream tests: ttl 0 / absent / negative → next Schemas() re-lists; positive ttl → served from cache until deadline, re-listed after; per-page min-TTL wins; any-page-private marks the catalogue private.
Concurrent reads of an expired cache collapse into one refresh.
Legacy upstream catalogue behaves exactly as before (no expiry).
Templates beyond page 1 now appear in ListResources, with a test naming the change.
The five named conformance gaps are retired; go test ./... for pkgs/mcpx passes in CI.

Out of scope

Disk persistence / scope enforcement (Phase 2), register truth-up (Phase 3), resources/read caching and discover TTL (open questions on #1601).

CODE-628

🤖 Agent note · filed

Agent: design-architect (dedicated code job, repo-design-architect-code)
Session / ID: repo-design-architect-code run 2026-10-28 00:25 CDT (2026-10-28T05:34:00Z)
Found via: filed this run (design pass 6)
Task: Phase 1 of design(mcpx): honour upstream ttlMs and cacheScope — the pool catalogue cache gets a freshness deadline and a scope #1601 (triage): surface ttlMs/cacheScope in mcpclient list results, aggregate min-TTL/private-if-any, add hint-returning list variants, and expire the pool catalogue cache for modern-era pools only.
Expectation: effort/l triage — done looks like: scope confirmed against current main, the hint-variant shape settled, and the implementation follow-up packet enqueued (or split) with mcpx: Phase 1 of #1601 — surface ttlMs/cacheScope in mcpclient and expire the pool catalogue cache (modern era) #1602's acceptance intact. Do not implement in the triage task.
Links: design design(mcpx): honour upstream ttlMs and cacheScope — the pool catalogue cache gets a freshness deadline and a scope #1601; design doc files/designs/code-mcpx-client-cache-hints.md; packet hidden_files/queue-packets/packet-1602.json

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane C shift
Session / ID: queue task 1689 (triage)
Found via: queue claim
Task: Triage mcpx: Phase 1 of #1601 — surface ttlMs/cacheScope in mcpclient and expire the pool catalogue cache (modern era) #1602 (mcpx Phase 1 of design(mcpx): honour upstream ttlMs and cacheScope — the pool catalogue cache gets a freshness deadline and a scope #1601): confirm scope against current main, settle the hint-variant shape, enqueue the implementation follow-up. No implementation in this task.
Expectation: effort l (issue label) / triage timebox 20m; done = verdict posted + follow-up packet enqueued
Links: design design(mcpx): honour upstream ttlMs and cacheScope — the pool catalogue cache gets a freshness deadline and a scope #1601 · doc files/designs/code-mcpx-client-cache-hints.md (keep-the-four-repos-healthy goal workspace)

🤖 Agent note · parked

Agent: queue worker (repo-worker-code), lane D
Session / ID: queue task 1704
Found via: queue claim (resume of awaiting_ci checkpoint)
Task: Rechecked CI on PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608 @ff81c525 — 14 checks pass (including client-2025-11-25, which failed on the previous head) and only "compare with the records" is still queued; parked for CI
Expectation: on resume, merge PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608 when that last check is green, then complete task 1704 (also unblocks mcpx: Phase 2 of #1601 — cacheScope at the disk boundary: private never persists, expired seeds expired, stale on refetch error #1603 gate tasks)
Links: PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane D shift
Session / ID: queue task 1704
Found via: queue claim (resume from awaiting_ci checkpoint)
Task: Resume PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608 — check CI on head ff81c52; merge when green per standing criteria
Expectation: done = PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608 merged and issue closed, or task parked again with the pending check named
Links: PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608 · branch queue/1704-1602-mcpx-ttl

mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue…

🤖 Agent note · done

Agent: queue worker (repo-worker-code), lane D shift
Session / ID: queue task 1704
Found via: queue claim (resume from awaiting_ci checkpoint)
Task: PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608 CI finished green (compare-with-the-records passed after a long runner queue; all 15 checks pass, 2 skipping) and the PR was squash-merged.
Expectation: done — merge commit ab2ce7a on main; Phase 2 (mcpx: Phase 2 of #1601 — cacheScope at the disk boundary: private never persists, expired seeds expired, stale on refetch error #1603) and Phase 3 (mcpx: Phase 3 of #1601 — register truth-up, list_changed invalidation test, and nix#200 evidence #1604) remain separate.
Links: PR mcpx: surface ttlMs/cacheScope in mcpclient and expire pool catalogue cache (#1602) #1608 (merged)

Navigation Menu

Repository navigation

mcpx: Phase 1 of #1601 — surface ttlMs/cacheScope in mcpclient and expire the pool catalogue cache (modern era) #1602

Scope

Evidence (main `33a4e67`, 2026-10-28)

Acceptance

Out of scope

76 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

mcpx: Phase 1 of #1601 — surface ttlMs/cacheScope in mcpclient and expire the pool catalogue cache (modern era) #1602

Description

Scope

Evidence (main 33a4e67, 2026-10-28)

Acceptance

Out of scope

Activity

developing-today commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

76 remaining items

dezren39 commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Evidence (main `33a4e67`, 2026-10-28)