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.

32.1 KB
Raw Blame
// Agora — human citizen actions (Task 08, see docs/agora.md § Citizens).
//
// The single authenticated, mutating entry point for a signed-in human living
// in Agora. Every action runs the SAME real on-chain AgenC operation an agent
// would and projects into the SAME agora_activity ledger + feed — there is no
// separate "fake human" path (docs/agora.md invariant 1 + 3).
//
// POST /api/agora/act   { action, ... }
//   join        → upsert a human citizen + custodial wallet, place in the Commons
//   post-task   → escrow a bounty on AgenC (createTask) for a target profession
//   hire        → post a bounty routed to a specific citizen (profession + minRep)
//   claim       → claim an open on-chain task as the worker yourself
//   complete    → submit a real proof (sha256 of your deliverable) → earn
//   vouch       → leave a real on-chain attestation for a citizen
//
// Guards (all server-side): session-or-bearer auth + CSRF (api/_lib/labor-auth),
// per-user rate limit, boundary input validation, a durable per-user spend
// policy (api/_lib/agora-policy) gating real-money escrow + the mainnet $THREE
// gate, and Idempotency-Key support so a retried POST never double-escrows.

import { createHash } from 'node:crypto';
import { cors, error, json, method, rateLimited, readJson, wrap, serverError, reportServerError } from '../_lib/http.js';
import { limits } from '../_lib/rate-limit.js';
import { sql } from '../_lib/db.js';
import { authWrite } from '../_lib/labor-auth.js';
import { TOKEN_MINT } from '../_lib/token/config.js';
import {
	ensureHumanCitizen, ensureRegistered, ensureDevnetBalance, requireFunded,
	projectActivity, bumpCitizenStats, citizenBalances, professionToCapabilityBits,
	PROFESSION_BITS, THREE_ATOMICS_PER_TOKEN, rewardLabel, proofHashFor,
	sendOnchainAttestation, explorerTx, recoverTimedOutSignature, findCompletionSignature,
} from '../_lib/agora-human.js';
import { resolveCluster, reservePostSpend, settlePostSpend, releasePostSpend } from '../_lib/agora-policy.js';
// Boundary shape checks for the two id kinds a caller can hand us: a citizen id
// (uuid column) and a task PDA (base58 pubkey). Both must be rejected here, or a
// malformed value reaches Postgres / PublicKey and surfaces as a 5xx.
import { isUuid, isValidSolanaAddress } from '../_lib/validate.js';
import { redactUrlSecrets as redactSecrets } from '../_lib/scrub-secrets.js';

const LAMPORTS_PER_SOL = 1_000_000_000n;
const MAX_TITLE = 140;
const MAX_DESC = 4000;
const MAX_DELIVERABLE = 8000;

// ── small helpers ─────────────────────────────────────────────────────────────

async function loadUser(userId) {
	const [u] = await sql`
		select id, display_name, username, avatar_url from users
		where id = ${userId} and deleted_at is null limit 1`;
	return u || null;
}

// AgenC rejects a claim/completion for real, explainable reasons (you posted it,
// someone already took it, your reputation is short). Every AnchorError carries
// the program's own human-readable reason, so surface THAT instead of a
// generic 502 the user can do nothing with. Returns null for non-Anchor failures
// (RPC/transport), which stay a 502 + support ref.
function onchainRejection(err) {
	const msg = String(err?.message || '');
	const reason = /Error Message:\s*([^\n]+)/.exec(msg);
	if (!reason) return null;
	const name = /Error Code:\s*(\w+)/.exec(msg);
	const code = name
		? name[1].replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
		: 'onchain_rejected';
	return { code, message: reason[1].trim().replace(/\.$/, '') };
}

// Solana RPC going dark (devnet throttling, a dropped socket, a confirm that
// timed out) is an outage, not a malformed request. It gets its own retryable
// 503 with an honest instruction, never an opaque 500 + a support ref the user
// can do nothing with. We deliberately do NOT claim the attempt left no trace:
// a transport failure after submit is ambiguous, so we tell them to check.
const RPC_OUTAGE = /fetch failed|econnreset|etimedout|enotfound|socket hang up|too many requests|429|rate limit|timed out|timeout/i;

