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(mcp): surface error_description so an agent sees the actionable half of a three.ws failure

nirholas66dad03f7790
diff --git a/packages/kol-mcp/src/lib/api.js b/packages/kol-mcp/src/lib/api.js
index 4b01992d6..9166671d1 100644
--- a/packages/kol-mcp/src/lib/api.js
+++ b/packages/kol-mcp/src/lib/api.js
@@ -59,7 +59,14 @@ export async function apiRequest(path, { method = 'GET', query, body } = {}) {
}
if (!res.ok) {
- const message = data?.message || data?.error || `three.ws ${path} returned HTTP ${res.status}`;
+ // three.ws answers a failure as { error: <code>, error_description: <sentence> }
+ // (api/_lib/http.js `error`). The description is the half a human can act on,
+ // so it leads; without it an agent only ever sees the bare code.
+ const message =
+ data?.error_description ||
+ data?.message ||
+ data?.error ||
+ `three.ws ${path} returned HTTP ${res.status}`;
throw Object.assign(new Error(message), { code: 'upstream_error', status: res.status, body: data });
}
return data;
diff --git a/packages/loom-mcp/src/lib/api.js b/packages/loom-mcp/src/lib/api.js
index 4b01992d6..9166671d1 100644
--- a/packages/loom-mcp/src/lib/api.js
+++ b/packages/loom-mcp/src/lib/api.js
@@ -59,7 +59,14 @@ export async function apiRequest(path, { method = 'GET', query, body } = {}) {
}
if (!res.ok) {
- const message = data?.message || data?.error || `three.ws ${path} returned HTTP ${res.status}`;
+ // three.ws answers a failure as { error: <code>, error_description: <sentence> }
+ // (api/_lib/http.js `error`). The description is the half a human can act on,
+ // so it leads; without it an agent only ever sees the bare code.
+ const message =
+ data?.error_description ||
+ data?.message ||
+ data?.error ||
+ `three.ws ${path} returned HTTP ${res.status}`;
throw Object.assign(new Error(message), { code: 'upstream_error', status: res.status, body: data });
}
return data;
diff --git a/packages/marketplace-mcp/src/lib/api.js b/packages/marketplace-mcp/src/lib/api.js
index 65512807b..08f80f49b 100644
--- a/packages/marketplace-mcp/src/lib/api.js
+++ b/packages/marketplace-mcp/src/lib/api.js
@@ -59,7 +59,14 @@ export async function apiRequest(path, { method = 'GET', query, body } = {}) {
}
if (!res.ok) {
- const message = data?.message || data?.error || `three.ws ${path} returned HTTP ${res.status}`;
+ // three.ws answers a failure as { error: <code>, error_description: <sentence> }
+ // (api/_lib/http.js `error`). The description is the half a human can act on,
+ // so it leads; without it an agent only ever sees the bare code.
+ const message =
+ data?.error_description ||
+ data?.message ||
+ data?.error ||
+ `three.ws ${path} returned HTTP ${res.status}`;
throw Object.assign(new Error(message), { code: 'upstream_error', status: res.status, body: data });
}
return data;
diff --git a/tests/api/onchain-card-token-id.test.js b/tests/api/onchain-card-token-id.test.js
new file mode 100644
index 000000000..bfda323cc
--- /dev/null
+++ b/tests/api/onchain-card-token-id.test.js
@@ -0,0 +1,149 @@
+// The on-chain social-card handlers (/api/a-og, /api/a-page) take the chain id
+// and the ERC-721 token id straight off the query string. Both used to hand an
+// unvalidated token id to `BigInt()` inside resolveOnChainAgent, which throws a
+// SyntaxError on anything non-numeric: a caller typo became an unhandled 500
+// plus a Sentry event and an ops alert. These pin the 4xx contract, and the
+// resolver's own guard, so that cannot come back.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Readable } from 'node:stream';
+
+process.env.PUBLIC_APP_ORIGIN ||= 'https://three.ws';
+
+const resolved = { value: { chainId: 8453, agentId: '1', name: 'Nova', description: 'a guide' } };
+const resolveSpy = vi.fn(async () => resolved.value);
+
+vi.mock('../../api/_lib/onchain.js', async (importOriginal) => {
+ // Keep isTokenId and SERVER_CHAIN_META real: the handlers' guards are exactly
+ // what is under test here. Only the network read is replaced.
+ const actual = await importOriginal();
+ return { ...actual, resolveOnChainAgent: (...a) => resolveSpy(...a) };
+});
+
+const { default: ogHandler } = await import('../../api/a-og.js');
+const { default: pageHandler } = await import('../../api/a-page.js');
+const { isTokenId } = await import('../../api/_lib/onchain.js');
+const { resolveOnChainAgent } = await vi.importActual('../../api/_lib/onchain.js');
+
+function makeReq(url, method = 'GET') {
+ const stream = Readable.from([]);
+ stream.method = method;
+ stream.url = url;
+ stream.headers = { host: 'three.ws' };
+ return stream;
+}
+
+function makeRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: '',
+ writableEnded: false,
+ setHeader(k, v) { this.headers[k.toLowerCase()] = v; },
+ getHeader(k) { return this.headers[k.toLowerCase()]; },
+ end(chunk) { if (chunk !== undefined) this.body += String(chunk); this.writableEnded = true; },
+ };
+}
+
+async function call(handler, url, method = 'GET') {
+ const res = makeRes();
+ await handler(makeReq(url, method), res);
+ return res;
+}
+
+beforeEach(() => {
+ resolveSpy.mockClear();
+ resolved.value = { chainId: 8453, agentId: '1', name: 'Nova', description: 'a guide' };
+});
+
+describe('isTokenId', () => {
+ it('accepts decimal token ids up to the uint256 ceiling', () => {
+ expect(isTokenId('0')).toBe(true);
+ expect(isTokenId('1')).toBe(true);
+ expect(isTokenId(42)).toBe(true);
+ expect(isTokenId(((1n << 256n) - 1n).toString())).toBe(true);
+ });
+
+ it('rejects anything a uint256 column cannot hold', () => {
+ expect(isTokenId('abc')).toBe(false);
+ expect(isTokenId('-1')).toBe(false);
+ expect(isTokenId('1.5')).toBe(false);
+ expect(isTokenId('0x01')).toBe(false);
+ expect(isTokenId('1_000')).toBe(false);
+ expect(isTokenId('')).toBe(false);
+ expect(isTokenId(null)).toBe(false);
+ expect(isTokenId((1n << 256n).toString())).toBe(false);
+ });
+});
+
+describe('resolveOnChainAgent guards the token id', () => {
+ it('reports a malformed id instead of throwing out of BigInt()', async () => {
+ const result = await resolveOnChainAgent({ chainId: 8453, agentId: 'abc' });
+ expect(result.error).toBe('invalid_agent_id');
+ });
+});
+
+describe('GET /api/a-og', () => {
+ it('400s a missing chain rather than resolving against chain 0', async () => {
+ const res = await call(ogHandler, '/api/a-og?id=1');
+ expect(res.statusCode).toBe(400);
+ expect(resolveSpy).not.toHaveBeenCalled();
+ });
+
+ it('400s an unsupported chain', async () => {
+ const res = await call(ogHandler, '/api/a-og?chain=999999&id=1');
+ expect(res.statusCode).toBe(400);
+ expect(JSON.parse(res.body).error).toBe('unsupported_chain');
+ expect(resolveSpy).not.toHaveBeenCalled();
+ });
+
+ it('400s a non-numeric token id', async () => {
+ const res = await call(ogHandler, '/api/a-og?chain=8453&id=abc');
+ expect(res.statusCode).toBe(400);
+ expect(resolveSpy).not.toHaveBeenCalled();
+ });
+
+ it('renders the SVG card for a resolvable agent', async () => {
+ const res = await call(ogHandler, '/api/a-og?chain=8453&id=1');
+ expect(res.statusCode).toBe(200);
+ expect(res.headers['content-type']).toContain('image/svg+xml');
+ expect(res.body).toContain('Nova');
+ });
+
+ it('still serves the card when the resolve degraded, with a short cache', async () => {
+ // A chain_read error is ambiguous (missing token or a flaky RPC). Hard-404ing
+ // it broke the social image of agents that do exist for as long as the edge
+ // cached the 404.
+ resolved.value = { chainId: 8453, agentId: '1', name: null, error: 'chain_read: timeout' };
+ const res = await call(ogHandler, '/api/a-og?chain=8453&id=1');
+ expect(res.statusCode).toBe(200);
+ expect(res.headers['cache-control']).toBe('public, max-age=60');
+ });
+
+ it('rejects a non-GET method with 405', async () => {
+ const res = await call(ogHandler, '/api/a-og?chain=8453&id=1', 'POST');
+ expect(res.statusCode).toBe(405);
+ });
+});
+
+describe('GET /api/a-page', () => {
+ it('serves the designed 404 page for a non-numeric token id', async () => {
+ const res = await call(pageHandler, '/api/a-page?chain=8453&id=abc');
+ expect(res.statusCode).toBe(404);
+ expect(res.headers['content-type']).toContain('text/html');
+ expect(res.body).toContain('Agent not found');
+ expect(resolveSpy).not.toHaveBeenCalled();
+ });
+
+ it('serves the metadata page for a valid id', async () => {
+ const res = await call(pageHandler, '/api/a-page?chain=8453&id=1');
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toContain('og:title');
+ expect(res.body).toContain('Nova');
+ });
+
+ it('rejects a non-GET method with 405', async () => {
+ const res = await call(pageHandler, '/api/a-page?chain=8453&id=1', 'POST');
+ expect(res.statusCode).toBe(405);
+ });
+});