@three-ws/avatar-agent 1.0.0

package/src/tools/inspect-glb.js

@@ -0,0 +1,219 @@
+// `inspect_glb` — fetch any GLB URL and return its full structural
+// breakdown: meshes, materials, textures, animations, file size, vertex
+// + triangle counts, bounding box, and skinning info.
+//
+// Pure parse via @gltf-transform/core. No network calls beyond the GLB
+// fetch itself.
+
+import { z } from 'zod';
+
+import { fetchGlbBytes, getIo } from '../lib/glb-io.js';
+
+function arrayLen(prim, semantic) {
+	const acc = prim.getAttribute(semantic);
+	return acc ? acc.getCount() : 0;
+}
+
+function primitiveTriangleCount(prim) {
+	const mode = prim.getMode();
+	const idx = prim.getIndices();
+	const count = idx ? idx.getCount() : arrayLen(prim, 'POSITION');
+	// glTF primitive modes: 0=POINTS, 1=LINES, 4=TRIANGLES, 5=TRIANGLE_STRIP, 6=TRIANGLE_FAN.
+	switch (mode) {
+		case 4:
+			return Math.floor(count / 3);
+		case 5:
+		case 6:
+			return Math.max(0, count - 2);
+		default:
+			return 0;
+	}
+}
+
+function computeWorldBbox(scene) {
+	let min = [Infinity, Infinity, Infinity];
+	let max = [-Infinity, -Infinity, -Infinity];
+	const visit = (node, mat = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]) => {
+		// Compose: world = parent * local. Keep mat as a 16-element column-major
+		// transform; we only need translate + axis-aligned vertex check so
+		// the full matrix multiplication suffices.
+		const t = node.getMatrix();
+		const world = mul(mat, t);
+		const mesh = node.getMesh();
+		if (mesh) {
+			for (const prim of mesh.listPrimitives()) {
+				const pos = prim.getAttribute('POSITION');
+				if (!pos) continue;
+				const arr = pos.getArray();
+				const stride = pos.getElementSize();
+				for (let i = 0; i < arr.length; i += stride) {
+					const v = transform([arr[i], arr[i + 1], arr[i + 2]], world);
+					if (v[0] < min[0]) min[0] = v[0];
+					if (v[1] < min[1]) min[1] = v[1];
+					if (v[2] < min[2]) min[2] = v[2];
+					if (v[0] > max[0]) max[0] = v[0];
+					if (v[1] > max[1]) max[1] = v[1];
+					if (v[2] > max[2]) max[2] = v[2];
+				}
+			}
+		}
+		for (const child of node.listChildren()) visit(child, world);
+	};
+	for (const root of scene.listChildren()) visit(root);
+	if (!Number.isFinite(min[0])) return null;
+	return {
+		min,
+		max,
+		center: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2],
+		size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
+	};
+}
+
+function mul(a, b) {
+	const r = new Array(16).fill(0);
+	for (let i = 0; i < 4; i++) {
+		for (let j = 0; j < 4; j++) {
+			let s = 0;
+			for (let k = 0; k < 4; k++) s += a[i + k * 4] * b[k + j * 4];
+			r[i + j * 4] = s;
+		}
+	}
+	return r;
+}
+
+function transform(v, m) {
+	return [
+		m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12],
+		m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13],
+		m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14],
+	];
+}
+
+export const def = {
+	name: 'inspect_glb',
+	title: 'Inspect a GLB / glTF 3D model',
+	description:
+		'Fetch any GLB URL (or data: URL) and return a full structural breakdown: meshes, primitives, materials, textures, animations, skins, vertex + triangle counts, world-space bounding box, and file size. Pure local parse via @gltf-transform/core — no third-party services.',
+	inputSchema: {
+		url: z.string().describe('Public URL or data: URL of a .glb file.'),
+	},
+	async handler(args) {
+		const { url } = args || {};
+		if (!url) return { ok: false, error: 'invalid_input', message: 'url is required' };
+		let bytes;
+		let doc;
+		try {
+			bytes = await fetchGlbBytes(url);
+			const io = await getIo();
+			doc = await io.readBinary(bytes);
+		} catch (err) {
+			return { ok: false, error: 'parse_failed', message: err.message };
+		}
+		const root = doc.getRoot();
+		const asset = root.getAsset();
+
+		let totalVertices = 0;
+		let totalTriangles = 0;
+		const meshes = root.listMeshes().map((mesh) => {
+			const prims = mesh.listPrimitives().map((p) => {
+				const v = arrayLen(p, 'POSITION');
+				const tri = primitiveTriangleCount(p);
+				totalVertices += v;
+				totalTriangles += tri;
+				return {
+					mode: p.getMode(),
+					vertices: v,
+					triangles: tri,
+					indexed: !!p.getIndices(),
+					attributes: p.listSemantics(),
+					material: p.getMaterial()?.getName() || null,
+					morphTargets: p.listTargets().length,
+				};
+			});
+			return {
+				name: mesh.getName() || null,
+				primitiveCount: prims.length,
+				primitives: prims,
+			};
+		});
+
+		const materials = root.listMaterials().map((m) => ({
+			name: m.getName() || null,
+			alphaMode: m.getAlphaMode(),
+			doubleSided: m.getDoubleSided(),
+			baseColorFactor: m.getBaseColorFactor(),
+			metallicFactor: m.getMetallicFactor(),
+			roughnessFactor: m.getRoughnessFactor(),
+			hasBaseColorTexture: !!m.getBaseColorTexture(),
+			hasMetallicRoughnessTexture: !!m.getMetallicRoughnessTexture(),
+			hasNormalTexture: !!m.getNormalTexture(),
+			hasOcclusionTexture: !!m.getOcclusionTexture(),
+			hasEmissiveTexture: !!m.getEmissiveTexture(),
+		}));
+
+		const textures = root.listTextures().map((t) => ({
+			name: t.getName() || null,
+			mimeType: t.getMimeType(),
+			sizeBytes: t.getImage()?.byteLength ?? null,
+			uri: t.getURI() || null,
+		}));
+
+		const animations = root.listAnimations().map((a) => {
+			let maxTime = 0;
+			for (const ch of a.listChannels()) {
+				const sampler = ch.getSampler();
+				const input = sampler?.getInput();
+				if (input) {
+					const arr = input.getArray();
+					const last = arr[arr.length - 1];
+					if (last > maxTime) maxTime = last;
+				}
+			}
+			return {
+				name: a.getName() || null,
+				channelCount: a.listChannels().length,
+				samplerCount: a.listSamplers().length,
+				durationSeconds: maxTime,
+			};
+		});
+
+		const skins = root.listSkins().map((s) => ({
+			name: s.getName() || null,
+			jointCount: s.listJoints().length,
+			hasInverseBindMatrices: !!s.getInverseBindMatrices(),
+		}));
+
+		const scenes = root.listScenes().map((s) => ({
+			name: s.getName() || null,
+			rootNodeCount: s.listChildren().length,
+		}));
+
+		const defaultScene = root.getDefaultScene() || root.listScenes()[0] || null;
+		const bbox = defaultScene ? computeWorldBbox(defaultScene) : null;
+
+		return {
+			ok: true,
+			url,
+			sizeBytes: bytes.byteLength,
+			generator: asset.generator || null,
+			version: asset.version || null,
+			counts: {
+				meshes: meshes.length,
+				materials: materials.length,
+				textures: textures.length,
+				animations: animations.length,
+				skins: skins.length,
+				scenes: scenes.length,
+				totalVertices,
+				totalTriangles,
+			},
+			boundingBox: bbox,
+			meshes,
+			materials,
+			textures,
+			animations,
+			skins,
+			scenes,
+		};
+	},
+};

