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(agents): log the upstream failure when an alpha read's LLM chain is exhausted

nirholas9a9a0c8e186a
diff --git a/api/agents/alpha.js b/api/agents/alpha.js
index a906de19e..88e42ca65 100644
--- a/api/agents/alpha.js
+++ b/api/agents/alpha.js
@@ -362,6 +362,7 @@ async function handleRead(req, res, id) {
return error(res, 503, 'narrator_offline', 'The co-pilot narrator is offline right now. Your wallet and trading still work — try the read again shortly.');
}
if (e?.code === 'daily_spend_cap_exceeded') return error(res, 429, e.code, e.message);
+ console.error('[agents/alpha] read failed', mint, e?.message || e);
return error(res, 502, 'read_failed', 'The co-pilot could not complete this read. Try again.');
}
diff --git a/tests/alpha-read-handler.test.js b/tests/alpha-read-handler.test.js
new file mode 100644
index 000000000..dc21f94f1
--- /dev/null
+++ b/tests/alpha-read-handler.test.js
@@ -0,0 +1,160 @@
+// Boundary coverage for POST /api/agents/:id/alpha/read: the in-character
+// alpha co-pilot's live-launch read. The contract under test here is narrow:
+// when the LLM chain is exhausted by an opaque upstream failure (the common
+// case in production: LlmUnavailableError is effectively unreachable once
+// the keyless OVH/Pollinations lanes are unconditional, per llm.js's own
+// tests), the generic 502 branch must log a diagnostic line naming the
+// mint and the upstream failure, the same way api/persona/preview.js does.
+// Before this fix the branch returned 502 silently, making every chain-
+// exhaustion failure on this route invisible in production logs.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const getSessionUserMock = vi.fn();
+const authenticateBearerMock = vi.fn();
+const extractBearerMock = vi.fn();
+vi.mock('../api/_lib/auth.js', () => ({
+ getSessionUser: (...a) => getSessionUserMock(...a),
+ authenticateBearer: (...a) => authenticateBearerMock(...a),
+ extractBearer: (...a) => extractBearerMock(...a),
+}));
+
+const sqlMock = vi.fn();
+vi.mock('../api/_lib/db.js', () => ({ sql: (...a) => sqlMock(...a) }));
+
+const tradePerUserLimit = vi.fn();
+const publicIpLimit = vi.fn();
+vi.mock('../api/_lib/rate-limit.js', () => ({
+ limits: {
+ tradePerUser: (...a) => tradePerUserLimit(...a),
+ publicIp: (...a) => publicIpLimit(...a),
+ },
+ clientIp: () => '127.0.0.1',
+}));
+
+vi.mock('../api/_lib/agent-pumpfun.js', () => ({
+ solanaPublicConnection: () => ({ getBalance: vi.fn().mockResolvedValue(0) }),
+}));
+vi.mock('../api/_lib/smart-money.js', () => ({
+ getSmartMoneyForMint: vi.fn().mockResolvedValue({ smart_money_score: 58, count: 3, sybil_flag: false }),
+}));
+vi.mock('../api/_lib/agent-trade-guards.js', () => ({
+ getTradeLimits: () => ({ per_trade_sol: 0.5, daily_budget_sol: 2, kill_switch: false }),
+ getSpendLimits: () => ({ frozen: false }),
+ getDailySpendLamports: vi.fn().mockResolvedValue(0n),
+}));
+vi.mock('../api/_lib/solana/sdk-bridge.js', () => ({
+ getBondingCurveState: vi.fn().mockResolvedValue({ realSolReserves: 8_400_000_000n, complete: false }),
+ getBuyQuote: vi.fn().mockResolvedValue({ priceImpact: 2.3 }),
+ getGraduationProgress: vi.fn().mockResolvedValue({ progress: 0.41 }),
+}));
+vi.mock('../api/_lib/pumpfun-ws-feed.js', () => ({
+ connectPumpFunFeed: vi.fn(),
+ recentBuffered: vi.fn().mockReturnValue([]),
+ recentGraduations: vi.fn().mockReturnValue([]),
+}));
+vi.mock('../api/_lib/pump-feed-fetch.js', () => ({
+ pumpFetchJson: vi.fn().mockResolvedValue({ ok: true, body: { symbol: 'WIDGET', name: 'Widget', usd_market_cap: 23000, created_timestamp: Date.now() - 14 * 60_000 } }),
+}));
+vi.mock('../api/_lib/upstream-fetch.js', () => ({
+ fetchUpstreamJson: vi.fn().mockResolvedValue({ pairs: [] }),
+}));
+
+const llmCompleteMock = vi.fn();
+class FakeLlmUnavailable extends Error {}
+vi.mock('../api/_lib/llm.js', () => ({
+ llmComplete: (...a) => llmCompleteMock(...a),
+ LlmUnavailableError: FakeLlmUnavailable,
+}));
+
+const { default: alphaHandler } = await import('../api/agents/alpha.js');
+
+const AGENT_ID = 'agent-1';
+const MINT = '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU';
+
+function mkReq({ body } = {}) {
+ return {
+ method: 'POST',
+ url: `/api/agents/${AGENT_ID}/alpha/read`,
+ headers: { 'content-type': 'application/json' },
+ on(event, cb) {
+ if (event === 'data' && body != null) {
+ const buf = Buffer.from(JSON.stringify(body));
+ queueMicrotask(() => { cb(buf); this._endCb?.(); });
+ } else if (event === 'end') this._endCb = cb;
+ },
+ destroy() {},
+ };
+}
+function mkRes() {
+ return {
+ statusCode: 200, headers: {}, body: undefined, writableEnded: false,
+ setHeader(k, v) { this.headers[k.toLowerCase()] = v; },
+ end(b) { this.body = b; this.writableEnded = true; },
+ };
+}
+const parse = (res) => (res.body ? JSON.parse(res.body) : undefined);
+
+async function callRead(body) {
+ const res = mkRes();
+ await alphaHandler(mkReq({ body }), res, AGENT_ID, 'read');
+ return res;
+}
+
+describe('POST /api/agents/:id/alpha/read - LLM failure handling', () => {
+ let consoleErrorSpy;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ getSessionUserMock.mockResolvedValue(null);
+ authenticateBearerMock.mockResolvedValue(null);
+ tradePerUserLimit.mockResolvedValue({ success: true });
+ publicIpLimit.mockResolvedValue({ success: true });
+ sqlMock.mockImplementation(() => {
+ const rows = [{
+ id: AGENT_ID, user_id: 'owner-1', name: 'Scout', persona_prompt: 'terse trader',
+ voice_provider: 'browser', voice_id: null, avatar_id: null,
+ is_published: true, meta: {},
+ }];
+ const p = Promise.resolve(rows);
+ p.catch = (fn) => p.then(undefined, fn);
+ return p;
+ });
+ consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+ });
+ afterEach(() => {
+ consoleErrorSpy.mockRestore();
+ });
+
+ it('returns 503 narrator_offline and does not require a diagnostic log when the provider chain reports LlmUnavailableError', async () => {
+ llmCompleteMock.mockRejectedValue(new FakeLlmUnavailable('no provider configured'));
+ const res = await callRead({ mint: MINT, network: 'mainnet' });
+ expect(res.statusCode).toBe(503);
+ expect(parse(res).error).toBe('narrator_offline');
+ });
+
+ it('logs a diagnostic line naming the mint and the upstream failure when the chain is exhausted by an opaque upstream error', async () => {
+ llmCompleteMock.mockRejectedValue(Object.assign(new Error('nvidia unreachable: fetch failed'), {
+ status: 502, code: 'upstream_error',
+ }));
+ const res = await callRead({ mint: MINT, network: 'mainnet' });
+
+ expect(res.statusCode).toBe(502);
+ expect(parse(res).error).toBe('read_failed');
+ // The bug: this branch used to return 502 with zero logging, so every
+ // chain-exhaustion failure on this route was invisible in production logs.
+ expect(consoleErrorSpy).toHaveBeenCalledWith(
+ expect.stringContaining('[agents/alpha]'),
+ MINT,
+ expect.stringContaining('nvidia unreachable'),
+ );
+ });
+
+ it('returns 429 daily_spend_cap_exceeded without masking it as read_failed', async () => {
+ llmCompleteMock.mockRejectedValue(Object.assign(new Error('daily cap hit'), {
+ code: 'daily_spend_cap_exceeded',
+ }));
+ const res = await callRead({ mint: MINT, network: 'mainnet' });
+ expect(res.statusCode).toBe(429);
+ expect(parse(res).error).toBe('daily_spend_cap_exceeded');
+ });
+});