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.

28.5 KB
Raw Blame
// Public AgenC bridge endpoints — free reads of the AgenC coordination
// protocol (agenc.tech, by Tetsuo Corp) so three.ws frontends and external
// agents can browse the on-chain task marketplace without standing up an
// Anchor + IDL pipeline of their own.
//
// Routes (all GET unless noted):
//
//   /api/agenc/list-tasks?creator=<base58>&cluster=devnet
//       Returns every task PDA created by `creator`, with state + reward.
//
//   /api/agenc/get-task?taskPda=<base58>&cluster=devnet[&lifecycle=1]
//   /api/agenc/get-task?creator=<base58>&taskId=<hex|label>&cluster=devnet
//       Single task status + (optionally) lifecycle timeline.
//
//   /api/agenc/recent-tasks?cluster=devnet[&limit=6]
//       The newest task PDAs three.ws itself wrote on-chain through the Agora
//       rail, read from the platform's own journal (no RPC round trip), so a
//       client with no address in hand has something real to watch.
//
//   /api/agenc/get-agent?agentPda=<base58>&cluster=devnet
//   /api/agenc/get-agent?agentId=<hex|label>&cluster=devnet
//       Agent registration state.
//
//   /api/agenc/link (POST)
//       body: { erc8004AgentId?, mplCoreAsset?, handle?, cluster? }
//       → { agenCAgentId, agentPda, metadataUri, source, label,
//             registered, agent? }
//       Computes the canonical three.ws → AgenC agentId via the identity
//       bridge and checks whether that PDA is already registered on-chain.
//
// Cluster defaults to `mainnet`; set `?cluster=devnet` for the devnet
// deployment. Every response carries the `programId` the read actually ran
// against, because `createAgenCClient` derives it from the bundled IDL rather
// than from a constant: quoting a program address from anywhere else (docs, UI
// copy, an older SDK export) is how a page ends up naming a program no read of
// ours has touched in months. Reads rotate across the platform's canonical
// Solana RPC chain (see withAgenC below); `AGENC_RPC_URL` pins a preferred
// endpoint at the head of that chain.

import { PublicKey } from '@solana/web3.js';
import { createHash } from 'node:crypto';
import { getTask, getTaskLifecycleSummary, getTasksByCreator, getAgent, deriveTaskPda, deriveAgentPda } from '@tetsuo-ai/sdk';

import { cors, json, method, readJson, wrap, error, rateLimited, serverError } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { sql } from '../_lib/db.js';
import {
	solanaRpcEndpoints,
	isEndpointCooling,
	markEndpointCooldown,
	hydrateEndpointCooldowns,
	shouldRotate,
	isTransientRpcError,
} from '../_lib/solana/connection.js';
import { Bazaar, filterByExtension, filterByMaxPrice, filterByNetwork, parseAtomicAmount } from '../_lib/x402/bazaar-client.js';

// @three-ws/solana-agent (the symlinked `file:solana-agent-sdk` SDK) is loaded
// LAZILY at the point of use — every other importer (api/agora/act.js,
// api/agora/[action].js, api/_lib/agora-human.js) does the same so the module
// evaluates even where the SDK's dist/ isn't built yet, and so the Vitest
// resolver doesn't have to externalize a static entry it can't load.

function pickCluster(req) {
	const c = (req.query?.cluster || '').toString().trim().toLowerCase();
	return c === 'devnet' ? 'devnet' : 'mainnet';
}

function parsePubkey(s, label) {
	if (!s) throw new Error(`${label} is required`);
	try {
		return new PublicKey(String(s).trim());
	} catch {
		throw new Error(`${label} is not a valid base58 pubkey`);
	}
}