package/src/tools/list-animations.js

@@ -0,0 +1,37 @@
+// `list_animations` — fetch the three.ws pose preset catalog (24 presets
+// across Standing, Action, Sitting & Floor, Expressive). Lives at
+// GET /api/render/avatar-clip on three.ws so the catalog stays
+// authoritative even when this MCP version is older than the live one.
+
+import { THREE_WS_BASE } from '../config.js';
+import { fetchPoseCatalogRemote } from '../lib/render.js';
+
+export const def = {
+	name: 'list_animations',
+	title: 'List three.ws pose presets + animation slots',
+	description:
+		'Return the three.ws pose preset catalog (T-pose, A-pose, wave, thinker, jump, dance, warrior2, …) grouped by category. Use the ids returned here as posePresetId in render_avatar. Fetched live from three.ws so the catalog reflects the deployed version.',
+	inputSchema: {},
+	async handler() {
+		try {
+			const catalog = await fetchPoseCatalogRemote();
+			const grouped = {};
+			for (const p of catalog.poses || []) {
+				const key = p.group || 'Other';
+				if (!grouped[key]) grouped[key] = [];
+				grouped[key].push({ id: p.id, label: p.label });
+			}
+			return {
+				ok: true,
+				source: `${THREE_WS_BASE}/api/render/avatar-clip`,
+				poseCount: (catalog.poses || []).length,
+				groups: Object.keys(grouped).map((g) => ({ group: g, poses: grouped[g] })),
+				cameraOrbit: catalog.cameraOrbit,
+				background: catalog.background,
+				fetchedAt: new Date().toISOString(),
+			};
+		} catch (err) {
+			return { ok: false, error: 'fetch_failed', message: err.message };
+		}
+	},
+};

