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.

13.2 KB
Raw Blame
// Pure transforms for consent-gated Farcaster memory seeding.
//
// Everything here is deterministic and network-free so the seeding pipeline can
// be tested without a hub, an indexer, or a database:
//   * the consent message a user signs with their wallet (build + parse),
//   * normalisation of the two upstream shapes (hub protobuf-JSON, Neynar),
//   * selection of which casts are worth remembering,
//   * the memory rows written to agent_memories.
//
// The network lane lives in ./farcaster-client.js; the HTTP surface lives in
// api/agents/_id/memory-seed-farcaster.js.

// Farcaster message timestamps are seconds since 2021-01-01T00:00:00Z.
export const FARCASTER_EPOCH_MS = 1_609_459_200_000;

// Read-only, least privilege: we never ask for a Farcaster signer, never write
// a cast, and never touch anything that is not already public on the protocol.
export const CONSENT_SCOPE = 'farcaster:profile.read farcaster:casts.read';

export const CONSENT_TTL_MS = 10 * 60 * 1000;

export const MEMORY_SOURCE = 'farcaster_seed';

export const PROOF_CHAINS = ['solana', 'ethereum'];

const CONSENT_HEADER = 'three.ws memory seeding consent';

const CONSENT_BODY =
	'I authorize three.ws to read my public Farcaster profile and casts and store them as ' +
	'memory for the agent below. Revoking this grant deletes every memory seeded from it.';

// ── Consent message ─────────────────────────────────────────────────────────

/**
 * Build the exact text the user signs in their wallet. Deterministic: the
 * server rebuilds it from the challenge it stored and compares byte for byte,
 * so a tampered field (different agent, different fid) never verifies.
 */
export function buildConsentMessage({
	domain,
	agentId,
	fid,
	fname,
	address,
	chain,
	nonce,
	issuedAt,
	expiresAt,
	castLimit,
}) {
	if (!domain) throw new Error('domain required');
	if (!agentId) throw new Error('agentId required');
	if (!Number.isInteger(fid) || fid <= 0) throw new Error('fid required');
	if (!address) throw new Error('address required');
	if (!PROOF_CHAINS.includes(chain)) throw new Error(`unsupported chain: ${chain}`);
	if (!nonce) throw new Error('nonce required');

	return [
		`${domain} ${CONSENT_HEADER}`,
		'',
		CONSENT_BODY,
		'',
		`Agent: ${agentId}`,
		`Farcaster FID: ${fid}`,
		`Farcaster Name: ${fname || '(none)'}`,
		`Wallet: ${address}`,
		`Chain: ${chain}`,
		`Scope: ${CONSENT_SCOPE}`,
		`Casts: up to ${castLimit}`,
		`Nonce: ${nonce}`,
		`Issued At: ${issuedAt}`,
		`Expiration Time: ${expiresAt}`,
	].join('\n');
}

/** Parse a consent message back into fields. Returns null when malformed. */
export function parseConsentMessage(message) {
	if (typeof message !== 'string') return null;
	const lines = message.split('\n');
	const header = new RegExp(`^(\\S+) ${CONSENT_HEADER}$`).exec(lines[0] || '');
	if (!header) return null;

	const out = { domain: header[1] };
	const keys = {
		Agent: 'agentId',
		'Farcaster FID': 'fid',
		'Farcaster Name': 'fname',
		Wallet: 'address',
		Chain: 'chain',
		Scope: 'scope',
		Casts: 'castLimit',
		Nonce: 'nonce',
		'Issued At': 'issuedAt',
		'Expiration Time': 'expiresAt',
	};
	for (const line of lines.slice(1)) {
		const kv = /^([A-Za-z ]+):\s*(.*)$/.exec(line);
		if (!kv) continue;
		const field = keys[kv[1].trim()];
		if (field) out[field] = kv[2].trim();
	}

	if (!out.agentId || !out.fid || !out.address || !out.nonce) return null;
	out.fid = Number(out.fid);
	if (!Number.isInteger(out.fid) || out.fid <= 0) return null;
	if (out.fname === '(none)') out.fname = null;
	const castLimit = /(\d+)/.exec(out.castLimit || '');
	out.castLimit = castLimit ? Number(castLimit[1]) : null;
	return out;
}

// ── Address matching ────────────────────────────────────────────────────────

/**
 * Solana addresses are base58 and case significant; EVM addresses are hex and
 * are compared case-insensitively so a checksummed wallet still matches the
 * lowercase form the protocol stores.
 */
export function normalizeAddress(address, chain) {
	const raw = String(address ?? '').trim();
	if (!raw) return '';
	return chain === 'ethereum' ? raw.toLowerCase() : raw;
}

export function addressMatches(candidate, verified, chain) {
	const needle = normalizeAddress(candidate, chain);
	if (!needle) return false;
	return (verified || []).some((v) => normalizeAddress(v, chain) === needle);
}

