Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(agent-index): stop sorting a permanently broken chain to the back of the sweep

nirholas44e97ea5a05d
diff --git a/api/cron/[name].js b/api/cron/[name].js
index f048d821e..2875a8040 100644
--- a/api/cron/[name].js
+++ b/api/cron/[name].js
@@ -398,15 +398,41 @@ async function erc8004CrawlOrder() {
return [...CHAINS].sort((a, b) => rank(by.get(b.id)) - rank(by.get(a.id)));
}
-// Never-crawled sorts above every backlog; otherwise the backlog itself ranks,
-// with cursor age breaking ties between two caught-up chains so the sweep still
-// rotates instead of re-serving the same head every tick.
-function rank(cursor) {
+// Ceiling on how far cursor age alone can lift a chain that reports no backlog.
+// It has to be high enough that a cursor stale for days outranks one crawled
+// minutes ago, and low enough that it never preempts a chain with a real
+// backlog to clear.
+const STALE_RANK_CAP = 10_000;
+
+/**
+ * Sweep priority for one chain's cursor. Never-crawled sorts above every
+ * backlog; otherwise the backlog itself ranks, and a chain reporting no backlog
+ * ranks by how long its cursor has been standing still.
+ *
+ * That last clause used to be `Math.min(ageMin, 1)`, which silently disabled
+ * itself. The cron runs every 15 minutes, so by the time it reads the table
+ * EVERY caught-up chain is older than the 1-minute cap and they all return
+ * exactly 1. The sort then falls through to the declared array order on every
+ * single tick, which is the starvation the tie-break was added to prevent.
+ *
+ * It also hid broken chains. blocks_behind is only written by a SUCCESSFUL
+ * crawl, so a chain erroring on every tick keeps reporting whatever its last
+ * good crawl left, which is 0, and reads as caught up forever. Measured
+ * 2026-08-28: Polygon's cursor had not advanced in 122 days and BNB Chain's in
+ * 89, both still reporting 0 blocks behind, both sorted to the bottom of every
+ * sweep. Ranking them by age puts the most-starved chains at the front of a
+ * tick that runs out of budget, which is the only time the order matters.
+ * Pure: the clock is injected. This is the seam the tests drive.
+ * @param {{ blocks_behind?: number|string|null, updated_at?: string|Date|null }|null|undefined} cursor
+ * @param {number} [now]
+ * @returns {number}
+ */
+export function rank(cursor, now = Date.now()) {
if (!cursor) return Number.MAX_SAFE_INTEGER;
const behind = Number(cursor.blocks_behind || 0);
if (behind > 0) return behind;
- const ageMin = cursor.updated_at ? (Date.now() - new Date(cursor.updated_at).getTime()) / 60_000 : 0;
- return Math.min(ageMin, 1);
+ const ageMin = cursor.updated_at ? (now - new Date(cursor.updated_at).getTime()) / 60_000 : 0;
+ return Math.min(Math.max(ageMin, 0), STALE_RANK_CAP);
}
// Concurrent eth_getBlockByNumber calls while stamping a range's event blocks.
diff --git a/tests/agent-index.test.js b/tests/agent-index.test.js
index 744e4cb54..624d2bb44 100644
--- a/tests/agent-index.test.js
+++ b/tests/agent-index.test.js
@@ -31,6 +31,7 @@ import {
backoffChunkSize,
isRangeRejection,
catchUpCandidates,
+ rank,
} from '../api/cron/[name].js';
import { splitCapabilities } from '../api/explore-item.js';
import { decodeReputationLog } from '../api/_lib/erc8004-reputation-events.js';
@@ -573,3 +574,50 @@ describe('catchUpCandidates', () => {
expect(catchUpCandidates(undefined)).toEqual([]);
});
});
+
+// ─── rank ────────────────────────────────────────────────────────────────────
+
+describe('rank', () => {
+ const NOW = 1_787_877_609_500;
+ const minsAgo = (m) => new Date(NOW - m * 60_000).toISOString();
+
+ it('puts a never-crawled chain above everything', () => {
+ expect(rank(null, NOW)).toBeGreaterThan(rank({ blocks_behind: 18_375_509 }, NOW));
+ });
+
+ it('ranks a real backlog by its size', () => {
+ expect(rank({ blocks_behind: 18_375_509 }, NOW)).toBe(18_375_509);
+ expect(rank({ blocks_behind: 18_375_509 }, NOW)).toBeGreaterThan(
+ rank({ blocks_behind: 15_668_383 }, NOW),
+ );
+ });
+
+ it('separates caught-up chains by cursor age instead of collapsing them', () => {
+ // The old Math.min(ageMin, 1) returned exactly 1 for every chain older than
+ // a minute, and the cron runs every 15, so the sort fell through to the
+ // declared array order on every tick and the tail was served last forever.
+ const fresh = rank({ blocks_behind: 0, updated_at: minsAgo(15) }, NOW);
+ const stale = rank({ blocks_behind: 0, updated_at: minsAgo(60 * 24 * 122) }, NOW);
+ expect(stale).toBeGreaterThan(fresh);
+ });
+
+ it('lifts a chain that errors every tick above the healthy ones', () => {
+ // blocks_behind is only written by a SUCCESSFUL crawl, so a chain failing on
+ // every tick reports 0 behind forever and used to read as caught up. Polygon
+ // sat 122 days like this on 2026-08-28.
+ const broken = rank({ blocks_behind: 0, updated_at: minsAgo(60 * 24 * 122) }, NOW);
+ const healthy = rank({ blocks_behind: 0, updated_at: minsAgo(15) }, NOW);
+ expect(broken).toBeGreaterThan(healthy);
+ });
+
+ it('never lets mere staleness preempt a chain with a real backlog', () => {
+ const stale = rank({ blocks_behind: 0, updated_at: minsAgo(60 * 24 * 365) }, NOW);
+ expect(stale).toBeLessThan(rank({ blocks_behind: 18_375_509 }, NOW));
+ expect(stale).toBeLessThan(rank({ blocks_behind: 500_000 }, NOW));
+ });
+
+ it('treats a missing or future timestamp as no age, never a negative rank', () => {
+ expect(rank({ blocks_behind: 0, updated_at: null }, NOW)).toBe(0);
+ expect(rank({ blocks_behind: 0, updated_at: new Date(NOW + 60_000).toISOString() }, NOW)).toBe(0);
+ });
+});