package/src/tools/list-avatars.js

@@ -0,0 +1,20 @@
+// `list_avatars` — enumerate the curated default avatars + accessories +
+// pose presets shipped by three.ws. Free, no signer needed.
+
+import { ACCESSORIES, DEFAULT_AVATARS, POSE_PRESETS } from '../lib/avatars.js';
+
+export const def = {
+	name: 'list_avatars',
+	title: 'List three.ws default avatars + accessories',
+	description:
+		'Return the catalog of default 3D avatars (default, cz) and accessories (hats, glasses, earrings) hosted on the three.ws CDN. Each entry includes a public GLB URL ready to load in any glTF viewer or Three.js scene. Includes the supported pose preset names.',
+	inputSchema: {},
+	async handler() {
+		return {
+			avatars: DEFAULT_AVATARS,
+			accessories: ACCESSORIES,
+			poses: POSE_PRESETS,
+			fetchedAt: new Date().toISOString(),
+		};
+	},
+};

package/src/tools/optimize-glb.js

@@ -0,0 +1,114 @@
+// `optimize_glb` — shrink a GLB by running a configurable
+// @gltf-transform/functions pipeline: dedup → prune → join → weld
+// → Draco mesh compression. Returns the optimized bytes as a base64
+// data URL plus before/after byte counts so callers see the saving.
+//
+// Texture re-encoding (PNG → WebP/AVIF) is intentionally off by default
+// because it requires Sharp's native binaries; flip `reencodeTextures`
+// when running in an env where Sharp is available.
+
+import { z } from 'zod';
+import { dedup, draco, prune, weld } from '@gltf-transform/functions';
+
+import { fetchGlbBytes, getIo } from '../lib/glb-io.js';
+
+const MAX_RETURN_BYTES = 20 * 1024 * 1024;
+
+export const def = {
+	name: 'optimize_glb',
+	title: 'Optimize a GLB (dedup, prune, weld, Draco)',
+	description:
+		'Run a @gltf-transform/functions optimization pipeline on a GLB URL: dedup → prune unused → weld duplicate vertices → optional Draco mesh compression. Returns the optimized bytes as a base64 data URL with before/after sizes. Lossless for geometry except where Draco quantization is requested.',
+	inputSchema: {
+		url: z.string().describe('Source GLB URL (or data: URL).'),
+		dedup: z.boolean().optional().describe('Merge equivalent accessors / materials / textures. Default true.'),
+		prune: z.boolean().optional().describe('Remove unused materials / nodes / meshes. Default true.'),
+		weld: z.boolean().optional().describe('Merge duplicate vertices. Default true.'),
+		draco: z.boolean().optional().describe('Apply Draco mesh compression (lossy quantization). Default false.'),
+		dracoQuantizePosition: z.number().int().min(1).max(16).optional()
+			.describe('Position bits for Draco (default 14 = high fidelity).'),
+		returnInline: z.boolean().optional()
+			.describe('Return the optimized GLB inline as a base64 data URL (default true). Set false to return only stats.'),
+	},
+	async handler(args) {
+		const { url } = args || {};
+		if (!url) return { ok: false, error: 'invalid_input', message: 'url is required' };
+		const wantDedup = args.dedup !== false;
+		const wantPrune = args.prune !== false;
+		const wantWeld = args.weld !== false;
+		const wantDraco = !!args.draco;
+		const inline = args.returnInline !== false;
+
+		let srcBytes;
+		try {
+			srcBytes = await fetchGlbBytes(url);
+		} catch (err) {
+			return { ok: false, error: 'fetch_failed', message: err.message };
+		}
+
+		let doc;
+		const io = await getIo();
+		try {
+			doc = await io.readBinary(srcBytes);
+		} catch (err) {
+			return { ok: false, error: 'parse_failed', message: err.message };
+		}
+
+		const applied = [];
+		try {
+			if (wantDedup) {
+				await doc.transform(dedup());
+				applied.push('dedup');
+			}
+			if (wantPrune) {
+				await doc.transform(prune());
+				applied.push('prune');
+			}
+			if (wantWeld) {
+				await doc.transform(weld());
+				applied.push('weld');
+			}
+			if (wantDraco) {
+				const opts = {};
+				if (typeof args.dracoQuantizePosition === 'number') {
+					opts.quantizePosition = args.dracoQuantizePosition;
+				}
+				await doc.transform(draco(opts));
+				applied.push('draco');
+			}
+		} catch (err) {
+			return { ok: false, error: 'transform_failed', message: err.message, applied };
+		}
+
+		let outBytes;
+		try {
+			outBytes = await io.writeBinary(doc);
+		} catch (err) {
+			return { ok: false, error: 'write_failed', message: err.message, applied };
+		}
+
+		const before = srcBytes.byteLength;
+		const after = outBytes.byteLength;
+		const ratio = before > 0 ? after / before : 1;
+		const result = {
+			ok: true,
+			url,
+			pipeline: applied,
+			beforeBytes: before,
+			afterBytes: after,
+			savedBytes: before - after,
+			ratio,
+			reductionPct: (1 - ratio) * 100,
+		};
+		if (inline) {
+			if (after > MAX_RETURN_BYTES) {
+				result.optimizedGlb = null;
+				result.note = `Optimized GLB is ${after} bytes (> ${MAX_RETURN_BYTES} inline cap). Re-run with smaller input or use a hosting endpoint.`;
+			} else {
+				const b64 = Buffer.from(outBytes).toString('base64');
+				result.optimizedGlb = `data:model/gltf-binary;base64,${b64}`;
+			}
+		}
+		return result;
+	},
+};