function resolveIdInput(s) {
	const t = String(s).trim();
	if (t.startsWith('0x') || t.startsWith('0X')) {
		const hex = t.slice(2);
		if (hex.length !== 64) throw new Error('hex id must be 32 bytes');
		return Uint8Array.from(Buffer.from(hex, 'hex'));
	}
	if (/^[0-9a-fA-F]{64}$/.test(t)) return Uint8Array.from(Buffer.from(t, 'hex'));
	return Uint8Array.from(createHash('sha256').update(t, 'utf8').digest());
}

function serialize(value) {
	if (value === null || value === undefined) return value;
	if (typeof value === 'bigint') return value.toString();
	if (value instanceof Uint8Array) return Buffer.from(value).toString('hex');
	if (value instanceof PublicKey) return value.toBase58();
	if (Array.isArray(value)) return value.map(serialize);
	if (typeof value === 'object') {
		const out = {};
		for (const [k, v] of Object.entries(value)) out[k] = serialize(v);
		return out;
	}
	return value;
}

// AgenC's on-chain TaskState enum, verbatim (@tetsuo-ai/sdk `TaskState` /
// `formatTaskState`). This map was previously shifted by one past `Open`, which
// reported a Completed task as "Cancelled" and a Cancelled one as "Disputed": the
// worst kind of wrong, because it reads as a definite (and alarming) status rather
// than an error. There is no 'Expired' state on-chain; a lapsed deadline leaves the
// task Open until its creator cancels it.
export function taskStateLabel(state) {
	const map = { 0: 'Open', 1: 'In Progress', 2: 'Pending Validation', 3: 'Completed', 4: 'Cancelled', 5: 'Disputed' };
	if (typeof state === 'number') return map[state] ?? `Unknown(${state})`;
	if (state && typeof state === 'object') {
		const key = Object.keys(state)[0];
		return key ? key[0].toUpperCase() + key.slice(1) : 'Unknown';
	}
	return String(state);
}

// A base58 address a visitor can legitimately paste but that is not an AgenC
// account of the expected type fails INSIDE the Anchor decoder ("Invalid account
// discriminator", "Account does not exist"), not by returning null. That error is
// deterministic, so `rotateRpc` correctly re-throws it on the first endpoint, and
// the wrapper then answered an opaque 500 for what is really "no such task on
// this cluster": the single most likely thing a visitor gets wrong, reported as
// though the platform were broken. Classify it and reuse the handler's own 404.
function isWrongAccount(err) {
	return /invalid account discriminator|account does not exist|could not find account|failed to deserialize/i.test(
		String(err?.message || err),
	);
}

// Read an AgenC account, turning "that address holds no such account" into null
// so callers render the honest 404 instead of a server error.
async function readAccount(read) {
	try {
		return await read();
	} catch (err) {
		if (isWrongAccount(err)) return null;
		throw err;
	}
}

function agentStatusLabel(status) {
	const map = { 0: 'Inactive', 1: 'Active', 2: 'Busy', 3: 'Suspended' };
	if (typeof status === 'number') return map[status] ?? `Unknown(${status})`;
	if (status && typeof status === 'object') {
		const key = Object.keys(status)[0];
		return key ? key[0].toUpperCase() + key.slice(1) : 'Unknown';
	}
	return String(status);
}

// `createAgenCClient` builds its own Connection from ONE url, so a client made
// here is bound to a single endpoint with no failover of its own. Pointing it at
// `SOLANA_RPC_URL` alone is what took every chain-backed AgenC route down: the
// configured primary began answering this egress with a hard 403, and each read
// became an opaque 500 while eight healthy lanes sat unused. So we walk the
// platform's canonical, priority-ordered endpoint chain instead and share its
// process-wide cooldown map, which means a lane another surface just parked is
// skipped here too, and a lane we park is skipped there. `AGENC_RPC_URL` still
// wins: it is pinned to the head of the chain rather than being the whole of it.
async function agenCEndpoints(cluster) {
	// Inherit the fleet's view of dead lanes first. Without it a cold Cloud Run
	// instance re-discovers a quota-dead provider the expensive way: web3.js runs
	// its own 429 backoff (500/1000/2000/4000ms) inside the Connection before the
	// error ever reaches us, so each already-known-dead lane costs ~7.5s.
	await hydrateEndpointCooldowns();
	const pinned = (process.env.AGENC_RPC_URL || '').trim() || null;
	const urls = solanaRpcEndpoints(cluster, pinned);
	const live = urls.filter((u) => !isEndpointCooling(u));
	// Every lane cooling at once is upstream weather, not a reason to answer with
	// nothing: re-probe the full chain rather than skipping straight to a 503.
	return live.length ? live : urls;
}