// ── Upstream normalisation: hub protobuf-JSON ───────────────────────────────

const USER_DATA_FIELDS = {
	USER_DATA_TYPE_PFP: 'pfpUrl',
	USER_DATA_TYPE_DISPLAY: 'displayName',
	USER_DATA_TYPE_BIO: 'bio',
	USER_DATA_TYPE_URL: 'url',
	USER_DATA_TYPE_USERNAME: 'fname',
};

/** Fold a hub `/v1/userDataByFid` message list into a flat profile. */
export function normalizeHubUserData(messages) {
	const profile = { fname: null, displayName: null, bio: null, pfpUrl: null, url: null };
	for (const msg of messages || []) {
		const body = msg?.data?.userDataBody;
		const field = USER_DATA_FIELDS[body?.type];
		if (field && typeof body.value === 'string' && body.value) profile[field] = body.value;
	}
	return profile;
}

/**
 * Fold a hub `/v1/verificationsByFid` message list into the addresses the fid
 * has publicly proved control of, split by protocol. These are the only
 * wallets allowed to grant consent for this fid.
 */
export function normalizeVerifications(messages) {
	const out = { solana: [], ethereum: [] };
	for (const msg of messages || []) {
		const body = msg?.data?.verificationAddAddressBody;
		const address = body?.address;
		if (!address) continue;
		const chain = body.protocol === 'PROTOCOL_SOLANA' ? 'solana' : 'ethereum';
		const normalized = normalizeAddress(address, chain);
		if (normalized && !out[chain].includes(normalized)) out[chain].push(normalized);
	}
	return out;
}

/** Fold a hub `/v1/castsByFid` message list into normalized casts. */
export function normalizeHubCasts(messages) {
	const casts = [];
	for (const msg of messages || []) {
		const data = msg?.data;
		if (data?.type !== 'MESSAGE_TYPE_CAST_ADD') continue;
		const body = data.castAddBody;
		if (!body) continue;
		casts.push({
			hash: msg.hash || null,
			text: typeof body.text === 'string' ? body.text : '',
			timestamp: farcasterTimeToMs(data.timestamp),
			isReply: Boolean(body.parentCastId || body.parentUrl),
			engagement: null,
		});
	}
	return casts;
}

export function farcasterTimeToMs(seconds) {
	const n = Number(seconds);
	if (!Number.isFinite(n)) return null;
	return FARCASTER_EPOCH_MS + n * 1000;
}

// ── Upstream normalisation: Neynar ──────────────────────────────────────────

/** Fold Neynar's indexed cast objects into the same shape as the hub lane. */
export function normalizeNeynarCasts(casts) {
	const out = [];
	for (const cast of casts || []) {
		const likes = cast?.reactions?.likes_count ?? 0;
		const recasts = cast?.reactions?.recasts_count ?? 0;
		const replies = cast?.replies?.count ?? 0;
		const ts = cast?.timestamp ? Date.parse(cast.timestamp) : NaN;
		out.push({
			hash: cast?.hash || null,
			text: typeof cast?.text === 'string' ? cast.text : '',
			timestamp: Number.isFinite(ts) ? ts : null,
			isReply: Boolean(cast?.parent_hash || cast?.parent_url),
			engagement: likes + recasts * 2 + replies * 3,
		});
	}
	return out;
}

export function normalizeNeynarUser(user) {
	if (!user) return null;
	return {
		fid: user.fid ?? null,
		fname: user.username || null,
		displayName: user.display_name || null,
		bio: user.profile?.bio?.text || null,
		pfpUrl: user.pfp_url || null,
		url: null,
		followerCount: user.follower_count ?? null,
		followingCount: user.following_count ?? null,
	};
}

// ── Cast selection ──────────────────────────────────────────────────────────

const URL_RE = /https?:\/\/\S+/g;
const MENTION_RE = /(^|\s)@[\w.-]+/g;

/** Text left once links and mentions are stripped: what actually carries meaning. */
export function substantiveText(text) {
	return String(text ?? '')
		.replace(URL_RE, ' ')
		.replace(MENTION_RE, ' ')
		.replace(/\s+/g, ' ')
		.trim();
}

/**
 * Pick the casts worth remembering: drop link-only and near-empty posts,
 * de-duplicate reposted text, then rank by engagement when the lane reports it
 * (Neynar) and by recency when it does not (a hub serves raw messages with no
 * reaction counts).
 */