package/src/tools/pump-buy.js

@@ -0,0 +1,69 @@
+// `pump_buy` — buy any Solana SPL or pump.fun token via Jupiter.
+//
+// Two modes:
+//   - direct (default): the buyer wallet pays its own fee + spends SOL.
+//   - bundled (set jitoBundle=true with a funderSecret): two-tx Jito
+//     bundle where the funder transfers SOL to the buyer + Jito tip in
+//     Tx1 and the buyer signs the swap in Tx2. Use this if the buyer
+//     wallet is shared/leaked and you must beat sweeper bots.
+//
+// EXECUTION ACTION — real swaps on Solana mainnet.
+
+import { z } from 'zod';
+
+import { isValidPubkey } from '../lib/solana.js';
+import { jupiterBuyBundled, jupiterBuyDirect } from '../lib/jupiter-buy.js';
+import { THREE_MINT } from '../config.js';
+
+export const def = {
+	name: 'pump_buy',
+	title: 'Buy a Solana token via Jupiter (direct or Jito-bundled)',
+	description:
+		'Swap SOL → target mint via Jupiter aggregator. Direct mode = one tx signed by the buyer. Bundled mode (jitoBundle=true) = two-tx Jito bundle where funderSecret transfers SOL + tip to the buyer atomically with the swap (sweeper-resistant). Pass target="three" to use the $three reference mint. EXECUTION ACTION.',
+	inputSchema: {
+		target: z.string().describe('Target mint (base58) or "three" to use the THREE_MINT env.'),
+		buySol: z.number().positive().describe('Amount of SOL to spend.'),
+		buyerSecret: z.string().describe('Base58 secret of the buyer wallet (signs the swap).'),
+		funderSecret: z.string().optional().describe('Base58 secret of the funder. Required when jitoBundle=true.'),
+		jitoBundle: z.boolean().optional().describe('Use a Jito bundle (atomic funder→buyer transfer + swap). Default false.'),
+		slippageBps: z.number().int().min(1).max(10_000).optional().describe('Slippage in basis points (default 500 = 5%).'),
+		jitoTipSol: z.number().min(0).optional().describe('Jito tip in SOL (default 0.005). Only used when jitoBundle=true.'),
+		priorityMicroLamports: z.number().int().min(0).max(20_000_000).optional()
+			.describe('Compute-unit price (default 2_000_000).'),
+	},
+	async handler(args) {
+		let target = args.target;
+		if (target === 'three' || target === '$three') {
+			if (!THREE_MINT) return { ok: false, error: 'three_mint_not_configured' };
+			target = THREE_MINT;
+		}
+		if (!isValidPubkey(target)) return { ok: false, error: 'invalid_target' };
+		try {
+			if (args.jitoBundle) {
+				if (!args.funderSecret) {
+					return { ok: false, error: 'invalid_input', message: 'jitoBundle=true requires funderSecret.' };
+				}
+				const out = await jupiterBuyBundled({
+					funderSecret: args.funderSecret,
+					buyerSecret: args.buyerSecret,
+					targetMint: target,
+					buySol: args.buySol,
+					slippageBps: args.slippageBps,
+					jitoTipSol: args.jitoTipSol,
+					priorityMicroLamports: args.priorityMicroLamports,
+				});
+				return out;
+			}
+			const out = await jupiterBuyDirect({
+				buyerSecret: args.buyerSecret,
+				targetMint: target,
+				buySol: args.buySol,
+				slippageBps: args.slippageBps,
+				priorityMicroLamports: args.priorityMicroLamports,
+			});
+			return out;
+		} catch (err) {
+			return { ok: false, error: err.code || 'buy_failed', message: err.message };
+		}
+	},
+};