function rpcUnavailable(err) {
	return RPC_OUTAGE.test(`${err?.message || ''} ${err?.cause?.message || ''}`);
}

const RPC_OUTAGE_MESSAGE =
	'Solana is not responding right now, so this action could not be completed. Check your activity before retrying, in case it landed.';

function reqHash(action, body) {
	return createHash('sha256').update(JSON.stringify({ action, body })).digest('hex');
}

// Durable idempotency on (user, action, key). Returns one of:
//   { replay: response }   — a prior identical request already completed
//   { conflict: true }     — same key, different payload (409)
//   { inflight: true }     — a request with this key is still running (409)
//   { proceed: true }      — we own the lock; finish() captures the result
async function idemBegin(userId, action, key, hash) {
	if (!key) return { proceed: true, key: null };
	try {
		await sql`
			insert into agora_idempotency (user_id, action, idem_key, status, request_hash)
			values (${userId}, ${action}, ${key}, 'pending', ${hash})`;
		return { proceed: true, key };
	} catch {
		const [row] = await sql`
			select status, response, request_hash from agora_idempotency
			where user_id = ${userId} and action = ${action} and idem_key = ${key} limit 1`;
		if (!row) return { proceed: true, key }; // race lost then row gone — proceed
		if (row.request_hash && row.request_hash !== hash) return { conflict: true };
		if (row.status === 'done') return { replay: row.response };
		return { inflight: true };
	}
}

async function idemFinish(userId, action, key, response) {
	if (!key) return;
	await sql`
		update agora_idempotency set status = 'done', response = ${JSON.stringify(response)}::jsonb
		where user_id = ${userId} and action = ${action} and idem_key = ${key}`.catch(() => {});
}

async function idemRelease(userId, action, key) {
	if (!key) return;
	await sql`
		delete from agora_idempotency
		where user_id = ${userId} and action = ${action} and idem_key = ${key} and status = 'pending'`.catch(() => {});
}

// Shape the "you" HUD payload — citizen status + balances + live tasks/earnings.
async function shapeMe(citizen, cluster) {
	const balances = await citizenBalances(citizen, cluster).catch(() => ({ sol: null, three: null, address: citizen.meta?.solana_address || null }));
	const [posted, open] = await Promise.all([
		sql`select count(*)::int as n from agora_activity where citizen_id = ${citizen.id} and kind = 'posted_task'`,
		sql`select a.task_pda, a.reward_label, a.profession, a.created_at
		    from agora_activity a
		    where a.citizen_id = ${citizen.id} and a.kind = 'posted_task' and a.task_pda is not null
		      and not exists (
		        select 1 from agora_activity x where x.task_pda = a.task_pda
		          and x.kind in ('claimed_task','completed_task','cancelled_task','expired_task','slashed')
		          and x.created_at >= a.created_at)
		    order by a.created_at desc limit 20`,
	]);
	return {
		citizenId: citizen.id,
		displayName: citizen.display_name,
		avatarUrl: citizen.avatar_url,
		status: citizen.status,
		cluster: citizen.agenc_cluster,
		walletAddress: balances.address,
		registered: !!citizen.agenc_agent_pda,
		agentPda: citizen.agenc_agent_pda,
		reputation: citizen.reputation,
		tasksPosted: citizen.tasks_posted,
		tasksCompleted: citizen.tasks_completed,
		earnedThreeAtomic: String(citizen.earned_three_atomic ?? '0'),
		balances: { sol: balances.sol, three: balances.three },
		home: { x: citizen.home_x, z: citizen.home_z },
		position: { x: citizen.pos_x, z: citizen.pos_z },
		openPostedCount: posted[0]?.n || 0,
		openPosted: open.map((t) => ({ taskPda: t.task_pda, rewardLabel: t.reward_label, profession: t.profession, postedAt: t.created_at })),
	};
}