// Recover the upstream HTTP status from a web3.js error, which reports it as the
// head of the message ("403 Forbidden: {…}"). 0 means "no status in there".
function rpcStatus(err) {
	const m = String(err?.message || err).match(/\b(401|403|404|408|410|429|5\d\d)\b/);
	return m ? Number(m[1]) : 0;
}

// Thrown once every endpoint has refused the same read. Distinct from a normal
// failure so the wrapper can answer 503 + Retry-After (upstream weather the
// caller should retry) instead of a 500 (a defect the caller cannot act on).
export class RpcChainExhausted extends Error {
	constructor(cluster, tried, cause) {
		super(`all ${tried} Solana RPC endpoints refused this ${cluster} read: ${cause?.message || 'unknown error'}`);
		this.name = 'RpcChainExhausted';
		this.cluster = cluster;
		this.tried = tried;
		this.cause = cause;
	}
}

// A lane that ACCEPTS the connection and then never answers is the one failure
// this rotation could not see. `createAgenCClient` builds a plain
// `new Connection(rpcUrl)`, so it never gets the rotating fetch's own
// ATTEMPT_TIMEOUT_MS bound (that only wraps multi-endpoint Connections); undici's
// defaults then run to minutes with nothing thrown, so `rotateRpc` sat on a dead
// provider instead of moving to the next one. `getTasksByCreator` is the read
// that exposed it: it is a getProgramAccounts memcmp scan, the heaviest call
// shape here and the first any provider stalls or silently drops. Bounding each
// attempt turns that silence back into a rotate-worthy failure.
const AGENC_ATTEMPT_TIMEOUT_MS = 10_000;

// Reject with a transient, rotate-worthy error once an attempt outruns its
// budget. The message is deliberately shaped to match `isTransientRpcError`, so
// a stall cools the lane exactly like a timeout reported by the provider itself.
function attemptTimeout(rpcUrl) {
	let timer;
	const promise = new Promise((_, reject) => {
		timer = setTimeout(() => {
			reject(new Error(`Solana RPC lane timed out after ${AGENC_ATTEMPT_TIMEOUT_MS}ms: ${rpcUrl}`));
		}, AGENC_ATTEMPT_TIMEOUT_MS);
	});
	// Never hold the process open on the loser of the race.
	timer?.unref?.();
	return { promise, cancel: () => clearTimeout(timer) };
}

// Run `run` against an AgenC client, rotating to the next endpoint whenever one
// fails in a way the next provider may not share (401/403/404/408/410/429/5xx,
// timeouts, network blips) or simply stops answering. A real request error, e.g.
// a malformed account the chain decodes the same way everywhere, is re-thrown on
// the first endpoint rather than replayed nine times.
export async function rotateRpc({ cluster, endpoints, createClient, run }) {
	let last = null;
	for (const rpcUrl of endpoints) {
		let client;
		try {
			client = createClient(rpcUrl);
		} catch (err) {
			// A URL this build of web3.js refuses to construct a Connection from is a
			// dead lane, not a dead chain: skip it and let the next endpoint answer.
			last = err;
			continue;
		}
		const bound = attemptTimeout(rpcUrl);
		try {
			return await Promise.race([run(client), bound.promise]);
		} catch (err) {
			const status = rpcStatus(err);
			if (!shouldRotate(status) && !isTransientRpcError(err)) throw err;
			const ms = markEndpointCooldown(rpcUrl, status || 429, String(err?.message || ''));
			console.info(`[agenc] rpc lane failed (${status || 'transient'}), cooling ${Math.round(ms / 1000)}s, rotating`);
			last = err;
		} finally {
			// Runs on success, rotation, and the re-thrown non-rotatable error alike,
			// so a won race never leaves a timer pending behind the response.
			bound.cancel();
		}
	}
	throw new RpcChainExhausted(cluster, endpoints.length, last);
}