package/src/tools/pump-collect.js

@@ -0,0 +1,48 @@
+// `pump_collect_fees` — atomically collect a pump.fun coin's creator-fee
+// vault and route the SOL to a safe destination, all in a single tx
+// inside a Jito bundle.
+//
+// Useful when the creator key is shared or potentially leaked: even if
+// another holder of the key tries to collect concurrently, the bundle's
+// atomicity prevents any tx from interleaving between the collect and
+// the drain.
+//
+// EXECUTION ACTION.
+
+import { z } from 'zod';
+
+import { atomicCollect } from '../lib/atomic-collect.js';
+
+export const def = {
+	name: 'pump_collect_fees',
+	title: 'Atomic pump.fun creator-fee collection (Jito bundle)',
+	description:
+		'Collect a pump.fun coin\'s creator-fee vault and route the SOL to a safe destination, atomically, in a single tx inside a Jito bundle. Funder pays the fee + Jito tip; creator signs collectCoinCreatorFee + drain to DESTINATION. The bundle\'s atomicity blocks any competing collector from interleaving even if the creator key is leaked. EXECUTION ACTION.',
+	inputSchema: {
+		funderSecret: z.string().describe('Base58 secret of the funder (pays fee + tip).'),
+		creatorSecret: z.string().describe('Base58 secret of the coin creator (signs collect + drain).'),
+		destination: z.string().describe('Pubkey to receive the collected SOL.'),
+		jitoTipSol: z.number().min(0).optional().describe('Jito tip in SOL (default 0.005).'),
+		priorityMicroLamports: z.number().int().min(0).max(20_000_000).optional()
+			.describe('Compute-unit priority price (default 3_000_000).'),
+		bufferLamports: z.number().int().min(0).optional()
+			.describe('Lamports to leave in the creator wallet (default 890880, rent-exempt minimum).'),
+		minVaultSol: z.number().min(0).optional()
+			.describe('Abort if the vault holds less than this (default 0.001).'),
+	},
+	async handler(args) {
+		try {
+			return await atomicCollect({
+				funderSecret: args.funderSecret,
+				creatorSecret: args.creatorSecret,
+				destination: args.destination,
+				jitoTipSol: args.jitoTipSol,
+				priorityMicroLamports: args.priorityMicroLamports,
+				bufferLamports: args.bufferLamports,
+				minVaultSol: args.minVaultSol,
+			});
+		} catch (err) {
+			return { ok: false, error: err.code || 'collect_failed', message: err.message };
+		}
+	},
+};

package/src/tools/pump-launch.js

