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.

9.4 KB
Raw Blame
// agora-citizens — environment + runtime configuration for the life engine.
// Validated once at boot so a misconfigured worker fails loudly instead of
// running half a config. Long-lived process (NOT a Vercel cron): it registers a
// fleet of devnet AgenC agents, then runs each citizen's daily loop on its own
// jittered cadence, projecting every on-chain action into agora_citizens /
// agora_activity and the live feed.
//
//   AGORA_DRY_RUN=1   — plan only: read the board, decide, but never sign a tx
//                       or write the DB. Inspect the loop safely.
//   AGORA_ONCE=1      — run a single tick per citizen, then exit (CI / manual).
//   AGORA_MAX_CITIZENS=N — cap the fleet (faucet-friendly local runs).
//   AGORA_DEVNET_FUNDER_SECRET : funded devnet wallet used to top signers up
//                       when the public faucet is dry (it usually is).
//
// Guardrails: devnet rewards are native SOL (synthetic plumbing — never another
// real token). $THREE is the only coin Agora promotes; on mainnet the reward
// label is '$THREE'. See docs/agora.md and CLAUDE.md.

import { resolveDatabaseUrl } from '../../api/_lib/env.js';

function req(name) {
	const v = process.env[name];
	if (!v || !String(v).trim()) throw new Error(`[agora-citizens] missing required env var: ${name}`);
	return String(v).trim();
}
function opt(name, def = undefined) {
	const v = process.env[name];
	return v == null || v === '' ? def : String(v).trim();
}
function num(name, def) {
	const raw = process.env[name];
	if (raw == null || raw === '') return def;
	const n = Number(raw);
	return Number.isFinite(n) ? n : def;
}
function bool(name, def = false) {
	const raw = process.env[name];
	if (raw == null || raw === '') return def;
	return /^(1|true|yes|on)$/i.test(String(raw).trim());
}

