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.
Scripts
This directory contains various scripts for the 3D-Agent application.
Usage
...
Operational
gcp-logs.mjs: read/tail Cloud Run production logs (vercel logs equivalent)
npm run logs # three-ws-api, last hour
npm run logs:tail # live tail
npm run logs -- -s model-rig --errors --since 2d
npm run logs -- --all --grep "forge" --warnings
Renders app logs (textPayload/jsonPayload) and request logs chronologically,
severity-colored, for any service in the fleet. Full guide:
docs/ops/gcp-logs.md.
gcp-triage.mjs: automated production monitor
npm run triage:gcp # human report
npm run triage:gcp -- --json # what agents consume (exit 1 = actionable findings)
Merges /api/healthz with a fleet-wide WARNING+ log sweep, fingerprints
repeated signatures, classifies each against the runbook
(docs/ops/production-log-triage.md) into
owner / env-action / investigate / self-healing, and prints the concrete action
per finding. Agents drive the fix loop via the /gcp-triage skill.
inspect-pbr-channels.mjs — PBR channel matrix for any GLB
node scripts/inspect-pbr-channels.mjs public/avatars/fox.glb
node scripts/inspect-pbr-channels.mjs --json https://storage.googleapis.com/three-ws-avatar-reconstructions/mesh.glb
Loads a local file or public https GLB with @gltf-transform/core and reports,
per material, whether baseColor/normal/metallicRoughness/occlusion/emissive
are a real texture, a flat factor, or missing, plus which KHR_materials_*
extensions (clearcoat, transmission, sheen, ior, anisotropy, volume) are
present. This is the ground truth for auditing whether a forge lane emits a
full PBR set or just albedo, without opening the GLB in a 3D editor by hand.
inspect-glb-geometry.mjs: meshes, attributes, and container extensions
node scripts/inspect-glb-geometry.mjs public/avatars/default.glb
node scripts/inspect-glb-geometry.mjs public/avatars/ # a whole directory
node scripts/inspect-glb-geometry.mjs --json a.glb b.glb
The mesh-side companion to the two PBR inspectors above. Prints mesh and skin
names, per-primitive vertex attributes, vertex/index counts, and the POSITION
component type, plus extensionsUsed / extensionsRequired.
Three questions it answers that the material inspectors cannot: a primitive with
no NORMAL renders flat-shaded and one with no TEXCOORD_0 cannot receive any
texture a forge lane derives for it, so an "it came back untextured" report is
often an attribute problem; a POSITION that is not FLOAT means the mesh is
quantized (KHR_mesh_quantization, usually beside EXT_meshopt_compression),
which is why every mesh-consuming worker decodes before it reads; and mesh and
skin names are what a rig mapper matches on, so an avatar that will not drive the
shared clip library is diagnosed here first.
validate-glb.mjs: Khronos glTF-Validator over a file, a directory, or a URL
node scripts/validate-glb.mjs public/avatars/default.glb
npm run validate:glb -- public/avatars/ # every model in a directory
npm run validate:glb -- --verbose model.glb # warnings and infos too
npm run validate:glb -- --json out/ > report.json
The PBR inspectors answer "what does this model carry"; this answers "is it
legal glTF at all", which is a different failure. A GLB can carry a complete
texture set and still be rejected by a strict viewer because a derived WebP map
was written without declaring EXT_texture_webp, an accessor's min/max
disagrees with its data, or a normalized attribute uses a component type the
spec forbids. Those show as a blank model in a third-party embed and as nothing
at all in our own forgiving viewer.
Errors print by default and warnings/infos behind --verbose. A .gltf with
external buffers resolves them relative to the file. Exit code is 1 when any
model reports a validation error, so it works as a gate on a pipeline that
writes GLBs.
derive-pbr-classes.mjs: run the PBR derive pass across every material class
node scripts/derive-pbr-classes.mjs model.glb
node scripts/derive-pbr-classes.mjs model.glb --classes=glass,person --out=/tmp/pbr
node scripts/derive-pbr-classes.mjs model.glb --json
api/_lib/glb-pbr-derive.js fills a model's
missing PBR channels from a material class: skin gets sheen and a pulled-down
specular, glass gets transmission and an IOR, car paint gets a clearcoat. The
class is normally picked from the generation prompt, which makes a change to the
class table or to the classifier easy to ship and hard to see. This runs one
input GLB through each class in turn and prints the table it applied next to
what the pass actually derived.
With --out each class writes <out>/<basename>.<class>.glb, ready to open in
the viewer or hand to inspect-glb-materials.mjs for the channel matrix.
set-r2-cors.mjs — apply the bucket CORS policy
Runs the canonical CORS policy against the R2 bucket holding all media
(avatars, thumbnails, posters). Required for browser reads (<model-viewer>,
<img>, fetch) and presigned uploads to work cross-origin.
node scripts/set-r2-cors.mjs --probe # measure the live policy from outside
node scripts/set-r2-cors.mjs --get # read the live policy (admin token only)
node scripts/set-r2-cors.mjs --dry-run # print the policy without pushing
node scripts/set-r2-cors.mjs # apply (admin token only)
Start with --probe. It measures what the bucket actually enforces using no
credentials at all: one HEAD per origin against the public host for the read
rule, one PUT preflight against the S3 endpoint for the write rule. It prints a
row per origin, marks any row where the measurement disagrees with the policy in
the script, and exits 1 on drift.
It finds both hosts by itself: the public host from a live listing endpoint, the
upload host from an auth-free presign route. When object storage is unhealthy
every presign route answers 503, so the write host cannot be discovered that
way. The probe still measures and reports the read rule in that case, showing
skip in the write column rather than exiting with nothing measured. To get the
write column back, pass the two non-secret values directly:
node scripts/set-r2-cors.mjs --probe \
--endpoint=https://<account>.r2.cloudflarestorage.com --bucket=<name>
Read them off the running service with
node scripts/read-service-env.mjs '^S3_ENDPOINT$' --raw. --get and the bare apply both call Get/PutBucketCors, which an
"Object Read & Write" token cannot do; they print the exact token to mint
instead of a stack trace.
Credentials come from .env / .env.local, or from the Cloud Run service for
production values (gcloud run services describe three-ws-api --region us-central1 --project aerial-vehicle-466722-p5 --format=yaml). Do not use
vercel env pull: it returns empty for secret-type vars, and production has
not run on Vercel since 2026-07-07. An admin token belongs in .env.local as
R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY.
Allowed origins are defined inline in the script: edit ALLOWED_ORIGINS when
you add a new domain (preview branch, staging host, etc.) and re-run.
Idempotent: re-running with the same policy is a no-op.
Run this any time you see No 'Access-Control-Allow-Origin' header errors
on assets served from *.r2.dev or your custom R2 domain. As of 2026-08-01
the live policy is an origin allowlist that predates the current script, so
--probe reports drift on www.three.ws, *.app.github.dev,
localhost:5173, and every third-party origin. Until an admin token applies
the fix, browser reads of bucket-hosted GLBs from an unlisted origin must go
through /api/glb.
mobile-perf.mjs: mobile field metrics under CPU + network throttling
npm run perf:mobile # top-15 preset vs production
npm run perf:mobile -- --pages /,/forge --runs 3
npm run perf:mobile -- --base http://localhost:3000 --net fast4g --cpu 2
npm run perf:mobile -- --json out.json --md out.md --label baseline
Drives each page in a real Playwright mobile context (default Pixel 5,
Chromium) with CDP throttling applied: Emulation.setCPUThrottlingRate (4x by
default) and Network.emulateNetworkConditions (default slow4g, the same
1.6 Mbps / 750 Kbps / 150 ms profile Lighthouse uses for its mobile preset).
It reads LCP, CLS, FCP, long-task blocking time, DOMContentLoaded, load, real
over-the-wire transfer bytes (CDP Network.loadingFinished.encodedDataLength),
request count, DOM size, and WebGL contexts created / still live / visible.
These are Playwright-measured field-style metrics, not Lighthouse scores.
Lighthouse is not a dependency of this repo. TBT* in the output is a long-task
blocking-time proxy, sum(max(0, longtask.duration - 50)), not Lighthouse's
simulated Total Blocking Time, and there is deliberately no blended
"performance score". Report the individual metrics, never a score.
Reports the median of --runs runs per page. Every run gets a fresh browser
context with service workers blocked, so transfer bytes are always cold-cache.
mobile-touch-audit.mjs: touch targets, gesture conflicts, safe areas
npm run audit:mobile-touch
npm run audit:mobile-touch -- --pages /marketplace --json out.json --md out.md
Loads each page in a Pixel 5 context and inspects the live computed DOM for the
four mobile ergonomics defects that matter: interactive elements whose rendered
box is under 44x44 CSS px (inline text links are exempt per WCAG 2.5.8 and
counted separately), visible canvases left at touch-action: auto where orbit
gestures fight page scroll, bottom-anchored fixed bars with no CSS rule
mentioning safe-area-inset plus whether the viewport meta opts into
viewport-fit=cover, and horizontal overflow at the mobile viewport width.
Every finding is a measured bounding box or a resolved computed style, never a source grep, so the output can be quoted directly as evidence.