feature(agent-cache): add discovery marker protocol (0.5.0)

[jamby77]

Summary

Companion to #127 (@betterdb/semantic-cache 0.2.0). Implements the agent-cache side of the shared __betterdb:* discovery marker protocol so BetterDB Monitor (and the upcoming Cache Intelligence MCP tools) can enumerate agent-cache instances on any Valkey they already monitor — no customer configuration beyond constructing the library as before.

Protocol (shared with semantic-cache)

• __betterdb:caches — hash. Field = options.name, value = JSON metadata (type, prefix, version, protocol_version, capabilities, tier TTL defaults, tool policy names, cost-table presence, etc).
• __betterdb:heartbeat:<name> — string, TTL 60s, refreshed every 30s.
• __betterdb:protocol — SET NX 1. Version marker.

No sensitive data is written — only cache metadata.

What lands

• Constructor kicks off a fire-and-forget registerDiscovery() alongside the existing tool.loadPolicies() and createAnalytics() patterns — the cache is usable immediately
• Heartbeat ticks refresh the registry metadata so tool_policies added via cache.tool.setPolicy(...) become visible within 30s, and re-assert the protocol NX key as belt-and-braces against LRU eviction
• tool_policies is capped at 500 names with a tool_policies_truncated flag
• shutdown() now stops the heartbeat and deletes the heartbeat key; the registry entry is preserved so Monitor retains history
• New cache.ensureDiscoveryReady() lets callers opt into strict collision enforcement — rejects with AgentCacheUsageError when another cache type is registered under the same name on this Valkey
• New ToolCache.listPolicyNames() exposes registered tool names for the marker
• Opt out via AgentCacheOptions.discovery = { enabled: false }. heartbeatIntervalMs and includeToolPolicies are also exposed
• agent_cache_discovery_write_failed_total counter so ACL-denied writes are alertable

Bumps @betterdb/agent-cache 0.4.0 → 0.5.0.

Test plan

• pnpm --filter @betterdb/agent-cache test — 221 tests pass (12 new unit tests + 1 new integration test for marker registration, heartbeat TTL, metadata refresh after setPolicy, cross-type collision, version mismatch warn+overwrite, ACL-denied resilience)
• pnpm --filter @betterdb/agent-cache typecheck clean
• pnpm --filter @betterdb/agent-cache build clean
• Integration tests run in CI against valkey:8.1: verify HGETALL __betterdb:caches populated, heartbeat TTL in range, shutdown() clears heartbeat key, registry preserved

Notes for review

• Fire-and-forget registration is intentional and matches the existing pattern for analytics.createAnalytics() / tool.loadPolicies() in the same constructor. Consumers who want strict collision enforcement can await cache.ensureDiscoveryReady() right after construction.
• The collision-enforcement trade-off is documented in the README and in the PR of the spec. If the team decides we need every tier operation to gate on discovery readiness, that's a follow-up — v1 covers the common case (construct → first op is async anyway → race is vanishingly rare on a healthy Valkey).

---

Note

Medium Risk
Adds new background Valkey writes and timers during AgentCache lifecycle (constructor/heartbeat/shutdown), which could surface ACL/permission issues or unexpected load in some deployments. Core caching behavior is intended to be unchanged, but lifecycle and monitoring side effects are new.

Overview
Introduces a BetterDB discovery-marker protocol for @betterdb/agent-cache (bumping to 0.5.0): each AgentCache now best-effort registers JSON metadata in __betterdb:caches, maintains a periodic __betterdb:heartbeat:<name> key (and sets __betterdb:protocol), and refreshes metadata on each heartbeat.

Adds AgentCacheOptions.discovery controls (enable/disable, heartbeat interval, include tool policies), a new cache.ensureDiscoveryReady() for callers that want cross-cache-type collision enforcement, and updates shutdown() to stop the heartbeat and delete the heartbeat key while leaving the registry entry intact. Observability is extended with a new Prometheus counter *_discovery_write_failed_total, and tests/docs are updated to cover registration, TTL behavior, collision handling, and ACL-denied write resilience.

^{Reviewed by Cursor Bugbot for commit 3b504ca. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0de940d. Configure here.}

[KIvanow]

In which cases will we enter this if, when line 325 does the same check first already?

[jamby77]

Await on line 329 can result on setting this.discoveryError

[jamby77]

When ensureDiscoveryReady() is called while registration is still in flight, line 325 sees discoveryError === null so it doesn't throw, then line 329 awaits the in-flight promise. The promise itself never rejects — line 379 ends the chain with a .catch() that swallows the rejection and stores it in this.discoveryError instead. So if registration fails during that await, the only way to surface it is to re-check discoveryError after the await resolves — that's what 330–332 do.

The .catch() is there because discoveryReady has multiple potential awaiters (also shutdown() at line 315) and is started from the constructor — without it, an unawaited rejection would log UnhandledPromiseRejection. The trade-off is we have to read the error back through the field rather than the promise.

A simpler form would be to drop the .catch() and let the promise reject; then line 329 would throw and lines 330–332 become unreachable. Happy to refactor it that way if you prefer.

[KIvanow]

@jamby77 looks great overall! Had only 1 comment