async function withAgenC(cluster, run) {
	const { createAgenCClient } = await import('@three-ws/solana-agent');
	const endpoints = await agenCEndpoints(cluster);
	return rotateRpc({
		cluster,
		endpoints,
		createClient: (rpcUrl) => createAgenCClient({ cluster, rpcUrl }),
		run,
	});
}

async function handleListTasks(req, res) {
	let creator;
	try {
		creator = parsePubkey(req.query?.creator, 'creator');
	} catch (err) {
		return error(res, 400, 'validation_error', err.message);
	}
	const { client, tasks } = await withAgenC(pickCluster(req), async (c) => ({
		client: c,
		tasks: await getTasksByCreator(c.program, creator),
	}));
	return json(res, 200, serialize({
		ok: true,
		cluster: client.cluster,
		programId: client.programId,
		creator,
		count: tasks.length,
		tasks: tasks.map((t) => ({
			taskId: Buffer.from(t.taskId).toString('hex'),
			taskPda: deriveTaskPda(creator, t.taskId, client.programId),
			state: taskStateLabel(t.state),
			stateRaw: typeof t.state === 'number' ? t.state : null,
			rewardAmount: t.rewardAmount,
			rewardMint: t.rewardMint,
			deadline: t.deadline,
			currentWorkers: t.currentWorkers,
			maxWorkers: t.maxWorkers,
			completedAt: t.completedAt,
			private: !!t.constraintHash,
		})),
		fetchedAt: new Date().toISOString(),
	}));
}

// Task discovery without an address in hand. `list-tasks` can only answer once
// the caller already knows a creator wallet, which leaves every first-time
// visitor of /agenc/embodied staring at an input box with nothing to put in it
// and no way to find one: the surface renders live on-chain state and offered no
// path to any. The platform does know real task PDAs, because every task the
// Agora rail posts, claims, and completes is journalled with the PDA it wrote.
// So this reads our own ledger (one DB round trip, no getProgramAccounts scan)
// and hands back the newest PDAs for the requested cluster. It is a pointer
// list, not a source of truth: whatever the caller then acts on is verified
// against the chain by `get-task`.
async function handleRecentTasks(req, res) {
	const cluster = pickCluster(req);
	const requested = parseInt(String(req.query?.limit ?? '6'), 10);
	const limit = Math.min(Math.max(Number.isFinite(requested) ? requested : 6, 1), 25);

	let rows;
	try {
		rows = await sql`
			select a.task_pda,
			       max(a.created_at) as last_activity_at,
			       max(a.reward_label) as reward_label,
			       array_agg(distinct a.kind) as kinds
			  from agora_activity a
			  join agora_citizens c on c.id = a.citizen_id
			 where a.task_pda is not null
			   and c.agenc_cluster = ${cluster}
			 group by a.task_pda
			 order by last_activity_at desc
			 limit ${limit}`;
	} catch (err) {
		// The journal is a convenience index over work the chain already holds, so
		// a DB blip degrades discovery rather than failing the request: the caller
		// still has the manual taskPda path, and `degraded` tells it to say so.
		console.warn('[agenc] recent-tasks journal unavailable:', err?.message);
		return json(res, 200, { ok: true, cluster, count: 0, degraded: true, tasks: [], fetchedAt: new Date().toISOString() });
	}

	return json(res, 200, {
		ok: true,
		cluster,
		count: rows.length,
		degraded: false,
		tasks: rows.map((r) => ({
			taskPda: r.task_pda,
			lastActivityAt: r.last_activity_at instanceof Date ? r.last_activity_at.toISOString() : r.last_activity_at,
			rewardLabel: r.reward_label ?? null,
			kinds: Array.isArray(r.kinds) ? r.kinds : [],
		})),
		fetchedAt: new Date().toISOString(),
	});
}