// Resolve the reward in atomic units for a cluster from the request body. Devnet
// rewards are SOL (lamports); mainnet rewards are $THREE (token atomics).
function resolveRewardAtomic(body, cluster) {
	if (cluster === 'mainnet') {
		const three = Number(body.rewardThree);
		if (!Number.isFinite(three) || three <= 0) return null;
		const whole = BigInt(Math.floor(three));
		const frac = BigInt(Math.round((three - Math.floor(three)) * Number(THREE_ATOMICS_PER_TOKEN)));
		return whole * THREE_ATOMICS_PER_TOKEN + frac;
	}
	const sol = Number(body.rewardSol);
	if (!Number.isFinite(sol) || sol <= 0) return null;
	const whole = BigInt(Math.floor(sol));
	const frac = BigInt(Math.round((sol - Math.floor(sol)) * Number(LAMPORTS_PER_SOL)));
	return whole * LAMPORTS_PER_SOL + frac;
}

// ── shared task-posting core (post-task + hire) ───────────────────────────────

async function postTaskCore({ user, body, requestedCluster, hire }) {
	const cluster = resolveCluster(requestedCluster);

	const title = String(body.title || '').trim();
	const description = String(body.description || body.spec || '').trim();
	if (!title || title.length > MAX_TITLE) return { err: [400, 'validation_error', `title is required (≤${MAX_TITLE} chars)`] };
	if (description.length > MAX_DESC) return { err: [400, 'validation_error', `description must be ≤${MAX_DESC} chars`] };

	// Resolve the target profession (and, for hire, the routed-to citizen).
	let profession = String(body.profession || '').toLowerCase() || null;
	let target = null;
	let minReputation = Number.isFinite(+body.minReputation) ? Math.max(0, Math.floor(+body.minReputation)) : 0;
	if (hire) {
		if (!body.citizenId) return { err: [400, 'validation_error', 'hire requires citizenId'] };
		// agora_citizens.id is a uuid column: a non-uuid value makes Postgres throw
		// 22P02 and the request 500s. The user-visible outcome is the same as a
		// well-formed id nobody holds, so answer it the same way.
		if (!isUuid(String(body.citizenId))) return { err: [404, 'not_found', 'no such citizen to hire'] };
		[target] = await sql`select * from agora_citizens where id = ${String(body.citizenId)} limit 1`;
		if (!target) return { err: [404, 'not_found', 'no such citizen to hire'] };
		profession = profession || target.profession;
		// Route so the target qualifies: minReputation must not exceed theirs.
		minReputation = Math.min(minReputation, Number(target.reputation || 0));
	}
	if (!profession || !(profession in PROFESSION_BITS)) {
		return { err: [400, 'validation_error', `profession must be one of: ${Object.keys(PROFESSION_BITS).join(', ')}`] };
	}

	const amountAtomic = resolveRewardAtomic(body, cluster);
	if (amountAtomic == null) {
		return { err: [400, 'validation_error', cluster === 'mainnet' ? 'rewardThree must be > 0' : 'rewardSol must be > 0'] };
	}

	// Per-user spend policy + mainnet gate (server-side, ledger-backed).
	const { citizen } = await ensureHumanCitizen({ user, cluster });
	// Reserve the daily-cap headroom BEFORE the chain call. The projection this
	// cap meters against is only written after the escrow lands, so a plain check
	// left a window in which two concurrent posts could both spend the same
	// headroom (security review L6). The hold counts until the projection takes
	// over, and the finally below frees it on every path that never escrows.
	const policy = await reservePostSpend({ citizenId: citizen.id, cluster, amountAtomic, requestedCluster });
	if (!policy.ok) return { err: [policy.status, policy.code, policy.message, policy.detail] };
	const hold = policy.reservationId;
	let settled = false;
	try {
		// Register on-chain (lazy) + fund the reward escrow on devnet.
		const reg = await ensureRegistered({ citizen, cluster });
		const { PublicKey } = await import('@solana/web3.js');

		const createArgs = {
			creatorAgentId: reg.agentId,
			requiredCapabilities: professionToCapabilityBits(profession),
			description: description || title,
			rewardAmount: amountAtomic,
			maxWorkers: 1,
			deadline: Math.floor(Date.now() / 1000) + Math.max(1, Math.min(720, Number(body.deadlineHours) || 24)) * 3600,
			taskType: 'Exclusive',
			minReputation,
		};

		if (cluster === 'mainnet') {
			const { getAssociatedTokenAddressSync } = await import('@solana/spl-token');
			createArgs.rewardMint = new PublicKey(TOKEN_MINT);
			createArgs.creatorTokenAccount = getAssociatedTokenAddressSync(new PublicKey(TOKEN_MINT), reg.signer.publicKey, false);
			// Real money: check the $THREE the escrow will actually debit before we
			// sign, so "you don't hold enough $THREE" is a designed state and not an
			// SPL transfer failure surfaced as a 502.
			const held = await citizenBalances(citizen, cluster).catch(() => ({ three: null }));
			const needThree = Number(amountAtomic) / Number(THREE_ATOMICS_PER_TOKEN);
			if (held.three != null && held.three < needThree) {
				return {
					err: [409, 'insufficient_funds',
						`This bounty escrows ${rewardLabel(amountAtomic, cluster)} and your Agora wallet holds ${held.three.toLocaleString('en-US')} $THREE. Send $THREE to your wallet address, then post again.`,
						{ walletAddress: held.address, asset: '$THREE', cluster, needed: needThree, have: held.three }],
				};
			}
		} else {
			// Devnet native-SOL escrow: top up, then gate on the real balance so a
			// throttled faucet reads as "fund this address", not a 500.
			const needLamports = Number(amountAtomic) + 10_000_000;
			await ensureDevnetBalance(reg.client.connection, reg.signer, needLamports);
			await requireFunded({
				connection: reg.client.connection, address: reg.signer.publicKey,
				neededLamports: needLamports, cluster, purpose: 'escrow this bounty',
			});
		}

		const { createAgenCTask } = await import('@three-ws/solana-agent');
		let created;
		try {
			created = await createAgenCTask(reg.client, createArgs);
		} catch (e) {
			// Two very different failures hide behind one throw, and telling them apart
			// matters because the reward is real money. A rejected transaction moved
			// nothing and is safe to retry. A CONFIRM TIMEOUT means we simply stopped
			// waiting: the escrow may well have funded, and a blind retry would escrow
			// the reward a second time. The task id is generated inside the SDK, so a
			// bare signature is not enough to rebuild the bounty here; say so plainly
			// and point them at their own bounty list rather than guessing.
			const landed = await recoverTimedOutSignature(reg.client.connection, e).catch(() => null);
			if (landed) {
				return {
					err: [409, 'escrow_pending',
						'Your bounty was submitted but confirmation timed out, so it may already be live. Check your open bounties before posting it again.',
						{ txSignature: landed.txSignature, explorerUrl: explorerTx(landed.txSignature, cluster), cluster }],
				};
			}
			return { err: [502, 'escrow_failed', 'the bounty was not posted, no funds moved'], cause: e };
		}

		const taskPda = created.taskPda.toBase58();
		const taskIdHex = Buffer.from(created.taskId).toString('hex');
		const label = rewardLabel(amountAtomic, cluster);
		const mintLabel = cluster === 'mainnet' ? '$THREE' : null;

		const narrative = hire
			? `${citizen.display_name} hired ${target.display_name} for a ${profession} task (${label}).`
			: `${citizen.display_name} posted a ${profession} bounty (${label}).`;

		await projectActivity({
			citizenId: citizen.id,
			kind: hire ? 'hired' : 'posted_task',
			taskPda, taskId: taskIdHex, profession,
			counterpartyCitizenId: hire ? target.id : null,
			amountAtomic: amountAtomic.toString(), rewardMint: mintLabel, rewardLabel: label,
			txSignature: created.txSignature, narrative,
			worldX: citizen.home_x, worldZ: citizen.home_z,
			meta: { minReputation, maxWorkers: 1 },
		});
		// The projection now carries this spend, so the hold can stop counting.
		// Settled AFTER the write, never before: overlapping for a moment
		// overcounts, which is the safe direction, while settling first would
		// leave a gap a racing post could slip through.
		await settlePostSpend(hold, { taskPda, txSignature: created.txSignature });
		settled = true;
		await bumpCitizenStats(citizen.id, { incPosted: 1, status: 'idle' });

		const { publishFeedEvent } = await import('../_lib/feed.js');
		publishFeedEvent({
			type: hire ? 'agora-hired' : 'agora-task-posted',
			actor: citizen.display_name.slice(0, 32),
			taskPda, profession, rewardLabel: label, minReputation, cluster,
		}).catch(() => {});

		return {
			ok: true,
			body: {
				ok: true,
				taskPda, taskId: taskIdHex,
				txSignature: created.txSignature,
				explorerUrl: explorerTx(created.txSignature, cluster),
				reward: { amountAtomic: amountAtomic.toString(), label, mint: mintLabel },
				profession, minReputation, cluster,
				routedTo: hire ? { citizenId: target.id, name: target.display_name } : null,
				taskUrl: `/api/agenc/get-task?taskPda=${taskPda}&cluster=${cluster}&lifecycle=1`,
			},
		};
	} finally {
		// Anything that returned or threw without escrowing gives the headroom back
		// immediately rather than waiting for the hold to age out.
		if (!settled) await releasePostSpend(hold);
	}
}