@@ -0,0 +1,77 @@
+// `pump_launch` — atomic pump.fun token launch via a Jito bundle.
+//
+// Wraps the atomic-launch port (originally from nirholas/atomic). Two-tx
+// bundle: funder pays its own fee + the Jito tip and rent-funds the
+// creator; creator signs createV2 in tx2. Either both land or neither
+// does, so the on-chain `creator` is the creator wallet (not the funder)
+// without forcing the creator to hold SOL up front.
+//
+// If `uri` is omitted, we upload metadata to pump.fun's IPFS endpoint
+// first using the supplied name/symbol/description/socials/imageUrl. This
+// makes the tool a one-shot "launch from scratch".
+//
+// EXECUTION ACTION — creates a real mint on Solana mainnet and pays
+// Jito tips + rent.
+
+import { z } from 'zod';
+
+import { atomicLaunch, uploadPumpMetadata } from '../lib/atomic-launch.js';
+
+export const def = {
+	name: 'pump_launch',
+	title: 'Atomic pump.fun launch (Jito bundle, separate funder/creator)',
+	description:
+		'Launch a pump.fun token atomically via a Jito bundle. Funder pays its own fee + tip and rent-funds the creator; creator signs createV2 in tx2 — both txs land in the same block or neither does. If uri is omitted, metadata is uploaded to pump.fun IPFS first from name/symbol/description/socials/imageUrl. Returns the mint address, bundle id, both tx signatures, and the pump.fun URL. EXECUTION ACTION — creates a real mint on mainnet.',
+	inputSchema: {
+		name: z.string().min(1).max(32).describe('Token name.'),
+		symbol: z.string().min(1).max(10).describe('Token symbol (ticker).'),
+		funderSecret: z.string().describe('Base58 secret of the funder wallet (pays Tx1 fee + tip + rent transfer).'),
+		creatorSecret: z.string().describe('Base58 secret of the creator wallet (signs createV2 — becomes on-chain creator).'),
+		uri: z.string().url().optional().describe('Existing metadata URI. If omitted, metadata is uploaded first.'),
+		description: z.string().max(500).optional(),
+		twitter: z.string().optional(),
+		telegram: z.string().optional(),
+		website: z.string().optional(),
+		imageUrl: z.string().url().optional().describe('Image to upload as the token icon (re-fetched at upload time).'),
+		mintSecret: z.string().optional().describe('Base58 secret to use as the mint keypair (default: random).'),
+		rentSol: z.number().min(0).optional().describe('SOL the funder transfers to the creator for tx2 rent + fees (default 0.035).'),
+		jitoTipSol: z.number().min(0).optional().describe('Jito tip in SOL (default 0.005).'),
+		priorityMicroLamports: z.number().int().min(0).max(20_000_000).optional()
+			.describe('Compute-unit priority price (default 2_000_000).'),
+	},
+	async handler(args) {
+		try {
+			let uri = args.uri;
+			let uploadedMeta = null;
+			if (!uri) {
+				uploadedMeta = await uploadPumpMetadata({
+					name: args.name,
+					symbol: args.symbol,
+					description: args.description || '',
+					twitter: args.twitter || '',
+					telegram: args.telegram || '',
+					website: args.website || '',
+					imageUrl: args.imageUrl,
+				});
+				uri = uploadedMeta.uri;
+				if (!uri) {
+					return { ok: false, error: 'metadata_upload_failed', detail: uploadedMeta.raw };
+				}
+			}
+			const out = await atomicLaunch({
+				name: args.name,
+				symbol: args.symbol,
+				uri,
+				funderSecret: args.funderSecret,
+				creatorSecret: args.creatorSecret,
+				mintSecret: args.mintSecret,
+				rentSol: args.rentSol,
+				jitoTipSol: args.jitoTipSol,
+				priorityMicroLamports: args.priorityMicroLamports,
+			});
+			return { ...out, metadataUri: uri, metadataUploadedNow: !!uploadedMeta };
+		} catch (err) {
+			return { ok: false, error: err.code || 'launch_failed', message: err.message };
+		}
+	},
+};

package/src/tools/pump-snapshot.js

@@ -0,0 +1,38 @@
+// `pump_snapshot` — live market snapshot for a Solana SPL or pump.fun
+// token. Free, read-only. Aggregates Jupiter price, Dexscreener volume,
+// pump.fun metadata, top holders from Solana RPC, and (optionally)
+// Helius DAS supply info when HELIUS_API_KEY is set.
+
+import { z } from 'zod';
+
+import { snapshot } from '../lib/pumpfun.js';
+import { isValidPubkey } from '../lib/solana.js';
+import { THREE_MINT } from '../config.js';
+
+export const def = {
+	name: 'pump_snapshot',
+	title: 'Live pump.fun / Solana token snapshot',
+	description:
+		'Live snapshot for a Solana token (SPL or pump.fun): USD price (Jupiter), 24h volume + primary DEX (Dexscreener), pump.fun metadata (name/symbol/image/socials/mcap), and top-holder distribution from Solana RPC. Optional Helius DAS supply when HELIUS_API_KEY is configured. Free — no signer.',
+	inputSchema: {
+		token: z.string().min(32).max(64).describe('Base58 Solana mint address. Pass "three" or omit to use the $three reference mint (THREE_MINT env).').optional(),
+	},
+	async handler(args) {
+		let mint = args?.token;
+		if (!mint || mint === 'three' || mint === '$three') {
+			if (!THREE_MINT) {
+				return {
+					ok: false,
+					error: 'three_mint_not_configured',
+					message: 'No token argument and THREE_MINT env is unset. Pass token=<mint> or set THREE_MINT.',
+				};
+			}
+			mint = THREE_MINT;
+		}
+		if (!isValidPubkey(mint)) {
+			return { ok: false, error: 'invalid_mint', token: mint };
+		}
+		const result = await snapshot(mint);
+		return { ok: true, ...result };
+	},
+};

