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.

10.4 KB
Raw Blame
// three.ws agent-registry read client used by the commerce discovery tool.
//
// Reads the live public agent directory (GET /api/agents/public) — real agents,
// real skills, real engagement counts — and exposes a ranking helper that folds
// task/skill fit, engagement, and (when present) on-chain ERC-8004 reputation
// into a single fitness score. No mock data: every candidate comes from the
// live directory; reputation is read straight from the canonical registries.

import { resilientFetch } from './resilient-fetch.js';
import { makeEvmProvider } from './evm-rpc.js';
import { readReputationAggregate, resolveChain } from './erc8004.js';

function baseUrl() {
	const v = process.env.THREEWS_BASE_URL;
	return v && v.trim() ? v.trim().replace(/\/+$/, '') : 'https://three.ws';
}

/**
 * Fetch candidate agents from the live three.ws public directory.
 *
 * The directory's full-text `q` is a strict pre-filter — a natural-language task
 * sentence ("help me run a pump.fun token launch") routinely matches nothing even
 * when the individual agents are perfectly relevant. So when a `q`-filtered query
 * comes back empty we broaden: retry without `q` and hand the reputation/
 * engagement-ranked pool to the client-side relevance scorer (rankCandidates),
 * which orders it by task-token overlap anyway. Discovery therefore never
 * dead-ends on phrasing — it degrades to "the best agents we have" rather than an
 * empty shortlist. When the directory grows, the `q` pre-filter still does the
 * heavy lifting on the happy path.
 *
 * @param {object} opts
 * @param {string} [opts.q]      — full-text query (task keywords)
 * @param {string} [opts.skill]  — skill-slug filter
 * @param {number} [opts.limit]  — max rows (clamped 1..48)
 * @returns {Promise<object[]>} raw agent rows from /api/agents/public
 */
export async function fetchCandidates({ q, skill, limit = 24 } = {}) {
	const rows = await fetchDirectory({ q, skill, limit });
	// A skill filter is an explicit, honored constraint — never widen past it.
	// A `q` that filtered everything out is just phrasing noise: broaden it away.
	if (rows.length === 0 && q) {
		return fetchDirectory({ skill, limit });
	}
	return rows;
}

async function fetchDirectory({ q, skill, limit = 24 } = {}) {
	const url = new URL(`${baseUrl()}/api/agents/public`);
	if (q) url.searchParams.set('q', String(q).slice(0, 100));
	if (skill) url.searchParams.set('skill', String(skill).toLowerCase());
	url.searchParams.set('limit', String(Math.min(48, Math.max(1, limit))));
	url.searchParams.set('sort', 'popular');

	const res = await resilientFetch(
		url.toString(),
		{ headers: { accept: 'application/json' } },
		{ timeoutMs: 12_000, retries: 2, label: 'agent-registry' },
	);
	if (!res.ok) {
		throw new Error(`agent directory returned ${res.status}`);
	}
	const data = await res.json().catch(() => null);
	const agents = Array.isArray(data?.agents) ? data.agents : [];
	return agents;
}

/**
 * Fetch one agent's public record by id, returning the fields the commerce
 * tools need (name, on-chain identity for reputation, skills for task-fit).
 * Returns null when the agent does not exist or the directory is unreachable —
 * the caller decides whether a missing record is fatal.
 *
 * @param {string} agentId — three.ws agent UUID
 * @returns {Promise<{id:string,name:string,description:string|null,skills:string[],erc8004_agent_id:string|null,chain_id:number|null,is_registered:boolean}|null>}
 */
export async function fetchAgentById(agentId) {
	const url = `${baseUrl()}/api/agents/${encodeURIComponent(agentId)}`;
	let res;
	try {
		res = await resilientFetch(
			url,
			{ headers: { accept: 'application/json' } },
			{ timeoutMs: 10_000, retries: 2, label: 'agent-by-id' },
		);
	} catch {
		return null;
	}
	if (!res.ok) return null;
	const data = await res.json().catch(() => null);
	const a = data?.agent;
	if (!a || !a.id) return null;
	return {
		id: a.id,
		name: a.name || null,
		description: a.description || null,
		skills: Array.isArray(a.skills) ? a.skills : [],
		erc8004_agent_id:
			a.erc8004_agent_id != null && String(a.erc8004_agent_id).trim() !== ''
				? String(a.erc8004_agent_id)
				: null,
		chain_id: a.chain_id ?? null,
		is_registered: !!a.is_registered,
	};
}

// Token-overlap relevance between the task text and an agent's name + skills +
// description. Cheap, deterministic, and good enough to order a shortlist; the
// registry's full-text search already did the heavy filtering.
export function relevanceScore(task, agent) {
	const taskTokens = tokenize(task);
	if (taskTokens.size === 0) return 0;
	const hay = tokenize(
		[agent.name, agent.description, ...(Array.isArray(agent.skills) ? agent.skills : [])]
			.filter(Boolean)
			.join(' '),
	);
	if (hay.size === 0) return 0;
	let hits = 0;
	for (const t of taskTokens) if (hay.has(t)) hits += 1;
	return hits / taskTokens.size;
}

function tokenize(s) {
	return new Set(
		String(s || '')
			.toLowerCase()
			.split(/[^a-z0-9]+/)
			.filter((w) => w.length > 2),
	);
}

// Squash an unbounded engagement count into 0..1 so it can't dominate the
// composite score. log10 keeps a 10× busier agent meaningfully — but not
// linearly — ahead.
function engagementScore(chatCount) {
	const n = Number(chatCount) || 0;
	if (n <= 0) return 0;
	return Math.min(1, Math.log10(n + 1) / 4); // ~10k chats → 1.0
}

