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(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.js
index 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.js
index 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 = 'trans
return { 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.js
index 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.js
index 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-cl
import { 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.js
index 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);