package/src/tools/render-avatar.js

@@ -0,0 +1,60 @@
+// `render_avatar` — full posed avatar render with three.ws's render-clip
+// pipeline: applies a pose preset's Euler-rotation map to the rig, sets
+// the camera orbit (theta/phi/radius), optionally applies ARKit-52 morph
+// targets for facial expression, and returns the PNG.
+//
+// Mirrors the experience of the three.ws customizer: same rig conventions
+// (Avaturn), same pose library (PRESETS in /src/pose-presets.js), same
+// lighting (three-light rig with ACES tone mapping). Works on any GLB
+// that follows the standard rig — both curated defaults and uploaded
+// avatars.
+
+import { z } from 'zod';
+
+import { renderAvatarClipRemote } from '../lib/render.js';
+import { getSession } from '../lib/avatars.js';
+
+export const def = {
+	name: 'render_avatar',
+	title: 'Render a posed avatar (pose + camera + expression)',
+	description:
+		'Render an avatar GLB with a three.ws pose preset, camera orbit, and optional ARKit-52 facial expression. Same pipeline as the three.ws customizer\'s save-snapshot flow. Returns PNG bytes as a base64 data URL. Accepts either glbUrl directly or sessionId from spawn_avatar.',
+	inputSchema: {
+		glbUrl: z.string().url().optional().describe('Avatar GLB URL. Required if sessionId is omitted.'),
+		sessionId: z.string().optional().describe('Avatar session id from spawn_avatar. Overrides glbUrl.'),
+		posePresetId: z.string().optional()
+			.describe('Pose preset id (e.g. "tpose", "wave", "thinker"). Call list_animations for the full catalog.'),
+		cameraOrbit: z.object({
+			theta: z.number().optional().describe('Yaw in degrees, 0..360. Default 0 (front).'),
+			phi: z.number().optional().describe('Pitch in degrees, 0..180 (from top). Default 80 (slightly above eye-level).'),
+			radius: z.number().nullable().optional().describe('Distance in meters. null = auto-frame the bounding box.'),
+		}).optional().describe('Camera orbit around the avatar.'),
+		expression: z.record(z.number()).optional()
+			.describe('ARKit-52 morph target map, e.g. { mouthSmileLeft: 0.6, mouthSmileRight: 0.6 }.'),
+		width: z.number().int().min(64).max(2048).optional().describe('Output width (default 1024).'),
+		height: z.number().int().min(64).max(2048).optional().describe('Output height (default 1024).'),
+		background: z.string().optional().describe('CSS color or "transparent". Default "#0a0a0a".'),
+	},
+	async handler(args) {
+		const { sessionId, glbUrl, posePresetId, cameraOrbit, expression, width, height, background } = args || {};
+		let resolvedGlb = glbUrl;
+		let sessionPose = null;
+		if (sessionId) {
+			const session = getSession(sessionId);
+			if (!session) return { ok: false, error: 'unknown_session', message: `No session ${sessionId}.` };
+			resolvedGlb = session.avatar.glb;
+			sessionPose = session.pose && session.pose !== 'idle' ? session.pose : null;
+		}
+		if (!resolvedGlb) return { ok: false, error: 'invalid_input', message: 'Pass glbUrl or sessionId.' };
+		const out = await renderAvatarClipRemote({
+			glbUrl: resolvedGlb,
+			posePresetId: posePresetId || sessionPose || null,
+			cameraOrbit,
+			expression,
+			width,
+			height,
+			background,
+		});
+		return { ...out, glbUrl: resolvedGlb, sessionId: sessionId || null };
+	},
+};