async function handleGetTask(req, res) {
	const q = req.query || {};
	// Resolve the caller's identifiers BEFORE touching the chain: a malformed pubkey
	// or task id is a 400 that must not cost an RPC round trip (or nine of them).
	let explicitPda = null;
	let creator = null;
	let taskIdSeed = null;
	try {
		if (q.taskPda) {
			explicitPda = parsePubkey(q.taskPda, 'taskPda');
		} else if (q.creator && q.taskId) {
			creator = parsePubkey(q.creator, 'creator');
			taskIdSeed = resolveIdInput(q.taskId);
		} else {
			return error(res, 400, 'validation_error', 'provide taskPda OR (creator + taskId)');
		}
	} catch (err) {
		return error(res, 400, 'validation_error', err.message);
	}

	const wantLifecycle = q.lifecycle === '1' || q.lifecycle === 'true';
	const { client, pda, task, lifecycle } = await withAgenC(pickCluster(req), async (c) => {
		const taskPda = explicitPda || deriveTaskPda(creator, taskIdSeed, c.programId);
		const found = await readAccount(() => getTask(c.program, taskPda));
		if (!found || !wantLifecycle) return { client: c, pda: taskPda, task: found, lifecycle: null };
		const s = await readAccount(() => getTaskLifecycleSummary(c.program, taskPda));
		if (!s) return { client: c, pda: taskPda, task: found, lifecycle: null };
		return {
			client: c,
			pda: taskPda,
			task: found,
			lifecycle: {
				currentState: taskStateLabel(s.currentState),
				createdAt: s.createdAt,
				currentWorkers: s.currentWorkers,
				maxWorkers: s.maxWorkers,
				timeline: s.timeline.map((e) => ({
					eventName: e.eventName,
					timestamp: e.timestamp,
					txSignature: e.txSignature ?? null,
					actor: e.actor ? e.actor.toBase58() : null,
				})),
			},
		};
	});

	if (!task) {
		return json(res, 404, {
			ok: false,
			error: 'not_found',
			cluster: client.cluster,
			programId: client.programId.toBase58(),
			taskPda: pda.toBase58(),
		});
	}

	// Journal enrichment reads our own DB, not the chain, so it stays outside the
	// RPC rotation: a DB blip must never cost a second pass over every endpoint.
	if (lifecycle) await enrichLifecycleFromProjection(lifecycle, pda.toBase58());

	return json(res, 200, serialize({
		ok: true,
		cluster: client.cluster,
		programId: client.programId,
		taskPda: pda,
		task: {
			taskId: Buffer.from(task.taskId).toString('hex'),
			state: taskStateLabel(task.state),
			stateRaw: typeof task.state === 'number' ? task.state : null,
			creator: task.creator,
			rewardAmount: task.rewardAmount,
			rewardMint: task.rewardMint,
			deadline: task.deadline,
			currentWorkers: task.currentWorkers,
			maxWorkers: task.maxWorkers,
			completedAt: task.completedAt,
			constraintHash: task.constraintHash ? Buffer.from(task.constraintHash).toString('hex') : null,
			private: !!task.constraintHash,
		},
		lifecycle,
		fetchedAt: new Date().toISOString(),
	}));
}

