Add optional client-side caching that honors SEP-2549 ttlMs/cacheScope

[tarekgh]

Following up on PR #1623 (SEP-2549 caching hints).

SEP-2549 lets servers advertise a non-zero ttlMs (and a cacheScope of public/private) on list/read results. The client currently surfaces these values (via the raw overloads) but does not act on them.

We could add optional client-side caching that:

• Caches list/read results keyed by request and serves them until the advertised TTL expires.
• Honors cacheScope semantics (private results not shared beyond the current session/consumer; public potentially shareable).
• Handles invalidation, concurrency/thread-safety, and interaction with the existing tool cache.

This is effectively a new opt-in subsystem and should be designed/reviewed separately from the wire-format conformance work in PR #1623.

[tarekgh]

Decision: defer until there is real user demand

This is the separate, opt-in caching subsystem referenced in the #1645 discussion. After reviewing it together with #1645, the decision is to not implement client-side caching now and to wait until we see whether and how users actually need it. Closing as deferred; we can reopen or open a fresh issue when demand justifies the work.

Rationale

• SEP-2549 deliberately leaves caching as client policy. Decisions like "serve stale on refetch error?", "cheap reuse vs consistent full snapshot?", and "poll or not?" are the client's to make, so a built-in cache would have to hard-code answers that are wrong for some clients.
• It is an opt-in subsystem with non-trivial surface (keying, expiry, invalidation, concurrency, scope enforcement). Designing it speculatively, before stateless adoption and the list_changed story settle, risks locking in the wrong abstraction.
• The audience is narrow today: it mainly benefits clients that both paginate and want to cache. Most clients either have small or unpaginated lists, or simply refetch on demand.

The counter-argument is also recorded: if callers implement per-page caching themselves, many will get it wrong or make it inefficient. That is the strongest reason to eventually centralize it in the SDK, and it is why this is deferred rather than rejected.

What #1645 already covered

• No aggregated ttlMs is exposed on the auto-paginating overloads; a single reduced value cannot represent the per-page freshness model.
• The raw, non-auto-paginating overloads already expose everything a caller needs to cache correctly: items, the cursor in, the next cursor out, TimeToLive (ttlMs), and CacheScope.
• The auto-paginating overloads now document that the SDK does no internal caching of listing results and that any caching should be done by the caller via the lower-level overloads.

Design constraints to honor if this is revisited

These are recorded so a future implementer starts from the correct model:

• Per-page, not per-request: a paginated list is not a single cacheable unit. Each page is keyed by (method, cursor) and has its own ttlMs and its own receive time, so the freshness clock is per page. The issue body's "keyed by request ... until the advertised TTL expires" should be read in that per-page sense.
• cacheScope enforcement is security-sensitive: a private result must never be served beyond the requesting user. Shared or multi-tenant caches must not return a private page to a different user. Per SEP-2549, cacheScope is uniform across all pages of a request.
• Invalidation: support cursor-invalidation cascade (a now-invalid cursor discards cached pages and re-fetches from the beginning), interaction with list_changed notifications where available, and a consistent-snapshot mode that re-fetches from the start without a cursor.
• Concurrency and thread-safety, and clear interaction with the existing tool cache.
• Opt-in only, with caching policy left configurable by the caller.

Outcome

Closing as deferred. The raw overloads remain the supported path for cache-aware clients in the meantime.