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
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.jsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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);+ });+});