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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Agora economy — the read model for the living agent + human economy
// (see docs/agora.md). Serves the 3D Commons and any dashboard a real, honest
// view of the world: who the citizens are, what work is on the board, how the
// economy is pulsing, and a single citizen's living passport.
//
// On-chain (AgenC, by Tetsuo Corp) is the source of truth for identity, escrow,
// proof, stake and reputation; the agora_* tables are a projection that adds the
// world layer. These endpoints read both and NEVER fabricate: an empty economy
// returns an honest empty state, not sample citizens.
//
// Routes (all GET):
// /api/agora/citizens?profession=&status=&kind=&limit=
// The population — world-renderable citizens (projection).
// /api/agora/board?maxItems=&network=&maxPrice=&asset=
// (maxPrice is ATOMIC units: 10000 = 0.01 USDC. asset takes a symbol or
// the raw contract/mint address.)
// The live job board — open AgenC tasks (projected, still-open) + every
// x402 bazaar service as a claimable Fetcher job (real, populated now).
// /api/agora/pulse
// The economy ticker — citizen/profession breakdown, 24h flows, top
// earners, recent narration.
// /api/agora/passport?id=|agentPda=|agentId=
// One citizen's living passport — projection + live on-chain AgenC state +
// recent activity.
import { PublicKey } from '@solana/web3.js';
import { getAgent, getTaskLifecycleSummary, deriveTaskPda } from '@tetsuo-ai/sdk';
import { createHash } from 'node:crypto';
import { cors, json, method, error, rateLimited, wrap, serverError } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { sql } from '../_lib/db.js';
import { isUuid } from '../_lib/validate.js';
// Mask URL-embedded credentials (Helius/RPC `?api-key=`, bearer tokens) before an
// error message reaches a log sink: a Solana web3.js network error carries the
// keyed RPC URL, so logging its raw `.message` on a best-effort catch would spill
// HELIUS_API_KEY. Shared with act.js and the 5xx sink in http.js so every Agora
// path masks identically.
import { redactUrlSecrets as redactSecrets } from '../_lib/scrub-secrets.js';
import { Bazaar, filterByMaxPrice, filterByNetwork, parseAtomicAmount } from '../_lib/x402/bazaar-client.js';
import { assembleTaskLive } from '../_lib/agora-task-live.js';
// The projection stores a citizen's avatar as an `avatars.id`, so the Commons
// used to resolve every one of them with its own /api/avatars/<id> round trip
// (measured: 184 requests, ~40s, and they saturated the browser's connection
// pool badly enough that the economy ticker's own polls timed out). One batch
// read here hands the client a ready-to-load URL instead.
import { isBakedFresh } from '../_lib/avatars.js';
import { publicUrlOrNull } from '../_lib/r2.js';
// Terminal-kind sets + type helpers are the labour engine's single source of
// truth (workers/agora-citizens/policy.js) — the board's open lane and the
// reconcile sweep MUST agree on what "still open" means per task type, so we
// import the very same constants rather than re-declaring them here.
import { EXCLUSIVE_TERMINAL_KINDS, MULTI_TERMINAL_KINDS, isArenaType, isGuildType } from '../../workers/agora-citizens/policy.js';
// The only coin Agora denominates in. Devnet plumbing may use SOL or a synthetic
// placeholder; this is the mainnet $THREE mint, surfaced for clients that render
// a reward chip and want the canonical address.
const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
// Profession bit map — the labor market's type system over AgenC's u64 capability
// bitmap. Stable bits, each backed by a real platform skill (docs/agora.md). Open
// by design: add a bit + a backing skill, never a hardcoded allowlist.
const PROFESSIONS = [
{ bit: 0, key: 'fetcher', label: 'Fetcher', skill: 'x402 service call' },
{ bit: 1, key: 'sculptor', label: 'Sculptor', skill: 'text/image → rigged GLB (forge)' },
{ bit: 2, key: 'scribe', label: 'Scribe', skill: 'research / write (brain)' },
{ bit: 3, key: 'cartographer', label: 'Cartographer', skill: '3D scene / diorama' },
{ bit: 4, key: 'crier', label: 'Crier', skill: 'TTS / voice / audio2face' },
{ bit: 5, key: 'appraiser', label: 'Appraiser', skill: 'token / market intel' },
{ bit: 6, key: 'verifier', label: 'Verifier', skill: 're-derive proofHash + attest' },
{ bit: 7, key: 'namekeeper', label: 'Namekeeper', skill: '.sol / ENS resolve' },
];
function decodeProfessions(bits) {
let b;
try {
b = BigInt(bits ?? 0);
} catch {
return [];
}
return PROFESSIONS.filter((p) => (b & (1n << BigInt(p.bit))) !== 0n).map((p) => ({
key: p.key,
label: p.label,
bit: p.bit,
}));
}
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 status == null ? null : String(status);
}
function pickCluster(req) {
const c = (req.query?.cluster || '').toString().trim().toLowerCase();
return c === 'mainnet' ? 'mainnet' : 'devnet';
}
function pickRpc(cluster) {
const override = (process.env.AGENC_RPC_URL || '').trim();
if (override) return override;
if (cluster === 'devnet') return (process.env.SOLANA_RPC_URL_DEVNET || '').trim() || undefined;
return (process.env.SOLANA_RPC_URL || '').trim() || undefined;
}
function clampInt(v, def, min, max) {
const n = parseInt(v, 10);
if (!Number.isFinite(n)) return def;
return Math.max(min, Math.min(max, n));
}
// Batch-resolve the citizens' avatar ids to loadable GLB URLs.
//
// `agora_citizens.avatar_url` holds an `avatars.id`, not a URL, so a client that
// took the column at its name had to make one HTTP call per citizen just to
// learn where the model lives. Resolve the whole page in a single read.
//
// Only public/unlisted avatars resolve: a private one would need a presigned URL
// per citizen (a 10-minute credential minted 200 at a time for a world anyone can
// watch), so its citizen renders on the shared default rig instead. Returns a
// Map<avatarId, url>; ids that resolve to nothing are simply absent.
async function resolveCitizenAvatarUrls(rows) {
const ids = [...new Set(rows.map((r) => r.avatar_url).filter((v) => isUuid(v)))];
if (!ids.length) return new Map();
const avatars = await sql`
select id, storage_key, baked_storage_key, appearance, appearance_hash
from avatars
where id = any(${ids}::uuid[])
and deleted_at is null
and visibility in ('public', 'unlisted')
`;
const byId = new Map();
for (const a of avatars) {
const key = isBakedFresh(a) ? a.baked_storage_key : a.storage_key;
const url = publicUrlOrNull(key);
if (url) byId.set(String(a.id), url);
}
return byId;
}
// Shape a projected citizen row into the world-renderable object the 3D Commons
// and dashboards consume. `avatarUrls` is the batch map from
// resolveCitizenAvatarUrls; without it `avatarUrl` falls back to the raw stored
// value (an avatar id), which every client still resolves on its own.
function shapeCitizen(row, avatarUrls) {
const storedAvatar = row.avatar_url;
return {
id: row.id,
kind: row.kind,
displayName: row.display_name,
avatarId: row.avatar_id ?? (isUuid(storedAvatar) ? storedAvatar : null),
avatarUrl: avatarUrls?.get(String(storedAvatar)) ?? storedAvatar,
profession: row.profession,
professions: decodeProfessions(row.capability_bits),
capabilityBits: String(row.capability_bits ?? '0'),
status: row.status,
agenc: {
agentId: row.agenc_agent_id,
agentPda: row.agenc_agent_pda,
cluster: row.agenc_cluster,
identitySource: row.identity_source,
registered: !!row.agenc_agent_pda,
},
position: { x: row.pos_x, z: row.pos_z },
home: { x: row.home_x, z: row.home_z },
reputation: row.reputation,
stakeLamports: String(row.stake_lamports ?? '0'),
earnedThreeAtomic: String(row.earned_three_atomic ?? '0'),
tasksCompleted: row.tasks_completed,
tasksPosted: row.tasks_posted,
joinedAt: row.joined_at,
lastActiveAt: row.last_active_at,
};
}
async function handleCitizens(req, res) {
const q = req.query || {};
const limit = clampInt(q.limit, 200, 1, 1000);
const filters = [];
if (q.profession) filters.push(sql`profession = ${String(q.profession).toLowerCase()}`);
if (q.status) filters.push(sql`status = ${String(q.status).toLowerCase()}`);
if (q.kind === 'agent' || q.kind === 'human') filters.push(sql`kind = ${q.kind}`);
let where = sql``;
for (let i = 0; i < filters.length; i++) {
where = i === 0 ? sql` where ${filters[i]}` : sql`${where} and ${filters[i]}`;
}
const rows = await sql`
select * from agora_citizens
${where}
order by last_active_at desc
limit ${limit}
`;
const avatarUrls = await resolveCitizenAvatarUrls(rows);
const citizens = rows.map((row) => shapeCitizen(row, avatarUrls));
return json(res, 200, {
ok: true,
count: citizens.length,
citizens,
professions: PROFESSIONS,
// Honest empty state: the world is real; before the life-engine seeds it,
// it is simply unpopulated — the client renders "no citizens yet", never
// fabricated ones.
empty: citizens.length === 0,
fetchedAt: new Date().toISOString(),
});
}
// The live board has two lanes:
// 1. AgenC tasks our citizens posted that are STILL OPEN — both patron/human
// bounties (`posted_task`) AND agent-to-agent sub-task hires (`hired`), each
// a projection with no later claimed/completed/slashed row for the same PDA.
// Surfacing `hired` here is what lets ANOTHER citizen discover, claim and
// complete a sub-task — closing the multi-hop hire loop (Task 03). If the
// board hid `hired`, a sub-task would be orphaned: no worker could ever find
// it, and the reconcile hire-link (which joins on a real claim of the same
// PDA) would never fire.
// 2. Every x402 bazaar service, as a claimable Fetcher job (real + populated).
async function handleBoard(req, res) {
const q = req.query || {};
const maxItems = clampInt(q.maxItems, 60, 1, 500);
// `maxPrice` is an atomic cap. Reject a malformed one here: inside the bazaar
// lane's own try it would be swallowed as an outage and report an empty board
// (`empty:true`) while 500+ real services exist, a dishonest empty state.
if (q.maxPrice != null && parseAtomicAmount(q.maxPrice) === null) {
return error(res, 400, 'validation_error', 'maxPrice must be an atomic integer amount (e.g. 10000 = 0.01 USDC)');
}
// Lane 1 — open AgenC tasks (projected from real on-chain postings + hires).
// The "still open" predicate is PER TYPE: an Exclusive posting closes on its
// first claim; a multi-worker Arena / Guild stays live through its claims and
// per-contributor completions and closes only on a whole-task `settled` (or
// cancel / expire / slash). `workers_current` counts the distinct citizens who
// have engaged (claimed) so the board can show the fill (current/max) — this
// keeps a live race/guild visible-and-watchable while it fills.
const openTasks = await sql`
select a.kind, a.task_pda, a.task_id, a.profession, a.amount_atomic, a.reward_mint,
a.reward_label, a.narrative, a.created_at, a.tx_signature, a.meta,
c.id as creator_id, c.display_name as creator_name, c.agenc_cluster,
(select count(distinct cl.citizen_id) from agora_activity cl
where cl.task_pda = a.task_pda and cl.kind = 'claimed_task')::int as workers_current
from agora_activity a
join agora_citizens c on c.id = a.citizen_id
where a.kind in ('posted_task', 'hired')
and a.task_pda is not null
and a.created_at > now() - interval '7 days'
and not exists (
select 1 from agora_activity x
where x.task_pda = a.task_pda
and x.created_at >= a.created_at
and x.kind = any(
case when coalesce(a.meta->>'taskType', 'Exclusive') in ('Competitive', 'Collaborative')
then ${MULTI_TERMINAL_KINDS}::text[]
else ${EXCLUSIVE_TERMINAL_KINDS}::text[]
end
)
)
order by a.created_at desc
limit 200
`;
const tasks = openTasks.map((t) => {
const taskType = t.meta?.taskType ?? 'Exclusive';
const maxWorkers = Number(t.meta?.maxWorkers ?? 1);
const arena = isArenaType(taskType);
const guild = isGuildType(taskType);
return {
source: 'agenc',
// A `hired` row is a sub-task another citizen posted mid-job (agent-to-agent
// hiring); the UI can badge it and the worker can prefer/skip it, but it is a
// first-class claimable bounty either way.
kind: t.kind,
hire: t.kind === 'hired',
parentTaskPda: t.meta?.parentTaskPda ?? null,
taskPda: t.task_pda,
taskId: t.task_id,
profession: t.profession,
title: t.narrative,
reward: {
amountAtomic: t.amount_atomic != null ? String(t.amount_atomic) : null,
label: t.reward_label,
mint: t.reward_mint,
},
creator: { id: t.creator_id, name: t.creator_name },
cluster: t.agenc_cluster,
// Career-ladder gating surfaced from the posting's projection so workers
// (and the UI) know who may claim it without re-reading the chain.
minReputation: Number(t.meta?.minReputation ?? 0),
requiredCapabilities: t.meta?.requiredCapabilities != null ? String(t.meta.requiredCapabilities) : null,
taskType,
// Arena/Guild affordances (Task 09): the board badges the social structure
// and shows the live fill + prize; clicking opens the live race/guild view.
isArena: arena,
isGuild: guild,
multiWorker: arena || guild,
maxWorkers,
workersCurrent: Number(t.workers_current ?? 0),
workersLabel: maxWorkers > 1 ? `${Number(t.workers_current ?? 0)}/${maxWorkers}` : null,
tier: t.meta?.tier ?? null,
// Verification bounties carry the deliverable to re-derive; the worker reads
// this as job.target and works it as the Verifier (the trust loop).
target: t.meta?.target ?? null,
postedAt: t.created_at,
txSignature: t.tx_signature,
taskUrl: t.task_pda
? `/api/agenc/get-task?taskPda=${t.task_pda}&cluster=${t.agenc_cluster || 'devnet'}&lifecycle=1`
: null,
// The live multi-worker view (roster + settlement) for the Arena/Guild panel.
liveUrl: (arena || guild) && t.task_pda
? `/api/agora/task?taskPda=${t.task_pda}&cluster=${t.agenc_cluster || 'devnet'}`
: null,
};
});
// Lane 2 — x402 bazaar services as claimable Fetcher jobs (real, live).
let services = [];
const errors = [];
try {
const baz = new Bazaar();
const result = await baz.list({ type: 'http', limit: 200, maxItems });
let items = result.items || [];
if (q.network) items = filterByNetwork(items, String(q.network));
if (q.maxPrice) items = filterByMaxPrice(items, String(q.maxPrice), q.asset ? String(q.asset) : null);
services = items.map((it) => {
const accept = it.accepts?.[0] || null;
return {
source: 'x402',
profession: 'fetcher',
title: it.serviceName || it.toolName || it.resource,
description: it.description || null,
resource: it.resource,
tags: it.tags || [],
reward: accept
? {
amountAtomic: accept.amountAtomic,
label: accept.priceLabel,
currency: accept.asset,
network: accept.network,
}
: null,
rewardKind: 'x402_pay_to_endpoint',
facilitator: it.facilitator,
};
});
if (Array.isArray(result.errors)) errors.push(...result.errors);
} catch (err) {
// The board degrades gracefully — a bazaar outage drops lane 2, never 500s
// the whole board. AgenC tasks still render.
console.warn('[agora] bazaar lane failed:', redactSecrets(err?.message));
errors.push({ source: 'x402', error: redactSecrets(err?.message) || 'bazaar_unavailable' });
}
// `maxItems` bounds the BOARD, not just each facilitator's page loop. Bazaar
// pages per facilitator, so a union across several of them overshoots the cap
// (573 services for maxItems=60 before this slice) and every consumer (the
// 3D marker pool most of all) pays for a payload it never asked for. AgenC
// tasks are the scarce lane and always keep their slots; the x402 lane fills
// what's left, and the honest totals ship alongside so a client can say
// "showing 60 of 573" rather than silently pretending it has everything.
const serviceTotal = services.length;
const serviceBudget = Math.max(0, maxItems - tasks.length);
if (serviceTotal > serviceBudget) services = services.slice(0, serviceBudget);
res.setHeader('cache-control', 'public, max-age=15, stale-while-revalidate=60');
return json(res, 200, {
ok: true,
openTaskCount: tasks.length,
serviceCount: services.length,
serviceTotal,
maxItems,
truncated: serviceTotal > services.length,
tasks,
services,
errors,
empty: tasks.length === 0 && services.length === 0,
fetchedAt: new Date().toISOString(),
});
}
async function handlePulse(req, res) {
// Population + profession breakdown from the projection.
const [popRows, profRows, statusRows, flow24, completed24, recent, topEarners] = await Promise.all([
sql`select count(*)::int as total,
count(*) filter (where kind = 'agent')::int as agents,
count(*) filter (where kind = 'human')::int as humans,
count(*) filter (where last_active_at > now() - interval '24 hours')::int as active_24h
from agora_citizens`,
sql`select profession, count(*)::int as n from agora_citizens
where profession is not null group by profession order by n desc`,
sql`select status, count(*)::int as n from agora_citizens group by status`,
sql`select coalesce(sum(amount_atomic), 0) as three_atomic, count(*)::int as payouts
from agora_activity
where kind = 'earned' and reward_mint = '$THREE'
and created_at > now() - interval '24 hours'`,
sql`select count(*)::int as n from agora_activity
where kind = 'completed_task' and created_at > now() - interval '24 hours'`,
sql`select a.id, a.kind, a.narrative, a.reward_label, a.created_at,
a.task_pda, a.deliverable_url, c.id as citizen_id, c.display_name as actor, c.profession
from agora_activity a join agora_citizens c on c.id = a.citizen_id
order by a.created_at desc limit 12`,
sql`select id, display_name, profession, reputation, earned_three_atomic, tasks_completed
from agora_citizens
where earned_three_atomic > 0
order by earned_three_atomic desc limit 5`,
]);
const pop = popRows[0] || {};
const flow = flow24[0] || {};
return json(res, 200, {
ok: true,
coin: { symbol: '$THREE', mint: THREE_MINT },
population: {
total: pop.total || 0,
agents: pop.agents || 0,
humans: pop.humans || 0,
active24h: pop.active_24h || 0,
byStatus: Object.fromEntries((statusRows || []).map((r) => [r.status, r.n])),
byProfession: (profRows || []).map((r) => ({ profession: r.profession, count: r.n })),
},
economy: {
tasksCompleted24h: completed24[0]?.n || 0,
threeEarned24hAtomic: String(flow.three_atomic ?? '0'),
payouts24h: flow.payouts || 0,
},
topEarners: (topEarners || []).map((r) => ({
id: r.id,
displayName: r.display_name,
profession: r.profession,
reputation: r.reputation,
earnedThreeAtomic: String(r.earned_three_atomic ?? '0'),
tasksCompleted: r.tasks_completed,
})),
recent: (recent || []).map((r) => ({
id: r.id,
citizenId: r.citizen_id,
kind: r.kind,
actor: r.actor,
profession: r.profession,
narrative: r.narrative,
rewardLabel: r.reward_label,
taskPda: r.task_pda,
deliverableUrl: r.deliverable_url,
at: r.created_at,
})),
empty: (pop.total || 0) === 0,
fetchedAt: new Date().toISOString(),
});
}
async function handlePassport(req, res) {
const q = req.query || {};
let row;
if (q.id) {
// agora_citizens.id is a uuid column — a non-uuid id (scanner probes send
// arbitrary strings) would make Postgres throw 22P02 and 500. Same outcome
// as a well-formed-but-unknown id: no such citizen.
if (!isUuid(String(q.id))) return error(res, 404, 'not_found', 'no such citizen');
[row] = await sql`select * from agora_citizens where id = ${String(q.id)} limit 1`;
} else if (q.agentPda) {
[row] = await sql`select * from agora_citizens where agenc_agent_pda = ${String(q.agentPda)} limit 1`;
} else if (q.agentId) {
[row] = await sql`select * from agora_citizens where agenc_agent_id = ${String(q.agentId).toLowerCase()} limit 1`;
} else {
return error(res, 400, 'validation_error', 'provide id, agentPda, or agentId');
}
if (!row) return error(res, 404, 'not_found', 'no such citizen');
// One row, so the batch resolver is a single-id lookup here, and the passport's
// avatar field means the same thing as the roster's.
const citizen = shapeCitizen(row, await resolveCitizenAvatarUrls([row]));
// Live on-chain reconcile — the passport shows the chain's truth, not a stale
// snapshot. Best-effort: an RPC hiccup falls back to the projection snapshot.
let onchain = null;
if (row.agenc_agent_pda) {
try {
// Lazy: only the passport reconcile needs the write-SDK's client builder.
// Loading it here (not at module top) keeps board/pulse/citizens — which
// touch no Solana program — serving even if that SDK build is unavailable.
const { createAgenCClient } = await import('@three-ws/solana-agent');
const cluster = row.agenc_cluster === 'mainnet' ? 'mainnet' : 'devnet';
const client = createAgenCClient({ cluster, rpcUrl: pickRpc(cluster) });
const agent = await getAgent(client.program, new PublicKey(row.agenc_agent_pda));
if (agent) {
onchain = {
authority: agent.authority?.toBase58?.() ?? String(agent.authority),
status: agentStatusLabel(agent.status),
capabilities: String(agent.capabilities ?? '0'),
endpoint: agent.endpoint,
metadataUri: agent.metadataUri,
stakeAmount: String(agent.stakeAmount ?? '0'),
activeTasks: agent.activeTasks,
reputation: agent.reputation,
registeredAt: agent.registeredAt,
};
}
} catch (err) {
console.warn('[agora] passport on-chain read failed:', redactSecrets(err?.message));
}
}
const activity = await sql`
select id, kind, narrative, profession, task_pda, task_id, amount_atomic,
reward_mint, reward_label, tx_signature, proof_hash, deliverable_url,
rep_before, rep_after, created_at
from agora_activity
where citizen_id = ${row.id}
order by created_at desc
limit 25
`;
return json(res, 200, {
ok: true,
citizen,
onchain,
activity: activity.map((a) => ({
id: a.id,
kind: a.kind,
narrative: a.narrative,
profession: a.profession,
taskPda: a.task_pda,
taskId: a.task_id,
amountAtomic: a.amount_atomic != null ? String(a.amount_atomic) : null,
rewardMint: a.reward_mint,
rewardLabel: a.reward_label,
txSignature: a.tx_signature,
proofHash: a.proof_hash,
deliverableUrl: a.deliverable_url,
repBefore: a.rep_before,
repAfter: a.rep_after,
at: a.created_at,
})),
fetchedAt: new Date().toISOString(),
});
}
// AgenC TaskState enum → label (mirrors api/agenc/[action].js taskStateLabel).
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 state == null ? null : String(state);
}
function resolveTaskIdInput(s) {
const t = String(s).trim();
if (t.startsWith('0x') || t.startsWith('0X')) return Uint8Array.from(Buffer.from(t.slice(2), '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());
}
// Shape the posting (posted_task/hired) projection row for the live view.
function shapePosting(row) {
return {
taskPda: row.task_pda,
taskId: row.task_id,
citizenId: row.citizen_id,
poster: row.display_name,
profession: row.profession,
rewardLabel: row.reward_label,
rewardAmountAtomic: row.amount_atomic != null ? String(row.amount_atomic) : null,
rewardMint: row.reward_mint,
taskType: row.meta?.taskType ?? 'Exclusive',
maxWorkers: Number(row.meta?.maxWorkers ?? 1),
minReputation: Number(row.meta?.minReputation ?? 0),
tier: row.meta?.tier ?? null,
createdAt: row.created_at,
txSignature: row.tx_signature,
cluster: row.agenc_cluster,
narrative: row.narrative,
};
}
// The live view of a single multi-worker task (Arena / Guild) — Task 09. Reads the
// projection roster (who engaged + their real claim/complete txs + escrow-measured
// shares) AND the on-chain lifecycle (authoritative fill, state, timeline), then
// assembles them into one honest object the race/guild view renders. On-chain read
// is best-effort: an RPC hiccup degrades to the projection, never a 500.
async function handleTaskLive(req, res) {
const q = req.query || {};
const cluster = pickCluster(req);
// Resolve the task PDA. Prefer an explicit PDA; else derive from creator+taskId
// (needs the program id, so it goes through the read client).
let pda;
let client = null;
try {
const { createAgenCClient } = await import('@three-ws/solana-agent');
client = createAgenCClient({ cluster, rpcUrl: pickRpc(cluster) });
} catch (err) {
// SDK dist unavailable — we can still serve the projection if a PDA was given.
console.warn('[agora] task-live: SDK client unavailable, projection-only:', redactSecrets(err?.message));
}
try {
if (q.taskPda) {
pda = new PublicKey(String(q.taskPda).trim());
} else if (q.creator && q.taskId && client) {
const creator = new PublicKey(String(q.creator).trim());
pda = deriveTaskPda(creator, resolveTaskIdInput(q.taskId), client.programId);
} else {
return error(res, 400, 'validation_error', 'provide taskPda (or creator + taskId with the SDK available)');
}
} catch (err) {
return error(res, 400, 'validation_error', err.message);
}
const pdaStr = pda.toBase58();
// Projection: the posting + every engagement row for this task.
const [postingRows, activityRows] = await Promise.all([
sql`
select a.task_pda, a.task_id, a.citizen_id, a.profession, a.amount_atomic, a.reward_mint,
a.reward_label, a.narrative, a.created_at, a.tx_signature, a.meta,
c.display_name, c.agenc_cluster
from agora_activity a
join agora_citizens c on c.id = a.citizen_id
where a.task_pda = ${pdaStr} and a.kind in ('posted_task', 'hired')
order by a.created_at asc
limit 1
`,
sql`
select a.kind, a.citizen_id, a.profession, a.amount_atomic, a.reward_mint, a.reward_label,
a.tx_signature, a.proof_hash, a.deliverable_url, a.created_at, a.meta,
c.display_name, c.avatar_url
from agora_activity a
join agora_citizens c on c.id = a.citizen_id
where a.task_pda = ${pdaStr}
and a.kind in ('claimed_task', 'completed_task', 'earned', 'stood_down', 'settled')
order by a.created_at asc
limit 200
`,
]);
const posting = postingRows[0] ? shapePosting(postingRows[0]) : null;
// On-chain lifecycle (authoritative fill + timeline). Best-effort.
let chain = null;
if (client) {
try {
const summary = await getTaskLifecycleSummary(client.program, pda);
if (summary) {
chain = {
currentState: taskStateLabel(summary.currentState),
currentWorkers: summary.currentWorkers,
maxWorkers: summary.maxWorkers,
createdAt: summary.createdAt,
deadline: summary.deadline,
completedAt: summary.completedAt,
isExpired: !!summary.isExpired,
rewardAmount: summary.rewardAmount != null ? String(summary.rewardAmount) : null,
rewardMint: summary.rewardMint ? summary.rewardMint.toBase58?.() ?? String(summary.rewardMint) : null,
timeline: (summary.timeline || []).map((e) => ({
eventName: e.eventName,
timestamp: e.timestamp,
txSignature: e.txSignature ?? null,
actor: e.actor ? e.actor.toBase58?.() ?? String(e.actor) : null,
})),
};
}
} catch (err) {
console.warn('[agora] task-live on-chain read failed:', redactSecrets(err?.message));
}
}
// Map the raw activity rows into the shape the assembler expects (parsed meta).
const rows = activityRows.map((r) => ({
kind: r.kind,
citizen_id: r.citizen_id,
display_name: r.display_name,
profession: r.profession,
avatar_url: r.avatar_url,
tx_signature: r.tx_signature,
proof_hash: r.proof_hash,
deliverable_url: r.deliverable_url,
amount_atomic: r.amount_atomic,
reward_label: r.reward_label,
reward_mint: r.reward_mint,
created_at: r.created_at,
meta: r.meta || {},
}));
const view = assembleTaskLive({ taskPda: pdaStr, cluster, posting, activityRows: rows, chain });
if (!posting && !chain && view.roster.length === 0) {
return json(res, 404, { ok: false, error: 'not_found', taskPda: pdaStr, cluster });
}
res.setHeader('cache-control', 'public, max-age=4, stale-while-revalidate=15');
return json(res, 200, { ok: true, ...view, fetchedAt: new Date().toISOString() });
}
const HANDLERS = {
citizens: { methods: ['GET'], fn: handleCitizens },
board: { methods: ['GET'], fn: handleBoard },
pulse: { methods: ['GET'], fn: handlePulse },
passport: { methods: ['GET'], fn: handlePassport },
task: { methods: ['GET'], fn: handleTaskLive },
};
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,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));
// Match the sibling AgenC read model: a 429 here must carry retry-after +
// the limiter's own reason, so a poller (the 3D Commons refreshes board and
// pulse on a timer) can back off correctly and can tell a genuine quota hit
// from a fail-closed limiter outage.
if (!rl.success) return rateLimited(res, rl);
try {
return await route.fn(req, res);
} catch (err) {
console.error('[agora] unexpected error', redactSecrets(err?.message));
return serverError(res, 500, 'agora_error', err);
}
});