/**
 * Read live ERC-8004 reputation for one agent that exposes an on-chain identity.
 * Returns null when the agent has no erc8004 id or the read fails (reputation is
 * enrichment — a single RPC blip must never sink the whole discovery call).
 *
 * @param {object} agent — directory row (may carry erc8004_agent_id + chain_id)
 * @returns {Promise<{average:number|null, count:number, source:string, chain:string, erc8004AgentId:string}|null>}
 */
export async function readAgentReputation(agent) {
	const erc8004Id = agent?.erc8004_agent_id;
	if (erc8004Id == null || String(erc8004Id).trim() === '') return null;
	let chain;
	try {
		chain = resolveChain(agent.chain_id ?? agent.chainId ?? undefined);
	} catch {
		chain = resolveChain(undefined);
	}
	try {
		const overrides = [process.env[`MCP_AGENT_REP_RPC_${chain.id}`]].filter(Boolean);
		const provider = makeEvmProvider(chain.id, { overrides, timeoutMs: 8_000 });
		const agg = await readReputationAggregate(provider, BigInt(String(erc8004Id)));
		return {
			average: agg.average,
			count: Number(agg.count) || 0,
			averageX100: agg.averageX100,
			totalStakeWei: agg.totalStakeWei,
			source: 'erc8004',
			chain: chain.name,
			chainId: chain.id,
			erc8004AgentId: String(erc8004Id),
		};
	} catch {
		return null;
	}
}

// Map an ERC-8004 average (the registry scores feedback −100..+100, stored ÷100
// so the average lands in roughly −1..+1 for normalized feedback, but can range
// wider) into a 0..1 reputation factor for the composite. Unrated agents get a
// neutral baseline so they're not auto-buried — discovery still surfaces them,
// just below comparably-fit rated peers.
function reputationFactor(reputation) {
	if (!reputation || reputation.average == null || reputation.count <= 0) return 0.5;
	// Clamp the average into [-1, 1] then shift to [0, 1].
	const clamped = Math.max(-1, Math.min(1, reputation.average));
	return (clamped + 1) / 2;
}

/**
 * Rank candidate agents for a task, enriching each with live reputation, and
 * return a sorted shortlist with the evidence behind each score.
 *
 * Composite weighting (sums to 1): relevance .45, reputation .35, engagement .20.
 * Reputation is read in parallel and bounded; failures degrade to a neutral
 * factor rather than dropping the candidate.
 *
 * @param {object} opts
 * @param {string} opts.task
 * @param {object[]} opts.candidates  — rows from fetchCandidates()
 * @param {number} [opts.limit=5]
 * @param {number} [opts.minReputation]  — drop rated agents below this average
 * @returns {Promise<object[]>}
 */
export async function rankCandidates({ task, candidates, limit = 5, minReputation } = {}) {
	const rows = Array.isArray(candidates) ? candidates : [];

	// Read reputation for every candidate concurrently (bounded inside
	// readAgentReputation). Promise.all is safe — each resolves to a value or
	// null, never rejects.
	const reputations = await Promise.all(rows.map((a) => readAgentReputation(a)));

	const scored = rows.map((agent, i) => {
		const reputation = reputations[i];
		const relevance = relevanceScore(task, agent);
		const engagement = engagementScore(agent.chat_count);
		const repFactor = reputationFactor(reputation);
		const score = 0.45 * relevance + 0.35 * repFactor + 0.2 * engagement;
		return {
			agentId: agent.id,
			name: agent.name,
			description: agent.description || null,
			skills: Array.isArray(agent.skills) ? agent.skills : [],
			homeUrl: agent.home_url || null,
			avatarThumbnail: agent.avatar_thumbnail || null,
			isRegistered: !!agent.is_registered,
			reputation: reputation
				? {
						average: reputation.average,
						count: reputation.count,
						source: reputation.source,
						chain: reputation.chain,
						erc8004AgentId: reputation.erc8004AgentId,
				  }
				: null,
			capabilityMatch: Math.round(relevance * 100) / 100,
			engagement: { chatCount: Number(agent.chat_count) || 0, score: Math.round(engagement * 100) / 100 },
			score: Math.round(score * 1000) / 1000,
			evidence: buildEvidence({ relevance, reputation, engagement, agent }),
		};
	});

	const gated =
		Number.isFinite(minReputation) && minReputation != null
			? scored.filter(
					(c) =>
						// Keep unrated agents (no on-chain rep to gate on) and rated
						// agents that clear the floor.
						c.reputation == null ||
						c.reputation.average == null ||
						c.reputation.average >= minReputation,
			  )
			: scored;

	gated.sort((a, b) => b.score - a.score);
	return gated.slice(0, Math.max(1, Math.min(10, limit)));
}

function buildEvidence({ relevance, reputation, engagement, agent }) {
	const parts = [];
	if (reputation && reputation.average != null && reputation.count > 0) {
		parts.push(
			`ERC-8004 reputation ${reputation.average.toFixed(2)} across ${reputation.count} vouch(es) on ${reputation.chain}`,
		);
	} else if (reputation) {
		parts.push(`on-chain ERC-8004 identity #${reputation.erc8004AgentId} (no vouches yet)`);
	} else {
		parts.push('no on-chain reputation record');
	}
	parts.push(`task fit ${(relevance * 100).toFixed(0)}%`);
	const chats = Number(agent.chat_count) || 0;
	if (chats > 0) parts.push(`${chats.toLocaleString('en-US')} chats served`);
	return parts.join(' · ');
}