// ── action handlers ───────────────────────────────────────────────────────────

async function actJoin(user, body) {
	const cluster = resolveCluster(body.cluster);
	const { citizen, created } = await ensureHumanCitizen({ user, cluster });
	const me = await shapeMe(citizen, cluster);
	return { ok: true, body: { ok: true, created, me } };
}

async function actPostTask(user, body) {
	const r = await postTaskCore({ user, body, requestedCluster: body.cluster, hire: false });
	return r.err ? { err: r.err } : { ok: true, body: r.body };
}

async function actHire(user, body) {
	const r = await postTaskCore({ user, body, requestedCluster: body.cluster, hire: true });
	return r.err ? { err: r.err } : { ok: true, body: r.body };
}

async function actClaim(user, body) {
	const cluster = resolveCluster(body.cluster);
	const taskPda = String(body.taskPda || '').trim();
	if (!taskPda) return { err: [400, 'validation_error', 'taskPda is required'] };
	// Shape-check before any wallet or chain work: a malformed PDA would otherwise
	// throw inside the claim call and read as a 502 outage, after we had already
	// registered this citizen on-chain for a request that could never succeed.
	if (!isValidSolanaAddress(taskPda)) return { err: [400, 'validation_error', 'taskPda must be a base58 Solana address'] };

	const { citizen } = await ensureHumanCitizen({ user, cluster });

	// AgenC forbids claiming your own bounty (SelfTaskNotAllowed). Our projection
	// already knows who posted it, so answer from there instead of spending a
	// round trip to be told no by the program.
	const [ownPost] = await sql`
		select 1 from agora_activity
		where task_pda = ${taskPda} and citizen_id = ${citizen.id}
		  and kind in ('posted_task', 'hired') limit 1`;
	if (ownPost) {
		return { err: [409, 'self_task_not_allowed', 'You posted this bounty, so you cannot claim it yourself. It stays on the board until another citizen takes it on.'] };
	}

	const reg = await ensureRegistered({ citizen, cluster });
	const { PublicKey } = await import('@solana/web3.js');
	const { claimAgenCTask } = await import('@three-ws/solana-agent');

	let claim;
	try {
		claim = await claimAgenCTask(reg.client, { taskPda: new PublicKey(taskPda), workerAgentId: reg.agentId });
	} catch (e) {
		claim = await recoverTimedOutSignature(reg.client.connection, e).catch(() => null);
		if (!claim) {
			const rejected = onchainRejection(e);
			if (rejected) return { err: [409, rejected.code, rejected.message] };
			return { err: [502, 'claim_failed', 'could not claim the task'], cause: e };
		}
	}

	await projectActivity({
		citizenId: citizen.id, kind: 'claimed_task', taskPda,
		txSignature: claim.txSignature,
		narrative: `${citizen.display_name} claimed a task to work on it.`,
		worldX: citizen.home_x, worldZ: citizen.home_z,
	});
	await bumpCitizenStats(citizen.id, { status: 'busy' });

	const { publishFeedEvent } = await import('../_lib/feed.js');
	publishFeedEvent({
		type: 'agora-task-claimed', actor: citizen.display_name.slice(0, 32),
		citizenId: citizen.id, agentPda: reg.agentPda, taskPda,
		txSig: claim.txSignature, explorerUrl: explorerTx(claim.txSignature, cluster),
		narrative: `${citizen.display_name} claimed a task`,
	}).catch(() => {});

	return { ok: true, body: { ok: true, taskPda, txSignature: claim.txSignature, explorerUrl: explorerTx(claim.txSignature, cluster), cluster } };
}