// A task account records WHAT happened but not the signature of the transaction
// that did it: Solana account state can't recover the signatures that wrote it,
// so every on-chain timeline event arrives with `txSignature: null` and a client
// can only render "no tx recorded". three.ws does know them: each write through
// the Agora rail is journalled into `agora_activity` with its real signature (and,
// for a completion, the deliverable URL + proofHash that the completion bound).
//
// So we fill the chain's blanks from our own journal, keyed by task PDA. Rules:
//   • The chain stays authoritative: an event that already carries a signature is
//     never overwritten, and no event is invented that the chain didn't report.
//   • Enrichment is best-effort: if the DB is unreachable the timeline is returned
//     exactly as the chain gave it. A missing signature renders as an honest "no tx
//     recorded", never a broken Explorer link.
//   • Surfacing `proofHash` + `deliverableUrl` on the completion event is what lets
//     a deep-linked task (/agora?task=<pda>) verify itself: without it a visitor
//     arriving by URL has bytes to fetch but nothing to check them against.
const LIFECYCLE_EVENT_KINDS = [
	{ match: /^(task)?created/i, kinds: ['posted_task', 'hired'] },
	{ match: /^(task)?claim/i, kinds: ['claimed_task'] },
	{ match: /^(task)?(complete|prove|submit)/i, kinds: ['completed_task', 'settled'] },
];

export async function enrichLifecycleFromProjection(lifecycle, taskPda) {
	if (!lifecycle?.timeline?.length) return;
	let rows;
	try {
		rows = await sql`
			select kind, tx_signature, proof_hash, deliverable_url, created_at
			from agora_activity
			where task_pda = ${taskPda} and tx_signature is not null
			order by created_at asc
			limit 200
		`;
	} catch (err) {
		// No DB (or it's down): the chain's own timeline is still correct and honest.
		console.warn('[agenc] lifecycle tx enrichment unavailable:', err?.message);
		return;
	}
	if (!rows?.length) return;

	// Consume each journal row at most once so a multi-worker task's second claim
	// can't inherit the first claim's signature.
	const used = new Set();
	for (const ev of lifecycle.timeline) {
		const spec = LIFECYCLE_EVENT_KINDS.find((s) => s.match.test(ev.eventName || ''));
		if (!spec) continue;
		let row = null;
		for (let i = 0; i < rows.length; i++) {
			if (used.has(i) || !spec.kinds.includes(rows[i].kind)) continue;
			used.add(i);
			row = rows[i];
			break;
		}
		if (!row) continue;
		if (!ev.txSignature) ev.txSignature = row.tx_signature;
		if (row.proof_hash && !ev.proofHash) ev.proofHash = row.proof_hash;
		if (row.deliverable_url && !ev.deliverableUrl) ev.deliverableUrl = row.deliverable_url;
	}

	// Hoist the deliverable proof to the top level too, so a client that only has a
	// PDA (a deep link) can run the verifier without walking the timeline.
	const done = lifecycle.timeline.find((e) => e.proofHash || e.deliverableUrl);
	if (done) {
		lifecycle.proofHash = done.proofHash || null;
		lifecycle.deliverableUrl = done.deliverableUrl || null;
	}
}

async function handleGetAgent(req, res) {
	const q = req.query || {};
	let explicitPda = null;
	let agentIdSeed = null;
	try {
		if (q.agentPda) {
			explicitPda = parsePubkey(q.agentPda, 'agentPda');
		} else if (q.agentId) {
			agentIdSeed = resolveIdInput(q.agentId);
		} else {
			return error(res, 400, 'validation_error', 'provide agentPda or agentId');
		}
	} catch (err) {
		return error(res, 400, 'validation_error', err.message);
	}
	const { client, pda, agent } = await withAgenC(pickCluster(req), async (c) => {
		const agentPda = explicitPda || deriveAgentPda(agentIdSeed, c.programId);
		return { client: c, pda: agentPda, agent: await readAccount(() => getAgent(c.program, agentPda)) };
	});
	if (!agent) {
		return json(res, 404, {
			ok: false,
			error: 'not_found',
			cluster: client.cluster,
			programId: client.programId.toBase58(),
			agentPda: pda.toBase58(),
		});
	}
	return json(res, 200, serialize({
		ok: true,
		cluster: client.cluster,
		programId: client.programId,
		agentPda: pda,
		agent: {
			agentId: Buffer.from(agent.agentId).toString('hex'),
			authority: agent.authority,
			capabilities: agent.capabilities,
			status: agentStatusLabel(agent.status),
			statusRaw: typeof agent.status === 'number' ? agent.status : null,
			endpoint: agent.endpoint,
			metadataUri: agent.metadataUri,
			stakeAmount: agent.stakeAmount,
			activeTasks: agent.activeTasks,
			reputation: agent.reputation,
			registeredAt: agent.registeredAt,
		},
		fetchedAt: new Date().toISOString(),
	}));
}