export function loadConfig() {
	const dryRun = bool('AGORA_DRY_RUN', false);

	// DATABASE_URL is the projection sink. A dry run reads the board + plans but
	// never writes, so it can run without a DB — handy for inspecting the loop
	// with zero side effects. Resolve from DATABASE_URL or any standard
	// Vercel-Postgres/Neon alias (POSTGRES_URL, NEON_DATABASE_URL, …) so the worker
	// connects wherever the integration injected the string — matching db.js.
	const databaseUrl = resolveDatabaseUrl() || '';
	if (!dryRun && !databaseUrl) {
		throw new Error('[agora-citizens] missing required env var: DATABASE_URL (or a POSTGRES_URL/NEON_DATABASE_URL alias)');
	}

	const cluster = (opt('AGORA_CLUSTER', 'devnet')).toLowerCase();
	if (cluster !== 'devnet' && cluster !== 'mainnet') {
		throw new Error(`[agora-citizens] AGORA_CLUSTER must be devnet|mainnet, got "${cluster}"`);
	}
	// Mainnet is escrowed in $THREE and is out of scope for the devnet life
	// engine — refuse to run live there so a stray env can't move real value.
	if (cluster === 'mainnet' && !dryRun) {
		throw new Error('[agora-citizens] mainnet life-engine is out of scope for this worker (devnet only). Set AGORA_CLUSTER=devnet.');
	}

	const rpcUrl = opt('AGENC_DEVNET_RPC_URL') || opt('SOLANA_RPC_URL_DEVNET') || opt('AGENC_RPC_URL') || undefined;

	return {
		cluster,
		rpcUrl,
		dryRun,
		// Single tick per citizen then exit — for CI smoke tests and manual runs.
		once: bool('AGORA_ONCE', false),
		// World-seed mode: project real rigged agents into the Commons as citizens
		// (real avatar, canonical AgenC id derived offline, profession from real
		// signals) WITHOUT any on-chain registration, then exit. No SOL needed — the
		// world fills instantly; the funded life-engine registers + works them later.
		seedOnly: bool('AGORA_SEED_ONLY', false),
		// How many rigged agents to project in a world-seed pass. The DB holds all of
		// them; the 3D renderer shows a bounded, nearest subset.
		seedLimit: Math.max(1, Math.min(2000, num('AGORA_SEED_LIMIT', 120))),
		// Before a world-seed, clear the previous UNREGISTERED world-seed citizens so
		// the population refreshes cleanly (never touches on-chain-registered citizens
		// or humans). Default on — a seed pass is the authoritative pending population.
		seedReset: bool('AGORA_SEED_RESET', true),
		databaseUrl,

		// Fleet size cap. The roster supplies the candidate citizens (seeded from
		// real platform agents where possible); this bounds how many we actually
		// run so a local devnet run respects faucet limits.
		maxCitizens: Math.max(1, Math.min(50, num('AGORA_MAX_CITIZENS', 4))),
		// Floor on the fleet when seeding can't find enough real agents — fill with
		// standalone roster citizens so the world is never empty.
		minCitizens: Math.max(1, num('AGORA_MIN_CITIZENS', 3)),
		// Run the standalone founding workforce ONLY, never the platform-agent seed.
		// Two engines against one DB otherwise pick the same first-N platform agents
		// and drive one set of keypairs concurrently. Use for an isolated devnet
		// fleet, a local run, or a CI smoke that must not touch real agent identities.
		standaloneOnly: bool('AGORA_STANDALONE_ONLY', false),

		// Per-citizen loop cadence. Each citizen ticks every base ± jitter so the
		// fleet doesn't stampede the RPC / faucet in lockstep.
		tickBaseMs: Math.max(5_000, num('AGORA_TICK_MS', 45_000)),
		tickJitterMs: Math.max(0, num('AGORA_TICK_JITTER_MS', 20_000)),

		// Devnet work supply. With no human/agent bounties yet (Task 03), an
		// internal dispatcher keeps a small pool of real on-chain Fetcher tasks
		// open so citizens have genuine work to claim → do → prove → earn. This is
		// devnet plumbing (native SOL rewards), not the Task-03 bounty product; it
		// posts no agora `posted_task` projection and escrows no $THREE. Disable to
		// run citizens against externally-supplied tasks only.
		dispatchTasks: bool('AGORA_DISPATCH_TASKS', cluster === 'devnet'),
		minOpenTasks: Math.max(0, num('AGORA_MIN_OPEN_TASKS', 3)),
		maxOpenTasks: Math.max(1, num('AGORA_MAX_OPEN_TASKS', 8)),
		taskRewardLamports: Math.max(1, num('AGORA_TASK_REWARD_LAMPORTS', 1_000_000)), // 0.001 SOL devnet
		taskDeadlineSecs: Math.max(300, num('AGORA_TASK_DEADLINE_SECS', 3_600)),

		// Arena (Competitive) + Guild (Collaborative) demand (Task 09). A patron
		// occasionally posts a multi-worker task so several citizens race (Arena —
		// first valid proof wins the whole escrow) or collaborate (Guild — the
		// reward splits across contributors). Both are real on-chain multi-worker
		// tasks; disable either to keep the board single-worker.
		enableArena: bool('AGORA_ENABLE_ARENA', cluster === 'devnet'),
		enableGuild: bool('AGORA_ENABLE_GUILD', cluster === 'devnet'),
		// Slots per multi-worker task. Clamped to the AgenC u8 range with a sane
		// upper bound so one task can't invite the whole fleet.
		arenaMaxWorkers: Math.max(2, Math.min(8, num('AGORA_ARENA_MAX_WORKERS', 3))),
		guildMaxWorkers: Math.max(2, Math.min(8, num('AGORA_GUILD_MAX_WORKERS', 3))),
		// The prize pool scales up from the base reward — a juicy Arena purse and a
		// Guild pool worth splitting. The patron locks the whole pool once (escrow);
		// Arena pays the winner all of it, Guild splits it across contributors.
		arenaRewardMultiplier: Math.max(1, num('AGORA_ARENA_REWARD_MULT', 6)),
		guildRewardMultiplier: Math.max(1, num('AGORA_GUILD_REWARD_MULT', 6)),
		// Arena carries a reputation gate (a juicy purse belongs to proven racers);
		// a Guild is open entry work so newcomers can contribute and climb. This is a
		// DELTA above AgenC's registration baseline (policy.js REPUTATION_BASELINE),
		// not an absolute: every registered agent already starts at the baseline, so
		// an absolute gate of 3 would let a citizen with zero completions straight in.
		// 100 is one completed task.
		arenaMinReputation: Math.max(0, num('AGORA_ARENA_MIN_REP', 100)),

		// Minimum on-chain stake per agent (AgenC protocol minAgentStake on devnet).
		stakeLamports: Math.max(1_000_000, num('AGORA_STAKE_LAMPORTS', 1_000_000)),

		// Faucet top-up: keep each signer above the threshold so a claim/complete
		// (which pays fees + locks reward) never fails for lack of SOL.
		topupThresholdLamports: Math.max(0, num('AGORA_TOPUP_THRESHOLD_LAMPORTS', 200_000_000)), // 0.2 SOL
		airdropLamports: Math.max(0, num('AGORA_AIRDROP_LAMPORTS', 1_000_000_000)), // 1 SOL
		// Devnet funder wallet (base58 or JSON-array secret key). The public faucet
		// answers 429 for long stretches from every IP we reach it from, which would
		// otherwise leave the fleet unfundable; when this is set the worker tops each
		// signer up from it with a real transfer instead, and only falls back to the
		// faucet if the funder is empty. Devnet test SOL only, never a mainnet key
		// the worker is expected to spend.
		funderSecret: opt('AGORA_DEVNET_FUNDER_SECRET') || '',
		// How far ABOVE the threshold a funder top-up lands, so a signer isn't
		// re-topped on every tick as fees nibble at it.
		funderTopupLamports: Math.max(0, num('AGORA_FUNDER_TOPUP_LAMPORTS', 100_000_000)), // 0.1 SOL

		// Where the citizen reads the world from. The board endpoint surfaces the
		// x402 bazaar (real Fetcher work) and any open AgenC tasks. The bridge is
		// the live work target the Fetcher fingerprints for its proof.
		apiBase: (opt('AGORA_API_BASE', 'https://three.ws')).replace(/\/+$/, ''),

		// Retry/backoff for every on-chain call. A single citizen's failure must
		// never halt the fleet.
		maxRetries: Math.max(0, num('AGORA_MAX_RETRIES', 4)),
		retryBaseMs: Math.max(200, num('AGORA_RETRY_BASE_MS', 1_500)),

		// Liveness heartbeat into bot_heartbeat (shared ops visibility). 0 disables.
		heartbeatMs: Math.max(0, num('AGORA_HEARTBEAT_MS', 30_000)),
	};
}