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(okx-forge): give buyers the geometry look_at_model promises, from one shared inspector helper
three.ws operatorcc1532bfb6e3
diff --git a/api/3d/look.js b/api/3d/look.jsindex 66e448b2b..28c0babc8 100644--- a/api/3d/look.js+++ b/api/3d/look.js@@ -29,30 +29,12 @@import { cors, wrap, json, readJson } from '../_lib/http.js';import { limits, clientIp } from '../_lib/rate-limit.js';-import { renderTurntable, describeGeometry, VIEW_ANGLES, DEFAULT_VIEWS, MAX_VIEWS, MIN_SIZE, MAX_SIZE, DEFAULT_SIZE } from '../_lib/3d-vision.js';+import { renderTurntable, describeGeometry, fetchGeometryStats, VIEW_ANGLES, DEFAULT_VIEWS, MAX_VIEWS, MIN_SIZE, MAX_SIZE, DEFAULT_SIZE } from '../_lib/3d-vision.js';import { persistImageBytes } from '../_lib/image-persist.js';import { originFromReq, viewerUrl, arLaunchUrl } from '../_mcp-studio/gpt-forge-client.js';const MAX_BODY_BYTES = 4_000;-// Geometry facts come from the free inspector rather than a second glTF parser-// here, so "what this model is" has exactly one implementation. It is-// best-effort: an inspector hiccup costs the caller its stats, never its-// frames, because the frames are the thing that could not be got any other way.-async function statsFor(base, glbUrl) {- try {- const res = await fetch(`${base}/api/3d/inspect?url=${encodeURIComponent(glbUrl)}`, {- headers: { accept: 'application/json' },- signal: AbortSignal.timeout(20_000),- });- if (!res.ok) return null;- const body = await res.json();- return body?.stats && typeof body.stats === 'object' ? body.stats : null;- } catch {- return null;- }-}-function discovery(base) {return {route: '/api/3d/look',@@ -136,7 +118,7 @@ export default wrap(async (req, res) => {}const wantStats = body?.stats !== false;- const stats = wantStats ? await statsFor(base, glbUrl) : null;+ const stats = wantStats ? await fetchGeometryStats(base, glbUrl) : null;return json(res, 200, {model_url: glbUrl,diff --git a/api/_lib/3d-vision.js b/api/_lib/3d-vision.jsindex a62f4474c..28129cfb2 100644--- a/api/_lib/3d-vision.js+++ b/api/_lib/3d-vision.js@@ -112,6 +112,24 @@ export async function renderTurntable({ glbUrl, views, size, background = 'transreturn { frames, failed, size: dim };}+// Geometry facts come from the free inspector (/api/3d/inspect) rather than a+// second glTF parser, so "what this model is" has exactly one implementation.+// Best-effort: an inspector hiccup costs the caller its stats, never its frames,+// because the frames are the thing that could not be got any other way.+export async function fetchGeometryStats(base, glbUrl) {+ try {+ const res = await fetch(`${base}/api/3d/inspect?url=${encodeURIComponent(glbUrl)}`, {+ headers: { accept: 'application/json' },+ signal: AbortSignal.timeout(20_000),+ });+ if (!res.ok) return null;+ const body = await res.json();+ return body?.stats && typeof body.stats === 'object' ? body.stats : null;+ } catch {+ return null;+ }+}+// Plain-language reading of the geometry, for an agent that has the numbers but// no intuition for what they mean. Every line is derived from the stats the// inspector already returns; nothing here guesses at quality it cannot measure.diff --git a/api/_mcp-studio/tools.js b/api/_mcp-studio/tools.jsindex 848c46d5f..c37451a7f 100644--- a/api/_mcp-studio/tools.js+++ b/api/_mcp-studio/tools.js@@ -45,7 +45,7 @@ import {directPrompt,} from './gpt-forge-client.js';import { COMPONENT_URI } from './component.js';-import { renderTurntable, describeGeometry } from '../_lib/3d-vision.js';+import { renderTurntable, describeGeometry, fetchGeometryStats } from '../_lib/3d-vision.js';import { buildSpatialArtifact } from '../_lib/spatial-mcp.js';// The same pure cold-start core the browser surfaces render from// (src/shared/forge-frames.js). Zero DOM, zero env, zero network, so it is safe@@ -749,22 +749,6 @@ function widgetMeta(invoking, invoked) {//// Frames are capped at 512 px and four views by default: enough for a model to// judge form and completeness, small enough not to flood the caller's context.-// Geometry from the free inspector, best-effort: a hiccup there costs the-// caller its numbers, never its frames.-async function lookStats(base, glbUrl) {- try {- const res = await fetch(`${base}/api/3d/inspect?url=${encodeURIComponent(glbUrl)}`, {- headers: { accept: 'application/json' },- signal: AbortSignal.timeout(20_000),- });- if (!res.ok) return null;- const body = await res.json();- return body?.stats && typeof body.stats === 'object' ? body.stats : null;- } catch {- return null;- }-}-async function handleLookAtModel(args, _auth, req) {const base = originFromReq(req);const glbUrl = String(args?.glb_url || '').trim();@@ -779,7 +763,7 @@ async function handleLookAtModel(args, _auth, req) {return toolError(String(err?.message || 'could not render this model').slice(0, 300));}- const stats = await lookStats(base, glbUrl);+ const stats = await fetchGeometryStats(base, glbUrl);const notes = describeGeometry(stats);const shown = turntable.frames.map((f) => f.view).join(', ');const missing = turntable.failed.length ? ` Could not render: ${turntable.failed.map((f) => f.view).join(', ')}.` : '';diff --git a/api/_okx3d/forge.js b/api/_okx3d/forge.jsindex 57b6145fa..8c69ecb9b 100644--- a/api/_okx3d/forge.js+++ b/api/_okx3d/forge.js@@ -43,7 +43,7 @@ import { startForge, pollOnce, originFromReq } from '../_mcp-studio/gpt-forge-climport { shapeSubmit, shapePoll, tierOf } from '../_mcp-studio/studio-shape.js';import { checkPromptSafety } from '../_mcp-studio/safety.js';import { objectStorageUsable } from '../_lib/r2.js';-import { renderTurntable, describeGeometry } from '../_lib/3d-vision.js';+import { renderTurntable, describeGeometry, fetchGeometryStats } from '../_lib/3d-vision.js';export { PROTOCOL_VERSION, FORGE_TOOL, FORGE_STATUS_TOOL };@@ -418,12 +418,15 @@ function buildLookTool() {} catch (err) {return toolError('render_failed', String(err?.message || 'could not render this model').slice(0, 300));}+ const stats = await fetchGeometryStats(BASE, glbUrl);+ const notes = describeGeometry(stats);const shown = turntable.frames.map((f) => f.view).join(', ');const content = [{type: 'text',text:`Rendered from ${turntable.frames.length} angle(s): ${shown}. ` ++ (notes.length ? `Geometry: ${notes.join(' ')} ` : '') +'Look at the frames below: is the subject complete and recognisable, is the far side ' +'finished, is anything melted or fused?',},@@ -440,6 +443,7 @@ function buildLookTool() {size: turntable.size,views: turntable.frames.map((f) => ({ view: f.view, theta: f.theta, phi: f.phi })),...(turntable.failed.length ? { missing_views: turntable.failed } : {}),+ ...(stats ? { stats, notes } : {}),},};},diff --git a/tests/api/okx-forge.test.js b/tests/api/okx-forge.test.jsindex fd7798c6d..067c2007a 100644--- a/tests/api/okx-forge.test.js+++ b/tests/api/okx-forge.test.js@@ -51,6 +51,18 @@ vi.mock('../../api/_lib/r2.js', async (importOriginal) => ({objectStorageUsable: vi.fn(async () => ({ ok: true, reason: null, message: null })),}));+// look_at_model renders through the shared headless browser. Stub only the+// render; the geometry fetch and its plain reading stay real, fed by the fetch+// router's /api/3d/inspect branch below.+vi.mock('../../api/_lib/3d-vision.js', async (importOriginal) => ({+ ...(await importOriginal()),+ renderTurntable: vi.fn(async ({ views }) => ({+ frames: (views || ['front']).map((view) => ({ view, theta: 0, phi: 0, png: Buffer.from([0x89, 0x50, 0x4e, 0x47]) })),+ failed: [],+ size: 256,+ })),+}));+vi.mock('../../api/_lib/usage.js', () => ({recordEvent: vi.fn(),logger: () => ({ info: () => {}, warn: () => {}, error: () => {} }),@@ -72,6 +84,7 @@ globalThis.fetch = vi.fn(async (input, init) => {}return lane.poll ? lane.poll(url) : jsonResponse(200, { status: 'running' });}+ if (url.includes('/api/3d/inspect')) return jsonResponse(200, { stats: { triangles: 12400, materials: 2, textures: 1 } });throw new Error(`unexpected fetch: ${url}`);});@@ -185,6 +198,17 @@ describe('the listed line-up is the forge', () => {}});+ // The tool's description promises the geometry and a plain reading of it, so+ // the response has to carry both, not frames alone.+ it('look_at_model returns the geometry and its reading alongside the frames', async () => {+ const look = forgeSurface('forge-draft').TOOLS.look_at_model;+ const out = await look.handler({ glb_url: 'https://cdn.test/model.glb', views: ['front', 'side'] });+ expect(out.content.filter((c) => c.type === 'image')).toHaveLength(2);+ expect(out.content[0].text).toContain('12,400 triangles');+ expect(out.structuredContent.stats).toEqual({ triangles: 12400, materials: 2, textures: 1 });+ expect(out.structuredContent.notes[0]).toContain('12,400 triangles');+ });+it('exposes one client shape: the same tool names on every endpoint', () => {for (const [id] of PAID_FORGE) {const names = forgeSurface(id).TOOL_CATALOG.map((t) => t.name);