async function actComplete(user, body) {
	const cluster = resolveCluster(body.cluster);
	const taskPda = String(body.taskPda || '').trim();
	if (!taskPda) return { err: [400, 'validation_error', 'taskPda is required'] };
	// Same boundary as claim: `new PublicKey(taskPda)` below throws outside every
	// try, so an unvalidated PDA collapses a plain typo into an opaque 500.
	if (!isValidSolanaAddress(taskPda)) return { err: [400, 'validation_error', 'taskPda must be a base58 Solana address'] };

	const deliverable = String(body.deliverable || body.deliverableUrl || '').trim();
	if (!deliverable) return { err: [400, 'validation_error', 'deliverable (text or url) is required'] };
	if (deliverable.length > MAX_DELIVERABLE) return { err: [400, 'validation_error', `deliverable must be ≤${MAX_DELIVERABLE} chars`] };

	const proofHash = proofHashFor(deliverable);
	const { citizen } = await ensureHumanCitizen({ user, cluster });
	const reg = await ensureRegistered({ citizen, cluster });
	const { PublicKey } = await import('@solana/web3.js');
	const { completeAgenCTask, getAgenCTask, getAgenCAgent } = await import('@three-ws/solana-agent');

	const pda = new PublicKey(taskPda);
	// resultData is an on-chain [u8;64]; size it by BYTES, not characters, so a
	// multibyte deliverable (emoji/CJK/accents) can't overflow Anchor's fixed slot
	// and fail serialization. Zero-padded; the first byte is non-zero (deliverable
	// is validated non-empty above) so it's never the rejected all-zero slot.
	const resultData = Buffer.alloc(64);
	Buffer.from(deliverable, 'utf8').copy(resultData, 0, 0, 64);
	let completion;
	try {
		completion = await completeAgenCTask(reg.client, {
			taskPda: pda, workerAgentId: reg.agentId, proofHash, resultData,
		});
	} catch (e) {
		// The proof may well be on-chain: a 30s confirm timeout on a throttled devnet
		// is routine, and reporting failure would strand a completion the citizen
		// genuinely earned (escrow paid, reputation moved) outside the world.
		completion = await recoverTimedOutSignature(reg.client.connection, e).catch(() => null);
		if (!completion) {
			const rejected = onchainRejection(e);
			// The claim account being gone usually means this proof ALREADY landed and
			// only the projection is missing, so read the task before calling it a
			// failure. The chain stamps completedAt, and the completing transaction is
			// the worker's own signature at that block time, which is evidence enough
			// to project the completion the citizen genuinely earned.
			if (rejected?.code === 'account_not_initialized') {
				const settled = await getAgenCTask(reg.client, pda).catch(() => null);
				const sig = settled?.completedAt
					? await findCompletionSignature(reg.client.connection, reg.signer.publicKey, settled.completedAt).catch(() => null)
					: null;
				if (sig) completion = { txSignature: sig, recovered: true };
			}
		}
		if (!completion) {
			const rejected = onchainRejection(e);
			if (rejected) return { err: [409, rejected.code, rejected.message] };
			return { err: [502, 'complete_failed', 'could not submit the proof'], cause: e };
		}
	}

	// Re-read the chain for the real reward + reputation — never invent them.
	const task = await getAgenCTask(reg.client, pda).catch(() => null);
	const onchainAgent = await getAgenCAgent(reg.client, new PublicKey(reg.agentPda)).catch(() => null);
	const rewardAmount = task?.rewardAmount != null ? BigInt(task.rewardAmount) : 0n;
	const label = rewardLabel(rewardAmount, cluster);
	const mintLabel = cluster === 'mainnet' ? '$THREE' : null;
	const repAfter = onchainAgent?.reputation != null ? Number(onchainAgent.reputation) : citizen.reputation;
	const deliverableUrl = /^https?:\/\//i.test(deliverable) ? deliverable : null;

	await projectActivity({
		citizenId: citizen.id, kind: 'completed_task', taskPda,
		proofHash, txSignature: completion.txSignature, deliverableUrl,
		amountAtomic: rewardAmount.toString(), rewardMint: mintLabel, rewardLabel: label,
		repBefore: citizen.reputation, repAfter,
		narrative: `${citizen.display_name} completed a task with an accepted proof (rep ${citizen.reputation} → ${repAfter}).`,
		worldX: citizen.home_x, worldZ: citizen.home_z,
	});
	// 'earned' cites the SAME completion tx — projectActivity is keyed by
	// (citizen, kind, tx) so this is a distinct, idempotent row.
	await projectActivity({
		citizenId: citizen.id, kind: 'earned', taskPda,
		amountAtomic: rewardAmount.toString(), rewardMint: mintLabel, rewardLabel: label,
		txSignature: completion.txSignature,
		narrative: `${citizen.display_name} earned ${label}.`,
	});
	await bumpCitizenStats(citizen.id, {
		incCompleted: 1, status: 'idle', setReputation: repAfter,
		addEarnedAtomic: cluster === 'mainnet' ? rewardAmount.toString() : null,
	});

	const { publishFeedEvent } = await import('../_lib/feed.js');
	publishFeedEvent({
		type: 'agora-task-completed', actor: citizen.display_name.slice(0, 32),
		citizenId: citizen.id, agentPda: reg.agentPda, taskPda, proofHash,
		txSig: completion.txSignature, explorerUrl: explorerTx(completion.txSignature, cluster),
		narrative: `${citizen.display_name} completed a task`,
	}).catch(() => {});
	if (rewardAmount > 0n) {
		publishFeedEvent({
			type: 'agora-earned', actor: citizen.display_name.slice(0, 32),
			citizenId: citizen.id, agentPda: reg.agentPda, rewardLabel: label,
			txSig: completion.txSignature, explorerUrl: explorerTx(completion.txSignature, cluster),
			narrative: `${citizen.display_name} earned ${label}`,
		}).catch(() => {});
	}

	return {
		ok: true,
		body: {
			ok: true, taskPda, proofHash: `0x${proofHash}`,
			txSignature: completion.txSignature, explorerUrl: explorerTx(completion.txSignature, cluster),
			reward: { amountAtomic: rewardAmount.toString(), label, mint: mintLabel },
			reputation: repAfter, cluster,
		},
	};
}

