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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
chore(prompts): file orders 411-412 for the Base ERC-8004 stall and GitHub rate-limit alert noise
nirholasb8a41cc4693f
diff --git a/prompts/finish/411-auto-base-erc8004-range-rejection.md b/prompts/finish/411-auto-base-erc8004-range-rejection.mdnew file mode 100644index 000000000..b95165885--- /dev/null+++ b/prompts/finish/411-auto-base-erc8004-range-rejection.md@@ -0,0 +1,83 @@+# 411. Fix the Base ERC-8004 crawler stall: teach `isRangeRejection()` Base's real error wording++How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate, no owner action required.++## Operating clause (binding)++- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.+- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan.+- Bug fixes are test-first: reproduce with a failing test before touching the fix, confirm it fails for the stated reason, then fix, then confirm green. Commit the test with the fix.+- The only permitted stops are the CLAUDE.md stop-and-ask gates (spend/on-chain writes, push/deploy, posting externally, committing content referencing a crypto project other than `$THREE`, destroying unrecoverable data). This order touches none of them.+- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or `git add .`), re-check `git status` and `git diff --staged` before committing.+- The em-dash and en-dash characters are banned in everything you write.++## Step 0: re-derive the current state++ curl -s https://three.ws/api/healthz | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const j=JSON.parse(d);console.log(JSON.stringify(j.subsystems.subsystems.find(s=>s.name==='agent_index'),null,2))})"++Confirm the `agent_index` subsystem still reads `status: "down"` with Base (chain 8453) named as the worst/stalest EVM chain, something like: `"EVM: ...44h+ worst cursor age (Base) across 22/22 chains, worst backlog 80,000+ blocks (Base)..."`. If Base no longer appears as the outlier (another agent already shipped this fix and it has been deployed and had time to catch up), re-run the query below to confirm `erc8004_crawl_cursor` shows all 22 chains fresh, then retire this order without a code change per the "Never blocked" table.++Confirm the exact production error text (requires the production `DATABASE_URL`, resolved on demand, never written to a file):++ export DATABASE_URL="$(node scripts/read-service-env.mjs '^DATABASE_URL$' | tail -1)"+ node -e "+ import('./api/_lib/db.js').then(async ({ sql }) => {+ const rows = await sql\`SELECT chain_id, last_block, head_block, blocks_behind, updated_at, last_error, chunk_size FROM erc8004_crawl_cursor ORDER BY blocks_behind DESC NULLS LAST LIMIT 5\`;+ console.log(rows);+ process.exit(0);+ });+ "++As measured 2026-10-24: chain_id 8453 (Base) is the only abnormal row of 22, frozen at `updated_at: 2026-10-22T07:46:23.684Z` (then 44+ hours stale and growing every tick since), `blocks_behind: 80529` and climbing, `last_error: "RPC -32602: query exceeds max results 20000, retry with the range 52932450-52933133"`. All 21 other chains show `blocks_behind: 0` and `updated_at` within the last 15 minutes.++Confirm the Cloud Scheduler job itself is running normally (ruling out a scheduling failure, not a classification bug):++ gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="three-ws-api" httpRequest.requestUrl:"erc8004-crawl"' --limit=5 --freshness=1h --project aerial-vehicle-466722-p5 --format='value(httpRequest.status, timestamp)'++Expect a dense list of `200` responses roughly every 15 minutes. The cron runs successfully every tick; the bug is purely in how one chain's error gets classified inside that successful run.++## Root cause++`api/cron/[name].js` defines `RANGE_REJECTED` (a regex of every wording a provider uses when it refuses a block range that is too wide) and `isRangeRejection(message)`, which tests a thrown RPC error's message against it. When `isRangeRejection()` returns true, `erc8004CrawlChain()` shrinks `chunkSize` via `backoffChunkSize()` and retries the same range at a narrower window, which is how the crawler self-heals against a provider's range ceiling. When it returns false, the error is treated as a genuine, unrecoverable fault: `erc8004RecordBacklog()` runs (updates `head_block`/`blocks_behind` only) and the error is rethrown up to the per-chain `catch` in `handleErc8004Crawl()`, which writes only `last_error` to the row, never `updated_at`, `last_block`, or `chunk_size`. The row then never adjusts again.++Base's real RPC answer, `"RPC -32602: query exceeds max results 20000, retry with the range 52932450-52933133"`, does not match any alternative in `RANGE_REJECTED` (`block range|range is too large|too wide|too many blocks|ranges? over \d+ blocks|query returned more than|exceed maximum block range|limited to|response size|logs matched`, case-insensitive). "query exceeds max results" and "retry with the range" are both absent from the pattern, so `isRangeRejection()` wrongly returns `false` for a message that is, semantically and literally, a range-too-wide rejection (the provider even names the exact smaller range it would accept). The adaptive shrink-and-retry path never engages for Base, so its cursor has been frozen since 2026-10-22T07:46:23.684Z.++## Task++1. Open `tests/agent-index.test.js` and find the `describe('isRangeRejection', ...)` block (around line 477). Add a new test case reproducing Base's exact verbatim error, asserting `isRangeRejection(...)` returns `true`:++ ```js+ it('reads Coinbase/Base RPC wording ("exceeds max results ... retry with the range") as a range ceiling', () => {+ // Verbatim from erc8004_crawl_cursor.last_error on chain 8453 (Base), frozen since 2026-10-22.+ expect(+ isRangeRejection('RPC -32602: query exceeds max results 20000, retry with the range 52932450-52933133'),+ ).toBe(true);+ });+ ```++2. Run `npx vitest run tests/agent-index.test.js` and confirm this new case fails (the existing `isRangeRejection` returns `false`). Confirm the failure is this exact assertion, not an unrelated error.+3. Open `api/cron/[name].js`, find the `RANGE_REJECTED` regex (around line 465, right above `isRangeRejection`). Add an alternative that matches this wording without weakening the existing negative cases the same test file already pins (`limit exceeded`, `cu limit exceeded...`, `chain is not available on free plan...` must stay `false`). A precise, narrow addition such as `exceeds? max(?:imum)? results|retry with the range` is both specific enough to avoid false-positiving the negative cases and literal enough to match real provider wording (test it against each existing case in the file, not just the new one).+4. Re-run `npx vitest run tests/agent-index.test.js` and confirm every case in the file passes, the new one included.+5. Run the full suite for this module's neighbors to catch any regression: `npx vitest run tests/agent-index.test.js tests/erc8004-chains.test.js` (second file only if it exists; check with `ls tests/ | grep erc8004` first and skip gracefully if it does not).+6. Read `api/cron/[name].js`'s `erc8004CrawlChain()` body once more (around lines 535-660) to confirm that once `isRangeRejection()` returns `true` for this message, the existing `backoffChunkSize()`/retry loop is sufficient on its own to converge Base to a servable window; no other code path needs changing. (It is: the loop shrinks `chunkSize` and retries the same `fromBlock` until a range succeeds or the floor `ERC8004_MIN_BLOCK_CHUNK=100` is hit, both comfortably under the ~683-block range Base's own error message suggested.)+7. Run `npm run check:rules -- --paths api/cron/\[name\].js tests/agent-index.test.js` and fix anything it flags.++## Done when++- `npx vitest run tests/agent-index.test.js` passes in full, including the new Base-wording case.+- `git diff` shows only the `RANGE_REJECTED` regex addition in `api/cron/[name].js` and the new test case (plus whatever `check:rules` required) in `tests/agent-index.test.js`.+- The fix and its test are committed together on `evolve` with an explicit-path commit.+- This file is removed, with a dated entry added to `prompts/finish/_context/production-100-PROGRESS.md` (create it with a one-line header if it does not exist) citing the fix commit SHA, and a note that Base's actual catch-up (the 80,000+ block backlog draining to `blocks_behind: 0`) happens automatically over the following hours once the fixed code deploys and is not something this session can force; row 1 of `prompts/finish/_context/production-100-OWNER-ACTIONS.md` already tracks the deploy cadence that carries it to production, so do not add a new row for the deploy itself.++## Never blocked++| Looks like a blocker | It is not | Do this |+|---|---|---|+| Another agent already shipped this fix | Routine for a shared worktree | Re-run step 0's healthz/DB query first; if Base is no longer the outlier and the regex already contains an equivalent alternative, retire this order without a code change |+| Tempted to widen the regex broadly (e.g. bare `exceeds`) to be safe | Over-broad matching risks reclassifying a genuine fault as a shrinkable range, which is exactly the bnbchain `limit exceeded` false positive the existing test file already guards against | Keep the new alternative as narrow as the task describes; run every existing case in the test file against it before committing, not just the new one |+| Can't reach production DB to confirm the live error text | `scripts/read-service-env.mjs` resolves it without needing the credential written anywhere | Use the exact command in step 0; never pipe its output into a committed file |+| Base's backlog has not visibly shrunk yet right after the fix lands | Catching up 80,000+ blocks at an adaptively-sized chunk takes real wall-clock time across many 15-minute ticks | This is expected; the done-when criteria do not require the backlog to be zero by the end of this session, only that the classification bug is fixed and tested |++## Report format++State: the step-0 healthz and DB query output, the failing-test confirmation before the fix, the final regex diff, the passing-test output after the fix, and the commit SHA.diff --git a/prompts/finish/412-auto-github-ratelimit-resilience.md b/prompts/finish/412-auto-github-ratelimit-resilience.mdnew file mode 100644index 000000000..543e63758--- /dev/null+++ b/prompts/finish/412-auto-github-ratelimit-resilience.md@@ -0,0 +1,100 @@+# 412. Stop the GitHub anonymous rate limit from firing unhandled 5xx alerts on ship/feed and commit-feed-push++How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate, no owner action required for the code fix (one optional, non-blocking owner action is noted at the end).++## Operating clause (binding)++- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.+- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan.+- Bug fixes are test-first: reproduce with a failing test before touching the fix, confirm it fails for the stated reason, then fix, then confirm green. Commit the test with the fix.+- The only permitted stops are the CLAUDE.md stop-and-ask gates (spend/on-chain writes, push/deploy, posting externally, committing content referencing a crypto project other than `$THREE`, destroying unrecoverable data). This order touches none of them.+- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or `git add .`), re-check `git status` and `git diff --staged` before committing.+- The em-dash and en-dash characters are banned in everything you write.++## Step 0: re-derive the current state++Production has no `GITHUB_TOKEN` or `GH_TOKEN` set, so every unauthenticated call to `api.github.com` from the Cloud Run service shares one 60-requests/hour budget per egress IP across several independent features. Confirm the alert pattern is still live:++ export DATABASE_URL="$(node scripts/read-service-env.mjs '^DATABASE_URL$' | tail -1)"+ node -e "+ import('./api/_lib/db.js').then(async ({ sql }) => {+ const rows = await sql\`SELECT signature, title, count, first_seen, last_seen FROM ops_alerts WHERE title ILIKE '%rate limit exhausted%' AND last_seen > now() - interval '24 hours' ORDER BY last_seen DESC\`;+ console.log(rows);+ process.exit(0);+ });+ "++As measured 2026-10-24: both `cron timeout`-unrelated signatures `unhandled 5xx in GET /api/cron/commit-feed-push` ("GitHub rate limit exhausted ... set GITHUB_TOKEN to raise it above 60/hour") and `unhandled 5xx in GET /api/ship/feed?limit=200&audience=internal` ("shipfeed: GitHub rate limit exhausted ... pass a token to raise it above 60/hour") fired multiple times in the preceding few hours (2026-10-24 01:00-02:25 UTC window alone: three occurrences). If this query returns nothing from the last 24 hours, re-run it against the last 7 days; if still nothing, the condition may not currently be reproducible live, but the code defect below is real and verifiable by reading the source regardless, so proceed with the fix and note the absence of fresh alerts in the report.++Confirm no `GITHUB_TOKEN`/`GH_TOKEN` is configured on the live service (this only reads config, it changes nothing):++ gcloud run services describe three-ws-api --region us-central1 --project aerial-vehicle-466722-p5 --format='value(spec.template.spec.containers[0].env)' | tr ';' '\n' | grep -i "GITHUB_TOKEN\|GH_TOKEN" || echo "confirmed: no GitHub token configured"++## Root cause++Two independent, unauthenticated call paths hit GitHub's commits API and both advertise resilience they do not actually implement:++1. **`api/ship/feed.js`'s `buildFeed()`** (around line 106). Its own file header comment claims the GitHub call is "served from last-good on an upstream blip," but `buildFeed()` uses plain `cacheGet`/`cacheSet` (a fresh-value TTL cache with nothing to fall back to), not `cacheWrapLastGood()` from `api/_lib/cache.js` (line 608), which is the exact helper that implements the last-known-good fallback this comment describes and which dozens of other upstream-dependent modules already use (`api/_lib/birdeye.js`, `api/_lib/coingecko.js`, `api/_lib/hyperliquid.js`, `api/_lib/news.js`, and others). When `fetchGitHubCommits()` throws (a rate-limit 403, or any other GitHub fault), `buildFeed()` has no catch, so the throw propagates straight out of the handler as an unhandled exception, which is what produces the `unhandled 5xx in GET /api/ship/feed` alert even though a perfectly good cached response from the last successful run is sitting right there unused.++2. **`api/_lib/commit-feed-push.js`'s `fetchCommitPage()`** (around line 142) throws a plain `Error` naming the rate-limit condition when GitHub answers `x-ratelimit-remaining: 0`. The call chain that invokes it, `pushTelegramLane()` -> `fetchCommitsSince(state.lastSha)` (around line 281), has no try/catch around that call (the only try/catch in `pushTelegramLane()` wraps the later Telegram-posting loop, not the initial GitHub fetch), so the throw propagates out of `pushTelegramLane()`, out of the cron handler's bare `try { ... } finally { ... }` (no `catch`) in `api/cron/commit-feed-push.js`, and into `wrapCron()`'s generic unhandled-error path, which is what produces the `unhandled 5xx in GET /api/cron/commit-feed-push` alert. The module's own comment at that throw site says plainly that this is an expected, no-fault condition ("a shared Cloud Run address can burn through [60/hour] without this cron doing anything wrong"), but the code does not act like it believes that: it throws instead of returning a typed, graceful skip the way every other anticipated no-op in this file does (compare the `{ skipped: 'not_configured' }` and `{ posted: 0, seeded: true }` returns a few lines away).++Both are real resilience gaps independent of whether `GITHUB_TOKEN` is ever set: even with a token raising the ceiling to 5,000/hour, a transient GitHub outage or a shared-IP burst from an unrelated caller can still exhaust it, and today both paths turn that into a noisy false-urgency "unhandled 5xx" instead of the graceful degradation the surrounding code already assumes exists.++## Task++### Part A: `api/ship/feed.js` serves stale instead of throwing++1. Add a test-first regression in `tests/ship-feed-endpoint.test.js` (read it first to match its existing mocking style for `cacheGet`/`cacheSet`/`fetchGitHubCommits` or whatever upstream fetch it already stubs) that: primes the cache with one successful `buildFeed()` result, then makes the next call's GitHub fetch throw a rate-limit-shaped error, and asserts the endpoint still returns the previous feed (marked stale) instead of a 5xx. Run it and confirm it fails against today's code.+2. In `api/ship/feed.js`, change `buildFeed()` to wrap its GitHub-dependent work in `cacheWrapLastGood(key, CACHE_TTL_S, async () => { ...the existing fetch+build body... }, { withMeta: true })` (imported from `../_lib/cache.js` alongside the existing `cacheGet`/`cacheSet`, or replacing them entirely if nothing else in the file still needs the bare versions), and thread the returned `{ value, stale }` into the response shape the handler already returns (`{ ...value, cached: false, stale }` on a fresh-but-stale-serving path, matching the existing `cached` flag convention in the file).+3. Re-run the new test and confirm it passes. Run the rest of `tests/ship-feed-endpoint.test.js` to confirm no regression.++### Part B: `api/_lib/commit-feed-push.js` skips gracefully instead of throwing++1. Tag the rate-limit error at its throw site (around line 145) with a stable, exported predicate instead of a bare message string callers must pattern-match, e.g.:++ ```js+ export function githubRateLimitError(resetMs) {+ const until = Number.isFinite(resetMs) ? new Date(resetMs).toISOString() : 'unknown';+ return Object.assign(+ new Error(`GitHub rate limit exhausted (resets ${until}); set GITHUB_TOKEN to raise it above 60/hour`),+ { githubRateLimited: true, retryAfter: Number.isFinite(resetMs) ? until : null },+ );+ }+ export function isGithubRateLimitError(err) {+ return Boolean(err?.githubRateLimited);+ }+ ```++ and use `throw githubRateLimitError(reset)` in place of the existing `throw new Error(...)` at that site.+2. Add a test-first regression in `tests/commit-feed-push.test.js` for `isGithubRateLimitError`/`githubRateLimitError` (no DB needed, pure functions): confirms a tagged error round-trips true, and a generic `new Error('boom')` reads false. Confirm it fails before the helpers exist, passes after.+3. In `pushTelegramLane()` (around line 281), wrap the `const { commits, found } = await fetchCommitsSince(state.lastSha);` call in its own try/catch: on `isGithubRateLimitError(err)`, `console.warn` a one-line notice and `return { posted: 0, skipped: 'github_rate_limited', retryAfter: err.retryAfter };` immediately (releasing the lock still happens in the cron handler's `finally`); any other error rethrows unchanged (out of scope for this order; only the named, previously-unhandled rate-limit case is being fixed).+4. Add a second test-first regression, following the existing PGlite-mocking pattern already established in `tests/x-mention-health.test.js` (`vi.mock('../api/_lib/db.js', ...)` backed by `@electric-sql/pglite`), that drives `pushTelegramLane()` with a `getPage`-equivalent failure path (check whether `pushTelegramLane` needs a small injectable-fetch parameter added, following the same shape `fetchCommitsSince` already accepts, to make this testable without mocking global `fetch`) and asserts it returns `{ posted: 0, skipped: 'github_rate_limited', retryAfter: ... }` rather than rejecting. Confirm it fails before the Part B.3 fix, passes after.+5. Confirm `api/cron/commit-feed-push.js` needs no change: it already treats any `telegram` result without a truthy `.error` as a 200 success, so the new `{ skipped: 'github_rate_limited', ... }` shape naturally returns 200, not 502.++### Part C: verify and close++1. Run `npx vitest run tests/ship-feed-endpoint.test.js tests/commit-feed-push.test.js` and confirm everything passes.+2. Run `npm run check:rules -- --paths api/ship/feed.js api/_lib/commit-feed-push.js api/_lib/cache.js tests/ship-feed-endpoint.test.js tests/commit-feed-push.test.js` and fix anything it flags (omit `api/_lib/cache.js` from the paths if Part A needed no change to it).+3. Add one dated row to `prompts/finish/_context/production-100-OWNER-ACTIONS.md` noting that setting `GITHUB_TOKEN` (a GitHub personal access token with no special scopes, read-only public access is enough) via `gcloud run services update three-ws-api --region us-central1 --update-env-vars GITHUB_TOKEN=<token>` would raise the shared ceiling from 60 to 5,000 requests/hour and reduce how often the new stale/skip paths this order ships are ever exercised; this is optional and does not block this order's completion, since the fix above already makes exhaustion a non-event instead of an alert-worthy failure.++## Done when++- `npx vitest run tests/ship-feed-endpoint.test.js tests/commit-feed-push.test.js` passes in full, including every new case.+- `api/ship/feed.js`'s `buildFeed()` uses `cacheWrapLastGood()` and serves a stale-but-marked response instead of throwing when GitHub is unreachable or rate-limited.+- `api/_lib/commit-feed-push.js`'s `pushTelegramLane()` returns `{ skipped: 'github_rate_limited', ... }` instead of throwing when GitHub answers a rate limit, and the cron handler's existing 200/502 logic naturally reflects that without modification.+- `git diff` reviewed; every changed line matches one of Part A, B, or C above.+- The fix and its tests are committed together on `evolve` with an explicit-path commit.+- This file is removed, with a dated entry added to `prompts/finish/_context/production-100-PROGRESS.md` citing the fix commit SHA, and the owner-action row from Part C.3 is in place.++## Never blocked++| Looks like a blocker | It is not | Do this |+|---|---|---|+| `tests/ship-feed-endpoint.test.js` doesn't already stub the GitHub fetch in a way that's easy to make throw | Read the file first; it already exercises `buildFeed()`'s success path, so the fetch seam exists | Reuse whatever injection point the existing tests use (a mocked `fetchGitHubCommits`/`fetchUpstream` or an injected `fetchImpl`); if none exists, add the smallest possible seam, matching the style `fetchCommitsSince`'s `getPage` option already sets in this repo |+| `pushTelegramLane()` has no injectable fetch today, making the DB-backed regression test awkward | Small, surgical seams are normal in this codebase (`fetchCommitsSince` already has one) | Add one parameter (default to the real `fetchCommitPage`) rather than mocking global `fetch`; keep the production call site unchanged (no argument passed, so it uses the default) |+| The live `ops_alerts` query in step 0 comes back empty | The alert is intermittent by nature (depends on shared-IP traffic), not permanently reproducible on demand | The code-level defect (no catch, no last-good fallback) is verifiable by reading the source regardless of whether an alert is firing right now; proceed with the fix and note this in the report |+| Tempted to also wire a cross-process GitHub call budget (shared rate limiter) to stop exhaustion happening at all | Out of scope: this order fixes the alert-worthy symptom (an avoidable failure mode turning into noisy unhandled 5xx), not the underlying shared-IP quota, which the optional `GITHUB_TOKEN` owner action in Part C.3 addresses far more effectively than new client-side throttling would | Do not build new rate-limiting infrastructure for this order; ship the two resilience fixes and the owner-action note |++## Report format++State: the step-0 `ops_alerts` and `gcloud run services describe` output, the failing-test confirmation for each of Part A and Part B before their fixes, the diffs, the passing-test output after, and the commit SHA.