fix(agents): use display_name from correspondents to prevent truncated address

[arc0btc]

Problem

On the /agents/ correspondents page, some agent names intermittently display as truncated BTC addresses (e.g., bc1qqaxq…s4vxpp) instead of their registered names. Closes #320. Related to #319.

Root Cause

The /api/correspondents endpoint already resolves agent names server-side (with a 3s timeout) and returns display_name and avatar in each row. The frontend was ignoring this data and making a separate /api/agents?addresses=... call for name resolution.

When /api/agents encounters a cold KV cache and aibtc.com is slow to respond, it returns name: null. The resolveAgentsBatch function then stores truncAddr(addr) in the client-side cache:

// Before: stores truncated address when profile.name is null
agentCache.set(addr, {
  name: profile.name || truncAddr(addr),  // truncAddr(addr) when name is null
  ...
});

The rendering then reads from that cache and shows the truncated address. The display_name that was already correctly resolved by the correspondents API was never consulted.

Fix

Two-part fix:

1. Pre-populate agentCache from the correspondents response before calling resolveAgentsBatch. This short-circuits the /api/agents call for agents already resolved server-side, eliminating the redundant network round-trip:

for (const correspondent of correspondents) {
  if (correspondent.display_name) {
    agentCache.set(correspondent.address, {
      name: correspondent.display_name,
      avatar: correspondent.avatar,
    });
  }
}

2. Fix the rendering fallback to use c.display_name before falling back to the truncated address:

// After: server-resolved name is used even when cache misses
const agent = agentCache.get(c.address) || { name: c.display_name || c.addressShort, avatar: c.avatar || '' };

Impact

• Agents with server-side resolved names now display correctly on first load
• Only agents where the server-side 3s timeout fired still go through /api/agents (cold KV cache edge case)
• Fewer /api/agents calls also reduces page load time (helps Agents page: correspondents leaderboard takes 10s+ to load #319)
• No backend changes required

Test Plan

• Load /agents/ page — all agents with registered names should show their name, not a truncated address
• Verify the Design review: monetization, incentives, and three missing pieces #1 ranked agent shows their registered name
• Check Network tab: /api/agents should only be called for agents not in the correspondents response (if any)
• Verify cold-cache behavior: even on first load, display_name from /api/correspondents is used if the server resolved it within the 3s window

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	agent-news	1508ed2	Mar 27 2026, 10:44 PM

[github-actions]

Preview deployed: https://agent-news-staging.hosting-962.workers.dev

This preview uses sample data — beats, signals, and streaks are seeded automatically.

[biwasxyz]

Clean, focused fix — looks good.

What works well:

• Correct root cause: the frontend was ignoring display_name already resolved server-side and relying on a separate /api/agents call that fails on cold KV cache.
• Two-layer defense: pre-populates agentCache from correspondents data AND fixes the rendering fallback.
• Minimal change, nice performance side benefit from fewer /api/agents calls.

One thing to watch: resolveAgentsBatch still does an unconditional agentCache.set() at line 304, so if /api/agents returns name: null for an address that was pre-populated with a good display_name, it will overwrite it with a truncated address. This is a pre-existing issue and rare in practice (requires the server to resolve the name but /api/agents to miss), but worth a follow-up guard like:

if (!agentCache.has(addr) || profile.name) {
  agentCache.set(addr, { ... });
}

Ship it 👍

[tfireubs-ui]

APPROVED

Clean, targeted fix. Pre-populating the cache from server-resolved display_name (line 340-349) is the right approach — the correspondents API already does the resolution server-side, no reason to wait for a /api/agents call that may return null for unwarmed KV entries.

The fallback chain agentCache.get(c.address) || { name: c.display_name || c.addressShort } is correctly ordered: cache wins (warming from /api/agents), then server-resolved name, then truncated address as last resort. Handles all three edge cases.

— T-FI

[tfireubs-ui]

APPROVED

Clean, targeted fix. Pre-populating the cache from server-resolved display_name (line 340-349) is the right approach — the correspondents API already does the resolution server-side, no reason to wait for a /api/agents call that may return null for unwarmed KV entries.

The fallback chain agentCache.get(c.address) || { name: c.display_name || c.addressShort } is correctly ordered: cache wins (warming from /api/agents), then server-resolved name, then truncated address as last resort. Handles all three edge cases.

— T-FI

[tfireubs-ui]

APPROVED

Pre-populating the cache from server-resolved display_name is the right call — the correspondents API already resolves this server-side. The fallback chain (cache → display_name → addressShort) handles all edge cases correctly. Verified this is targeted to the KV cache warmup race condition from #319/#320.

— T-FI

[tfireubs-ui]

Ping for merge — 2x APPROVED (biwasxyz + tfireubs-ui). CI green.

— T-FI

[tfireubs-ui]

Re-ping for merge — 2x APPROVED (biwasxyz + tfireubs-ui). CI green. Closes #320 (partial fix — pairs with #331).

[tfireubs-ui]

3rd re-ping — 2x APPROVED (biwasxyz + tfireubs-ui), CI green. Closes #320 (pairs with #331). Ready to merge when you have a moment.

[biwasxyz]

Code review

Recommend closing -- superseded by changes already in main.

The problem this PR fixes (truncated addresses on the agents page) is already solved in main. The agentCache/resolveAgentsBatch code path that this PR patches no longer exists -- main was refactored (commits 4e66670, 90f1979, dbdbaa5) to use c.display_name directly on public/agents/index.html line 315, bypassing the cache pattern entirely.

This PR would conflict heavily with the current main and its intent is fully addressed.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}