async function handleLink(req, res) {
	let body;
	try {
		body = await readJson(req);
	} catch {
		return error(res, 400, 'validation_error', 'invalid json');
	}
	const { erc8004AgentId, mplCoreAsset, handle, cluster, baseUrl } = body || {};
	const { getCanonicalThreewsAgenCId, buildThreewsMetadataUri, agenCAgentIdToHex } =
		await import('@three-ws/solana-agent');
	let canonical;
	try {
		canonical = getCanonicalThreewsAgenCId({
			erc8004AgentId: erc8004AgentId ?? null,
			mplCoreAsset: mplCoreAsset ?? null,
			handle: handle ?? null,
		});
	} catch (err) {
		return error(res, 400, 'validation_error', err.message);
	}

	const cl = cluster === 'devnet' ? 'devnet' : 'mainnet';
	const { client, pda, agent } = await withAgenC(cl, async (c) => {
		const agentPda = deriveAgentPda(canonical.agenCAgentId, c.programId);
		return { client: c, pda: agentPda, agent: await readAccount(() => getAgent(c.program, agentPda)) };
	});

	const metadataUri = buildThreewsMetadataUri(
		{ erc8004AgentId: erc8004AgentId ?? null, mplCoreAsset: mplCoreAsset ?? null, handle: handle ?? null },
		typeof baseUrl === 'string' && baseUrl ? baseUrl : 'https://three.ws',
	);

	return json(res, 200, serialize({
		ok: true,
		cluster: client.cluster,
		programId: client.programId,
		source: canonical.source,
		label: canonical.label,
		agenCAgentId: agenCAgentIdToHex(canonical.agenCAgentId),
		agentPda: pda,
		metadataUri,
		registered: !!agent,
		agent: agent
			? {
					authority: agent.authority,
					status: agentStatusLabel(agent.status),
					endpoint: agent.endpoint,
					metadataUri: agent.metadataUri,
					reputation: agent.reputation,
					activeTasks: agent.activeTasks,
					stakeAmount: agent.stakeAmount,
				}
			: null,
		fetchedAt: new Date().toISOString(),
	}));
}

// Stable 32-byte taskId seed derived from an x402 resource URL — lets the
// same x402 service map to a deterministic AgenC task PDA so re-postings
// idempotently update the same on-chain account.
function x402TaskIdSeed(resource) {
	return createHash('sha256')
		.update('AgenC/three.ws/x402/v1\0', 'utf8')
		.update(String(resource), 'utf8')
		.digest();
}

