0.48.0 — carry over PR #136: key from a file, and Retry-After on 429

[VickyXAI]

Salvages the two good ideas from @KillerQueen-Z's #136 that the shipped implementation did not have, and closes that PR as superseded.

What happened

#136 implemented account-API-key support in parallel, opened 2026-09-04 and gated on @blockrun/llm #36 being published. That gate lifted this morning, and 0.46.0 / 0.47.0 shipped the same feature before #136 could be rebased — so it is now unmergeable against main and its CI is red on a typecheck error plus the stale ^3.8.4 pin it was explicitly waiting to replace.

Rather than close it and lose the work, this carries over the parts it got right.

~/.blockrun/.api-key

The shipped implementation read BLOCKRUN_API_KEY and nothing else. #136 also read a file, and that is the better call: a stdio MCP server is launched by its client, and several clients make setting an environment variable awkward or impossible — which is exactly why the wallet has always had ~/.blockrun/.session. The key needs the same escape hatch.

Precedence is env, then file, mirroring BLOCKRUN_WALLET_KEY over .session: an explicitly exported key is a deliberate override and must not be shadowed by whatever is left on disk from an earlier account.

• empty or unreadable file → falls through to wallet mode, rather than taking the server down over a permissions error
• malformed key → still fails loudly, and the message now names which source it came from, so "invalid key" does not send someone to check an env var they never set

Retry-After on 429

Surfaced instead of buried in the response body. It is the one part of a rate-limit response a caller can act on; an agent told only "rate limited" retries immediately and is refused again.

Verification

Ran the built server against a temp HOME holding only the key file, with no environment variable set anywhere:

Paying with: BlockRun account API key (no wallet, no chain)

  Account:  pilot (ungated)
  Spent to date: $4.5985 (invoiced account — no prepaid ceiling)

Four new tests cover the file path, env-outranks-file, a malformed file naming itself, and an empty file falling through. Tests 458 → 462.

Not carried over

#136's accountJson helper duplicates polling and origin-pinning that utils/api-key-call.ts and utils/wallet.ts:resolveGatewayUrl already do, with tests. Its requirements-api-preview.txt was a temporary note for the unpublished SDK and is obsolete.

🤖 Generated with Claude Code

https://claude.ai/code/session_0116SvLAGyzJ4SYKBvAE2DTc