async function actVouch(user, body) {
	const cluster = resolveCluster(body.cluster);
	const subjectId = String(body.subjectCitizenId || body.citizenId || '').trim();
	if (!subjectId) return { err: [400, 'validation_error', 'subjectCitizenId is required'] };
	// uuid column, same 22P02 trap as hire: a malformed id is simply nobody.
	if (!isUuid(subjectId)) return { err: [404, 'not_found', 'no such citizen to vouch for'] };

	const { citizen } = await ensureHumanCitizen({ user, cluster });
	if (subjectId === citizen.id) return { err: [400, 'validation_error', 'you cannot vouch for yourself'] };

	const [subject] = await sql`select id, display_name, agenc_agent_pda from agora_citizens where id = ${subjectId} limit 1`;
	if (!subject) return { err: [404, 'not_found', 'no such citizen to vouch for'] };

	// Dedupe per ordered (voucher, subject): refresh an existing edge, never stack.
	const [existing] = await sql`
		select id from agora_vouches where voucher_citizen_id = ${citizen.id} and subject_citizen_id = ${subject.id} limit 1`;

	const reg = await ensureRegistered({ citizen, cluster });
	const note = String(body.note || '').slice(0, 280);
	const taskPda = body.taskPda ? String(body.taskPda).trim() : null;
	const memo = `agora:vouch v1 by=${reg.agentPda} for=${subject.agenc_agent_pda || subject.id}${taskPda ? ` task=${taskPda}` : ''}`;

	let sig;
	try {
		sig = await sendOnchainAttestation({ cluster, signer: reg.signer, memo });
	} catch (e) {
		return { err: [502, 'attestation_failed', 'the vouch was not recorded on-chain'], cause: e };
	}

	const [edge] = existing
		? await sql`
			update agora_vouches set tx_signature = ${sig}, cluster = ${cluster}, note = ${note || null},
			    task_pda = ${taskPda}, updated_at = now()
			where id = ${existing.id} returning id`
		: await sql`
			insert into agora_vouches
				(voucher_citizen_id, subject_citizen_id, voucher_user_id, task_pda, tx_signature, cluster, note)
			values (${citizen.id}, ${subject.id}, ${user.id}, ${taskPda}, ${sig}, ${cluster}, ${note || null})
			returning id`;

	await projectActivity({
		citizenId: citizen.id, kind: 'vouched', counterpartyCitizenId: subject.id,
		taskPda, txSignature: sig,
		narrative: `${citizen.display_name} vouched for ${subject.display_name}.`,
		worldX: citizen.home_x, worldZ: citizen.home_z,
	});

	const { publishFeedEvent } = await import('../_lib/feed.js');
	publishFeedEvent({
		type: 'agora-vouched', actor: citizen.display_name.slice(0, 32),
		citizenId: citizen.id, subjectCitizenId: subject.id, subject: subject.display_name.slice(0, 32),
		txSig: sig, explorerUrl: explorerTx(sig, cluster),
		narrative: `${citizen.display_name} vouched for ${subject.display_name}`,
	}).catch(() => {});

	return {
		ok: true,
		body: { ok: true, edgeId: edge.id, refreshed: !!existing, txSignature: sig, explorerUrl: explorerTx(sig, cluster), subject: { id: subject.id, name: subject.display_name }, cluster },
	};
}