async function handleX402Services(req, res) {
	const q = req.query || {};
	const type = (q.type || 'http').toString().toLowerCase();
	if (type !== 'http' && type !== 'mcp') {
		return error(res, 400, 'validation_error', 'type must be "http" or "mcp"');
	}
	const network = q.network ? String(q.network) : null;
	const maxPrice = q.maxPrice ? String(q.maxPrice) : null;
	// Atomic units, not decimals (see /api/bazaar/list): a malformed cap is a 400.
	if (maxPrice != null && parseAtomicAmount(maxPrice) === null) {
		return error(res, 400, 'validation_error', 'maxPrice must be an atomic integer amount (e.g. 10000 = 0.01 USDC)');
	}
	const asset = q.asset ? String(q.asset) : null;
	const extension = q.extension ? String(q.extension) : null;
	const maxItems = Math.max(1, Math.min(parseInt(q.maxItems, 10) || 200, 1000));

	const baz = new Bazaar();
	let result;
	try {
		result = await baz.list({ type, limit: 200, maxItems });
	} catch (err) {
		console.error('[agenc] bazaar fetch failed', err?.message);
		return serverError(res, 502, 'facilitator_error', err);
	}
	let items = result.items;
	if (network) items = filterByNetwork(items, network);
	if (maxPrice) items = filterByMaxPrice(items, maxPrice, asset);
	if (extension) items = filterByExtension(items, extension);

	const tasks = items.map((it) => {
		const minAccept = it.accepts?.[0] || null;
		const seed = x402TaskIdSeed(it.uniqueKey || it.resource);
		return {
			source: 'three.ws/x402',
			type: it.type,
			resource: it.resource,
			toolName: it.toolName || null,
			serviceName: it.serviceName,
			description: it.description,
			tags: it.tags || [],
			method: it.method || null,
			capabilities: 1, // bit 0: HTTP fetch / x402 settle
			price: minAccept
				? {
						amountAtomic: minAccept.amountAtomic,
						amountLabel: minAccept.priceLabel,
						currency: minAccept.asset,
						network: minAccept.network,
						family: minAccept.family,
					}
				: null,
			input: it.input || null,
			output: it.output || null,
			taskIdSeed: '0x' + Buffer.from(seed).toString('hex'),
			rewardKind: 'x402_pay_to_endpoint',
			facilitator: it.facilitator,
			lastUpdated: it.lastUpdated,
		};
	});

	res.setHeader('cache-control', 'public, max-age=15, stale-while-revalidate=60');
	return json(res, 200, {
		ok: true,
		count: tasks.length,
		tasks,
		sources: result.sources,
		errors: result.errors,
		fetchedAt: new Date().toISOString(),
	});
}

const HANDLERS = {
	'list-tasks': { methods: ['GET'], fn: handleListTasks },
	'recent-tasks': { methods: ['GET'], fn: handleRecentTasks },
	'get-task': { methods: ['GET'], fn: handleGetTask },
	'get-agent': { methods: ['GET'], fn: handleGetAgent },
	'x402-services': { methods: ['GET'], fn: handleX402Services },
	link: { methods: ['POST'], fn: handleLink },
};

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: false })) return;
	const action = String(req.query?.action || '').toLowerCase();
	const route = HANDLERS[action];
	if (!route) return error(res, 404, 'not_found', `unknown action "${action}"`);
	if (!method(req, res, route.methods)) return;

	const rl = await limits.publicIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	try {
		return await route.fn(req, res);
	} catch (err) {
		// Every RPC lane refusing the same read is upstream weather with a real
		// remedy (retry once a cooldown lapses), so it gets an honest 503 + a
		// Retry-After the caller can act on. A 500 here told clients "we are
		// broken, do not retry" for a condition that clears itself in seconds.
		if (err instanceof RpcChainExhausted) {
			console.error('[agenc] rpc chain exhausted', err.message);
			// A handler that already wrote a response before throwing would make this
			// setHeader throw ERR_HTTP_HEADERS_SENT, turning a clean 503 into a crash.
			if (!res.headersSent) res.setHeader('retry-after', '30');
			return error(res, 503, 'rpc_unavailable', `Solana ${err.cluster} RPC is unavailable right now; retry in ~30s`, {
				cluster: err.cluster,
				endpointsTried: err.tried,
			});
		}
		console.error('[agenc] unexpected error', err?.message);
		return serverError(res, 500, 'agenc_error', err);
	}
});