export function selectSeedCasts(casts, { limit = 40, minChars = 16, includeReplies = false } = {}) {
	const seen = new Set();
	const kept = [];
	for (const cast of casts || []) {
		if (!includeReplies && cast.isReply) continue;
		const body = substantiveText(cast.text);
		if (body.length < minChars) continue;
		const key = body.toLowerCase();
		if (seen.has(key)) continue;
		seen.add(key);
		kept.push({ ...cast, body });
	}

	const ranked = kept.some((c) => typeof c.engagement === 'number')
		? kept.sort(
				(a, b) => (b.engagement ?? 0) - (a.engagement ?? 0) || (b.timestamp ?? 0) - (a.timestamp ?? 0),
			)
		: kept.sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0));

	return ranked.slice(0, Math.max(0, limit));
}

// ── Memory rows ─────────────────────────────────────────────────────────────

const MAX_CONTENT_CHARS = 10_000;
const DEFAULT_CAST_MEMORIES = 12;

function isoDay(ms) {
	return Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : null;
}

/**
 * Turn a verified profile, its selected casts, and any LLM-distilled facts into
 * agent_memories rows. Every row carries the consent id so revocation can
 * delete exactly what this grant wrote and nothing else.
 *
 * The profile and cast rows are derived without an LLM, so a seed still
 * produces real memory when the distillation lane is unavailable.
 */
export function buildSeedMemories({
	fid,
	fname = null,
	profile = {},
	casts = [],
	facts = [],
	consentId,
	castMemoryLimit = DEFAULT_CAST_MEMORIES,
}) {
	if (!Number.isInteger(fid) || fid <= 0) throw new Error('fid required');
	if (!consentId) throw new Error('consentId required');

	const handle = fname || profile.fname || String(fid);
	const base = { source: MEMORY_SOURCE, fid, consent_id: consentId, fname: handle };
	const rows = [];

	const identity = [
		profile.displayName ? `Display name: ${profile.displayName}` : null,
		`Farcaster: @${handle} (FID ${fid})`,
		profile.bio ? `Bio: ${profile.bio}` : null,
		Number.isFinite(profile.followerCount) ? `Followers: ${profile.followerCount}` : null,
	]
		.filter(Boolean)
		.join('. ');

	rows.push({
		type: 'user',
		content: clip(`The user's Farcaster identity. ${identity}`),
		tags: ['farcaster', 'profile'],
		context: { ...base, kind: 'profile' },
		salience: 0.8,
	});

	for (const fact of facts) {
		const content = typeof fact === 'string' ? fact.trim() : '';
		if (!content) continue;
		rows.push({
			type: 'user',
			content: clip(content),
			tags: ['farcaster', 'fact'],
			context: { ...base, kind: 'fact' },
			salience: 0.7,
		});
	}

	const topCasts = casts.slice(0, Math.max(0, castMemoryLimit));
	topCasts.forEach((cast, index) => {
		const body = cast.body || substantiveText(cast.text);
		if (!body) return;
		const day = isoDay(cast.timestamp);
		const dated = day ? ` on ${day}` : '';
		// Rank decay keeps the loudest casts above the tail without ever pushing a
		// raw post into the working core, which is reserved for distilled facts.
		const salience = Math.max(0.4, 0.62 - index * 0.015);
		rows.push({
			type: 'reference',
			content: clip(`The user cast${dated} on Farcaster: "${body}"`),
			tags: ['farcaster', 'cast'],
			context: { ...base, kind: 'cast', cast_hash: cast.hash ?? null, cast_at: cast.timestamp ?? null },
			salience: Number(salience.toFixed(3)),
		});
	});

	return rows;
}

function clip(text) {
	return text.length > MAX_CONTENT_CHARS ? `${text.slice(0, MAX_CONTENT_CHARS - 1)}…` : text;
}

/** Prompt input for the distillation lane: newest-first cast text, bounded. */
export function distillationInput({ profile = {}, casts = [], maxCasts = 50 }) {
	const lines = casts
		.slice(0, maxCasts)
		.map((c) => c.body || substantiveText(c.text))
		.filter(Boolean);
	const header = [
		profile.displayName ? `Display name: ${profile.displayName}` : null,
		profile.fname ? `Handle: @${profile.fname}` : null,
		profile.bio ? `Bio: ${profile.bio}` : null,
		Number.isFinite(profile.followerCount) ? `Followers: ${profile.followerCount}` : null,
	]
		.filter(Boolean)
		.join(', ');
	return { header: header || '(no profile data)', casts: lines };
}

/** Parse the distillation model's reply into a bounded list of fact strings. */
export function parseDistilledFacts(raw, { max = 15 } = {}) {
	if (typeof raw !== 'string') return [];
	const stripped = raw
		.replace(/^```(?:json)?\s*/i, '')
		.replace(/\s*```\s*$/i, '')
		.trim();
	let parsed;
	try {
		parsed = JSON.parse(stripped);
	} catch {
		return [];
	}
	if (!Array.isArray(parsed)) return [];
	return parsed
		.filter((f) => typeof f === 'string')
		.map((f) => f.trim())
		.filter(Boolean)
		.slice(0, max);
}