const ACTIONS = {
	join: actJoin,
	'post-task': actPostTask,
	hire: actHire,
	claim: actClaim,
	complete: actComplete,
	vouch: actVouch,
};

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const auth = await authWrite(req, res, { spend: true });
	if (!auth) return; // authWrite already wrote 401/403
	const { userId } = auth;

	const rl = await limits.mcpAgentPay(userId);
	if (!rl.success) return rateLimited(res, rl, 'agora action rate limit exceeded');

	const body = (await readJson(req)) || {};
	const action = String(body.action || '').toLowerCase();
	const handler = ACTIONS[action];
	if (!handler) return error(res, 400, 'validation_error', `unknown action "${action}"`);

	const user = await loadUser(userId);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	// Idempotency-Key (optional). Durable across serverless invocations so a
	// retried escrow/claim/complete returns the first result rather than re-running.
	const idemKey = (req.headers['idempotency-key'] || '').toString().trim().slice(0, 200) || null;
	const hash = reqHash(action, body);
	const idem = await idemBegin(userId, action, idemKey, hash);
	if (idem.replay) return json(res, 200, idem.replay);
	if (idem.conflict) return error(res, 409, 'idempotency_conflict', 'this Idempotency-Key was used with a different request');
	if (idem.inflight) return error(res, 409, 'idempotency_inflight', 'a request with this Idempotency-Key is still in progress');

	try {
		const result = await handler(user, body);
		if (result.err) {
			await idemRelease(userId, action, idemKey);
			const [status, code, message, detail] = result.err;
			const extra = { ...(detail || {}) };
			// A ≥500 carries an upstream on-chain cause: log + capture it server-side
			// under a correlation id and return only that ref — never the raw RPC
			// error string, which can embed the keyed RPC URL (HELIUS_API_KEY).
			if (result.cause && status >= 500 && rpcUnavailable(result.cause)) {
				return error(res, 503, 'rpc_unavailable', RPC_OUTAGE_MESSAGE, { retryable: true });
			}
			if (result.cause && status >= 500) {
				extra.ref = reportServerError(result.cause, { code, status, context: { action } });
			}
			return error(res, status, code, message, extra);
		}
		await idemFinish(userId, action, idemKey, result.body);
		return json(res, 200, result.body);
	} catch (err) {
		await idemRelease(userId, action, idemKey);
		// A typed 4xx thrown from the service layer is a DESIGNED state the user can
		// act on (no custodial wallet yet, a dry devnet wallet the faucet wouldn't
		// top up). Surface it verbatim; only genuinely unexpected failures collapse
		// into an opaque 500 with a support ref.
		const status = Number(err?.status);
		if (Number.isInteger(status) && status >= 400 && status < 500) {
			return error(res, status, err.code || 'agora_act_error', err.message, err.detail || {});
		}
		if (rpcUnavailable(err)) {
			return error(res, 503, 'rpc_unavailable', RPC_OUTAGE_MESSAGE, { retryable: true });
		}
		// Redact before logging: an unexpected failure here is usually an on-chain
		// RPC error whose message carries the keyed endpoint URL.
		console.error('[agora/act] error', action, redactSecrets(err?.message));
		return serverError(res, 500, 'agora_act_error', err);
	}
});