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.9 KB
Raw Blame
// @ts-check
// Autonomous coin launcher engine — the Memetic Launcher.
//
// The platform-side sibling of the circulation engine (circulation.js). Where
// circulation makes a pool of real agents tip/pay/trade one another every tick,
// THIS engine makes them mint coins on pump.fun on a cadence, each one riding a
// live cultural narrative (launcher-trends.js). Every launch flows through the
// SAME real code path a human owner uses — build metadata, then the agent signs
// its OWN pump.fun create — so each coin carries a real avatar identity and lands
// in /launches and the money feed as a genuine on-chain launch. No synthetic rows.
//
// The handshake (per launch):
//   1. pick a narrative-driven coin     (launcher-sources.pickSource)
//   2. pick the next agent in rotation  (launcher_queue, oldest-first, weighted)
//   3. fund: GLOBAL scope → master tops the agent up (launcher-funding);
//            USER scope   → self-funded, the agent's own wallet already holds the
//            SOL its owner deposited (liveUserLaunch) — master never pays
//   4. the agent builds metadata + signs its own create  (postAs → /api/pump)
//   5. record the run + advance the rotation             (launcher_runs / _queue)
//
// LIVE BY DEFAULT, BOUNDED BY CONSTRUCTION. The seeded global row ships enabled +
// real (dry_run=false) with a standing per-launch dev buy, so the platform mints
// on a cadence out of the box. The engine is still fully inert for any scope whose
// launcher_config row is disabled, and dry_run (set per scope) selects a coin +
// agent and records the run without moving SOL or submitting a create. Hard caps
// (per-launch SOL, daily SOL, hourly count, target cadence) and an auto-tripping
// circuit breaker bound the blast radius. Never throws — every failure is contained
// and recorded.

import { sql, isDbCapacityError, isDbUnavailableError } from './db.js';
import { env } from './env.js';
import { createSession } from './auth.js';
import { pickSource } from './launcher-sources.js';
import {
	masterBalanceSol,
	dailySpentSol,
	fundAgentForLaunch,
} from './launcher-funding.js';
import { getSolBalance } from './avatar-wallet.js';
import { solanaConnection } from './agent-pumpfun.js';

const ORIGIN = env.APP_ORIGIN || 'https://three.ws';

// How few enabled agents in the rotation before we auto-enroll more, and how many
// to enroll per top-up. The global rotation draws from the circulation pool (which
// grows itself), so the launcher is autonomous end-to-end with zero curation.
const MIN_QUEUE = 3;
const ENROLL_BATCH = 12;

// Circuit breaker: this many consecutive launch FAILURES (real submit/RPC errors,
// not business-rule skips) since the last success trips the config's paused flag.
const FAIL_BREAK = 5;

// Master must hold at least (per_launch_sol + this) or we wait — a recoverable
// skip (operator tops up the master), never a breaker trip.
const MASTER_FEE_BUFFER_SOL = 0.01;

// Floor on how often a dry_run scope re-picks. Each pick costs an LLM call and
// launches nothing; at the old 60s cadence the dry-run scopes alone demanded
// ~6× Groq's entire 100k-token/day free tier, starving the REAL launches into
// wordlist fallback. Hourly previews cost ~1% of that. Also: how far back the
// novelty guard remembers picks so the meme lane can't converge on one joke.
const DRY_RUN_MIN_CADENCE_S = 3600;
const NOVELTY_LOOKBACK_DAYS = 14;
const NOVELTY_LIMIT = 60;

// FUNDING MODEL PER SCOPE. Global: the platform master wallet tops the next agent
// up per launch (launcher-funding.js). User: SELF-FUNDED — the user's own agent
// wallet pays its launch (base cost + dev buy) from SOL the user deposited to it;
// master SOL never routes to a user scope, so "live" can only ever spend what the
// user chose to hold in wallets they own.
//
// Base pump.fun launch cost the agent wallet covers besides the dev buy (rent +
// fees) — mirrors PUMP_BASE_LAMPORTS in the /api/pump launch-agent preflight.
export const LAUNCH_BASE_SOL = 0.022;
// Headroom for priority fees so a wallet funded to the displayed estimate doesn't
// bounce off the preflight under congestion.
export const SELF_FUND_FEE_BUFFER_SOL = 0.005;

// House-ownership guarantee. When LAUNCHER_OWNER_USER_IDS is set (a comma-separated
// list of user uuids we control), the GLOBAL rotation is HARD-restricted to agents
// owned by exactly those accounts — an auditable promise that only house-owned
// agents ever sign a launch. Unset → the self-growing circulation pool, whose
// agents are themselves platform-created bot accounts (*@agents.three.ws), never
// real end users. Either way the launcher never borrows a user's agent.
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
export function ownerAllowlist() {
	return String(process.env.LAUNCHER_OWNER_USER_IDS || '')
		.split(',')
		.map((s) => s.trim())
		.filter((s) => UUID_RE.test(s));
}

// ── schema guard ────────────────────────────────────────────────────────────────
// Self-contained so the engine runs whether or not 20260629060000_coin_launcher.sql
// has been applied. Mirrors that migration; CREATE … IF NOT EXISTS is idempotent.
// launcher_claims is not created here: migration 20260930120000_launcher_claims.sql
// owns it (with its agent_id and (mint, network) indexes).
let _ensured = false;
async function ensureSchema() {
	if (_ensured) return;
	await sql`
		create table if not exists launcher_config (
			id uuid primary key default gen_random_uuid(),
			scope text not null check (scope in ('global','user')),
			user_id uuid,
			enabled boolean not null default true,
			dry_run boolean not null default false,
			mode text not null default 'hybrid' check (mode in ('off','trend','meme','random','hybrid')),
			sources jsonb not null default '["coin_intel","trending","knowyourmeme","googletrends","x"]'::jsonb,
			categories jsonb not null default '[]'::jsonb,
			target_cadence_seconds integer not null default 60,
			max_per_hour integer not null default 30,
			per_launch_sol numeric(20,9) not null default 0.04,
			dev_buy_sol numeric(20,9) not null default 0.01,
			daily_sol_cap numeric(20,9) not null default 1,
			buyback_bps integer not null default 5000,
			network text not null default 'mainnet',
			paused boolean not null default false,
			pause_reason text,
			updated_by uuid,
			created_at timestamptz not null default now(),
			updated_at timestamptz not null default now()
		)
	`;
	await sql`create unique index if not exists launcher_config_global_uniq on launcher_config (scope) where scope = 'global'`;
	await sql`create unique index if not exists launcher_config_user_uniq on launcher_config (user_id) where scope = 'user'`;
	await sql`
		create table if not exists launcher_queue (
			agent_id uuid primary key references agent_identities(id) on delete cascade,
			scope text not null default 'user' check (scope in ('global','user')),
			user_id uuid,
			enabled boolean not null default true,
			weight integer not null default 1,
			last_launched_at timestamptz,
			launch_count integer not null default 0,
			created_at timestamptz not null default now()
		)
	`;
	await sql`create index if not exists launcher_queue_pick_idx on launcher_queue (scope, enabled, last_launched_at nulls first)`;
	await sql`
		create table if not exists launcher_runs (
			id uuid primary key default gen_random_uuid(),
			scope text not null default 'global' check (scope in ('global','user')),
			user_id uuid,
			agent_id uuid,
			kind text not null check (kind in ('trend','meme','random')),
			trigger_source text,
			trigger_detail jsonb not null default '{}'::jsonb,
			name text, symbol text, mint text,
			network text not null default 'mainnet',
			sol_spent numeric(20,9) not null default 0,
			buyback_bps integer,
			status text not null default 'pending'
				check (status in ('pending','dry_run','funded','launched','confirmed','skipped','failed')),
			dry_run boolean not null default false,
			tx_signature text, fund_signature text, error text,
			created_at timestamptz not null default now(),
			updated_at timestamptz not null default now()
		)
	`;
	await sql`create index if not exists launcher_runs_recent_idx on launcher_runs (created_at desc)`;
	await sql`create index if not exists launcher_runs_scope_idx on launcher_runs (scope, created_at desc)`;
	await sql`create index if not exists launcher_runs_spend_idx on launcher_runs (created_at) where status in ('funded','launched','confirmed')`;
	await sql`create unique index if not exists launcher_runs_mint_uniq on launcher_runs (mint) where mint is not null`;
	await sql`
		insert into launcher_config (scope, enabled, dry_run, mode, per_launch_sol, dev_buy_sol)
		values ('global', true, false, 'hybrid', 0.04, 0.01)
		on conflict do nothing
	`;
	_ensured = true;
}

// A skip is an expected, recoverable non-event (cadence not due, cap reached, no
// agent ready) — logged as a 'skipped' run, never an error.
class Skip extends Error {}

// ── run-row helpers ─────────────────────────────────────────────────────────────
async function insertRun(cfg, coin, agent) {
	const [row] = await sql`
		insert into launcher_runs
			(scope, user_id, agent_id, kind, trigger_source, trigger_detail,
			 name, symbol, network, buyback_bps, status, dry_run)
		values (
			${cfg.scope}, ${cfg.user_id ?? null}, ${agent?.id ?? null},
			${coin.kind}, ${coin.trigger_source ?? null}, ${JSON.stringify(coin.trigger_detail ?? {})}::jsonb,
			${coin.name}, ${coin.symbol}, ${cfg.network}, ${cfg.buyback_bps},
			'pending', ${cfg.dry_run}
		)
		returning id
	`;
	return row.id;
}

async function setRun(id, fields) {
	await sql`
		update launcher_runs set
			status         = coalesce(${fields.status ?? null}, status),
			mint           = coalesce(${fields.mint ?? null}, mint),
			sol_spent      = coalesce(${fields.sol_spent ?? null}, sol_spent),
			tx_signature   = coalesce(${fields.tx_signature ?? null}, tx_signature),
			fund_signature = coalesce(${fields.fund_signature ?? null}, fund_signature),
			error          = coalesce(${fields.error ?? null}, error),
			updated_at     = now()
		where id = ${id}
	`;
}

// ── rotation ────────────────────────────────────────────────────────────────────

// Keep the rotation stocked. Global draws from the self-growing circulation pool;
// a user scope draws from that user's own avatar-bearing agents. Either way the
// engine never needs a human to curate who can launch.
async function ensureQueue(cfg) {
	const [{ c }] = await sql`
		select count(*)::int as c from launcher_queue
		where scope = ${cfg.scope} and enabled = true
	`;
	if (c >= MIN_QUEUE) return c;

	const owners = cfg.scope === 'global' ? ownerAllowlist() : [];
	const candidates = cfg.scope === 'global'
		? (owners.length
			? await sql`
				select ai.id from agent_identities ai
				where ai.deleted_at is null
				  and ai.user_id = any(${owners}::uuid[])
				  and ai.avatar_id is not null
				  and ai.meta->>'solana_address' is not null
				  and not exists (select 1 from launcher_queue q where q.agent_id = ai.id)
				limit ${ENROLL_BATCH}
			`
			: await sql`
				select ai.id from agent_identities ai
				where ai.deleted_at is null and ai.is_public = true
				  and ai.avatar_id is not null
				  and (ai.meta->>'circulation') = 'true'
				  and ai.meta->>'solana_address' is not null
				  and not exists (select 1 from launcher_queue q where q.agent_id = ai.id)
				limit ${ENROLL_BATCH}
			`)
		: await sql`
			select ai.id from agent_identities ai
			where ai.deleted_at is null and ai.user_id = ${cfg.user_id}
			  and ai.avatar_id is not null
			  and ai.meta->>'solana_address' is not null
			  and not exists (select 1 from launcher_queue q where q.agent_id = ai.id)
			limit ${ENROLL_BATCH}
		`;

	for (const r of candidates) {
		await sql`
			insert into launcher_queue (agent_id, scope, user_id, enabled)
			values (${r.id}, ${cfg.scope}, ${cfg.user_id ?? null}, true)
			on conflict (agent_id) do nothing
		`;
	}
	return c + candidates.length;
}

// The next agent up: enabled, avatar-bearing, with a wallet, least-recently-used
// first (weighted, with a touch of jitter so ties don't always resolve the same).
async function pickAgent(cfg) {
	const owners = cfg.scope === 'global' ? ownerAllowlist() : [];
	const ownerGate = owners.length ? sql`and ai.user_id = any(${owners}::uuid[])` : sql``;
	const [agent] = await sql`
		select q.agent_id as id, ai.user_id, ai.name, ai.avatar_id,
		       ai.meta->>'solana_address' as solana_address,
		       ai.meta->>'twitter' as twitter,
		       ai.meta->>'website' as website,
		       ai.meta->>'telegram' as telegram
		from launcher_queue q
		join agent_identities ai on ai.id = q.agent_id and ai.deleted_at is null
		where q.scope = ${cfg.scope} and q.enabled = true
		  and ai.avatar_id is not null
		  and ai.meta->>'solana_address' is not null
		  ${ownerGate}
		order by q.last_launched_at asc nulls first, q.weight desc, random()
		limit 1
	`;
	return agent || null;
}

// ── the real launch (metadata → agent-signed create) ─────────────────────────────
async function postAs(ownerUserId, path, body, timeoutMs = 55_000) {
	const token = await createSession({ userId: ownerUserId, userAgent: 'launcher', ip: null });
	let res;
	try {
		res = await fetch(`${ORIGIN}${path}`, {
			method: 'POST',
			headers: {
				'content-type': 'application/json',
				cookie: `__Host-sid=${token}`,
				'user-agent': 'threews-launcher/1.0',
			},
			body: JSON.stringify(body),
			signal: AbortSignal.timeout(timeoutMs),
		});
	} catch (err) {
		if (err?.name === 'TimeoutError' || err?.name === 'AbortError') return { status: 0, body: null, timedOut: true };
		throw err;
	}
	let parsed = null;
	try { parsed = await res.json(); } catch { /* non-JSON */ }
	return { status: res.status, body: parsed };
}

const isHttpSuccess = (status) => status >= 200 && status < 300;

async function launchCoin(cfg, agent, coin) {
	// Forward the agent's own socials when it has them; the metadata builder falls
	// back to the agent profile page (website) and the three.ws X/Telegram otherwise,
	// so every coin carries the fullest set of links we can supply autonomously.
	const meta = await postAs(agent.user_id, '/api/pump/build-metadata', {
		name: coin.name,
		symbol: coin.symbol,
		description: coin.description,
		agent_id: agent.id,
		avatar_id: agent.avatar_id,
		...(agent.twitter ? { twitter: agent.twitter } : {}),
		...(agent.website ? { website: agent.website } : {}),
		...(agent.telegram ? { telegram: agent.telegram } : {}),
	});
	if (meta.timedOut) throw new Error('metadata build timed out');
	if (!isHttpSuccess(meta.status) || !meta.body?.metadata_url) {
		throw new Error(`metadata build ${meta.status}: ${meta.body?.error || 'no url'}`);
	}

	const launch = await postAs(agent.user_id, '/api/pump/launch-agent', {
		agent_id: agent.id,
		name: coin.name,
		symbol: coin.symbol,
		uri: meta.body.metadata_url,
		network: cfg.network,
		quote_currency: 'sol',
		sol_buy_in: Number(cfg.dev_buy_sol) || 0,
		buyback_bps: cfg.buyback_bps,
		coin_type: 'agent',
	});
	if (launch.timedOut) throw new Error('launch timed out');
	const mint = launch.body?.mint || launch.body?.data?.mint;
	const sig = launch.body?.sig || launch.body?.signature || launch.body?.data?.sig || null;
	// launch-agent answers a created coin with 201; any 2xx carrying a mint is a
	// launch. Requiring exactly 200 recorded real launches as failed with no mint.
	if (!isHttpSuccess(launch.status) || !mint) {
		// Carry the HTTP status so callers can classify (402 unfunded ⇒ recoverable
		// skip on the self-funded path, everything else ⇒ failure).
		throw Object.assign(
			new Error(`launch ${launch.status}: ${launch.body?.error_description || launch.body?.error || launch.body?.message || 'no mint'}`),
			{ status: launch.status },
		);
	}
	return { mint, sig };
}

// ── breaker ───────────────────────────────────────────────────────────────────
async function tripBreaker(cfg, reason) {
	await sql`
		update launcher_config set paused = true, pause_reason = ${reason}, updated_at = now()
		where id = ${cfg.id}
	`;
}

// FAIL_BREAK consecutive failures since the last success ⇒ trip. Counts only real
// launch outcomes (launched/confirmed/failed), ignoring skips.
async function shouldTripBreaker(cfg) {
	const rows = await sql`
		select status from launcher_runs
		where scope = ${cfg.scope}
		  and ${cfg.scope === 'user' ? sql`user_id = ${cfg.user_id}` : sql`true`}
		  and status in ('launched', 'confirmed', 'failed')
		order by created_at desc
		limit ${FAIL_BREAK}
	`;
	return rows.length >= FAIL_BREAK && rows.every((r) => r.status === 'failed');
}

// ── per-scope tick ───────────────────────────────────────────────────────────────
async function runScopeTick(cfg) {
	if (cfg.paused) return { scope: cfg.scope, skipped: `paused: ${cfg.pause_reason || 'breaker'}` };
	if (cfg.mode === 'off') return { scope: cfg.scope, skipped: 'mode off' };

	const userFilter = cfg.scope === 'user' ? sql`and user_id = ${cfg.user_id}` : sql``;

	// Cadence gate — only one launch attempt per target_cadence_seconds. Two
	// deliberate extras:
	//   · dry_run cadence is floored: a preview scope re-picking every 60s burned
	//     ~5.8k LLM calls/week on runs nobody launches, exhausting the free-LLM
	//     quota the REAL picks need. 15 min keeps the preview fresh at ~1% of the
	//     cost.
	//   · quality-gate skips count as attempts: when the LLM lane is down, retrying
	//     every tick is the same quota burn in a tighter loop — wait a cadence out.
	const cadenceS = cfg.dry_run
		? Math.max(cfg.target_cadence_seconds, DRY_RUN_MIN_CADENCE_S)
		: cfg.target_cadence_seconds;
	const [last] = await sql`
		select created_at from launcher_runs
		where scope = ${cfg.scope} ${userFilter}
		  and (status in ('dry_run', 'funded', 'launched', 'confirmed')
		       or (status = 'skipped' and error like 'quality gate%'))
		order by created_at desc limit 1
	`;
	if (last) {
		const elapsed = (Date.now() - new Date(last.created_at).getTime()) / 1000;
		if (elapsed < cadenceS) {
			return { scope: cfg.scope, skipped: `cadence (${Math.round(elapsed)}s/${cadenceS}s)` };
		}
	}

	// Hourly ceiling.
	if (cfg.max_per_hour > 0) {
		const [{ c: hourCount }] = await sql`
			select count(*)::int as c from launcher_runs
			where scope = ${cfg.scope} ${userFilter}
			  and status in ('dry_run', 'funded', 'launched', 'confirmed')
			  and created_at > now() - interval '1 hour'
		`;
		if (hourCount >= cfg.max_per_hour) {
			return { scope: cfg.scope, skipped: `hourly cap (${hourCount}/${cfg.max_per_hour})` };
		}
	}

	// Daily SOL ceiling (real launches only; dry_run never spends).
	const dailyRemaining = cfg.dry_run
		? Infinity
		: Number(cfg.daily_sol_cap) - (await dailySpentSol(cfg.scope, cfg.user_id || null));
	if (!cfg.dry_run && dailyRemaining <= 0) {
		return { scope: cfg.scope, skipped: `daily SOL cap reached (${cfg.daily_sol_cap})` };
	}

	// Stock + pick the rotation.
	const queued = await ensureQueue(cfg);
	if (queued < 1) return { scope: cfg.scope, skipped: 'no launch-ready agents (need avatar + wallet)' };
	const agent = await pickAgent(cfg);
	if (!agent) return { scope: cfg.scope, skipped: 'no eligible agent this tick' };

	// Decide WHAT to launch — narrative-driven (launcher-trends via pickSource).
	// The recent pick history rides along so the LLM can't re-mint an identity
	// it already used (the KEKWZ-189-times failure mode).
	const recentPicks = await sql`
		select symbol, name from launcher_runs
		where created_at > now() - make_interval(days => ${NOVELTY_LOOKBACK_DAYS})
		  and symbol is not null
		group by symbol, name
		order by max(created_at) desc
		limit ${NOVELTY_LIMIT}
	`;
	const coin = await pickSource({
		mode: cfg.mode,
		network: cfg.network,
		categories: Array.isArray(cfg.categories) ? cfg.categories : [],
		sources: Array.isArray(cfg.sources) ? cfg.sources : undefined,
		avoid: recentPicks,
	});

	// Quality gate for LIVE scopes: a degraded pick means the LLM lane failed and
	// pickSource fell back to wordlist filler. Dry runs may record it (it shows
	// the operator the lane is degraded), but real SOL never mints "Neon Walrus" —
	// unless the operator explicitly chose mode 'random'.
	if (!cfg.dry_run && cfg.mode !== 'random' && (coin.degraded || coin.kind === 'random')) {
		const reason = `quality gate: ${coin.degraded || 'random filler'} — no narrative-backed pick this tick`;
		const gateRunId = await insertRun(cfg, coin, agent);
		await setRun(gateRunId, { status: 'skipped', error: reason });
		return { scope: cfg.scope, skipped: reason };
	}

	const runId = await insertRun(cfg, coin, agent);

	// Dry run: chose a coin + agent, recorded it, moved nothing.
	if (cfg.dry_run) {
		await setRun(runId, { status: 'dry_run' });
		await sql`update launcher_queue set last_launched_at = now() where agent_id = ${agent.id}`;
		return { scope: cfg.scope, dry_run: true, agent: agent.name, name: coin.name, symbol: coin.symbol, kind: coin.kind, top: coin.trigger_detail?.top_narrative || null };
	}

	// LIVE. A user scope is self-funded — the agent's own wallet pays, master SOL
	// never routes to it. Global continues below on the master-funded path.
	if (cfg.scope === 'user') {
		return liveUserLaunch(cfg, agent, coin, runId, dailyRemaining);
	}

	// Master balance breaker — recoverable wait, not a trip.
	const perLaunch = Number(cfg.per_launch_sol);
	const masterSol = await masterBalanceSol(cfg.network);
	if (masterSol == null) {
		await setRun(runId, { status: 'skipped', error: 'master launch wallet not configured' });
		return { scope: cfg.scope, skipped: 'master wallet not configured' };
	}
	if (masterSol < perLaunch + MASTER_FEE_BUFFER_SOL) {
		await setRun(runId, { status: 'skipped', error: `master balance ${masterSol} SOL below ${perLaunch} + buffer` });
		return { scope: cfg.scope, skipped: `master low (${masterSol.toFixed(4)} SOL)` };
	}

	// Fund the agent from master (guarded by per-launch + daily caps).
	const fund = await fundAgentForLaunch({
		agentAddress: agent.solana_address,
		sol: perLaunch,
		perLaunchCapSol: perLaunch,
		dailyCapSol: dailyRemaining,
		network: cfg.network,
		memo: `three.ws launcher · ${coin.symbol}`,
	});
	if (!fund.ok) {
		await setRun(runId, { status: 'skipped', error: fund.reason });
		return { scope: cfg.scope, skipped: `fund refused: ${fund.reason}` };
	}
	await setRun(runId, { status: 'funded', fund_signature: fund.signature, sol_spent: perLaunch });

	// The agent signs its own create.
	try {
		const { mint, sig } = await launchCoin(cfg, agent, coin);
		await setRun(runId, { status: 'confirmed', mint, tx_signature: sig });
		await sql`
			update launcher_queue
			set last_launched_at = now(), launch_count = launch_count + 1
			where agent_id = ${agent.id}
		`;
		return { scope: cfg.scope, agent: agent.name, name: coin.name, symbol: coin.symbol, kind: coin.kind, mint, top: coin.trigger_detail?.top_narrative || null };
	} catch (e) {
		await setRun(runId, { status: 'failed', error: String(e?.message || e).slice(0, 300) });
		// Still advance the rotation so one bad agent can't wedge the whole queue.
		await sql`update launcher_queue set last_launched_at = now() where agent_id = ${agent.id}`;
		if (await shouldTripBreaker(cfg)) {
			await tripBreaker(cfg, `${FAIL_BREAK} consecutive launch failures`);
			return { scope: cfg.scope, error: e?.message, breaker_tripped: true };
		}
		return { scope: cfg.scope, error: e?.message };
	}
}

// ── self-funded user launch ──────────────────────────────────────────────────────
// The picked agent's own custodial wallet pays for its launch (base cost + dev
// buy) from SOL its owner deposited. No master involvement — an unfunded wallet
// is a recoverable 'skipped' (deposit and the launcher resumes on its own), never
// a 'failed', so an empty wallet can't trip the breaker.
async function liveUserLaunch(cfg, agent, coin, runId, dailyRemaining) {
	const devBuy = Number(cfg.dev_buy_sol) || 0;
	const estCost = LAUNCH_BASE_SOL + devBuy;
	if (estCost > dailyRemaining) {
		await setRun(runId, { status: 'skipped', error: `daily SOL cap: launch ~${estCost.toFixed(4)} SOL > ${dailyRemaining.toFixed(4)} remaining` });
		return { scope: cfg.scope, skipped: `daily SOL cap (${cfg.daily_sol_cap})` };
	}

	// Balance gate before any work: cheaper than a metadata build + a 402, and it
	// yields a skip reason that carries the deposit address. An RPC blip falls
	// through — the launch preflight is the authority.
	const need = estCost + SELF_FUND_FEE_BUFFER_SOL;
	let walletSol = null;
	try {
		({ sol: walletSol } = await getSolBalance(solanaConnection(cfg.network), agent.solana_address));
	} catch { /* transient RPC failure */ }
	if (walletSol != null && walletSol < need) {
		await setRun(runId, {
			status: 'skipped',
			error: `agent wallet ${walletSol.toFixed(4)} SOL below ~${need.toFixed(4)} — deposit to ${agent.solana_address}`,
		});
		// Advance the rotation so one empty wallet doesn't pin the queue — the next
		// tick tries the user's next agent.
		await sql`update launcher_queue set last_launched_at = now() where agent_id = ${agent.id}`;
		return { scope: cfg.scope, skipped: `agent wallet unfunded (${agent.name})`, deposit_to: agent.solana_address };
	}

	try {
		const { mint, sig } = await launchCoin(cfg, agent, coin);
		await setRun(runId, { status: 'confirmed', mint, tx_signature: sig, sol_spent: estCost });
		await sql`
			update launcher_queue
			set last_launched_at = now(), launch_count = launch_count + 1
			where agent_id = ${agent.id}
		`;
		return { scope: cfg.scope, agent: agent.name, name: coin.name, symbol: coin.symbol, kind: coin.kind, mint, top: coin.trigger_detail?.top_narrative || null };
	} catch (e) {
		await sql`update launcher_queue set last_launched_at = now() where agent_id = ${agent.id}`;
		// The launch preflight 402s an underfunded wallet — recoverable, not a fault.
		if (e?.status === 402) {
			await setRun(runId, { status: 'skipped', error: String(e?.message || e).slice(0, 300) });
			return { scope: cfg.scope, skipped: `agent wallet unfunded (${agent.name})`, deposit_to: agent.solana_address };
		}
		await setRun(runId, { status: 'failed', error: String(e?.message || e).slice(0, 300) });
		if (await shouldTripBreaker(cfg)) {
			await tripBreaker(cfg, `${FAIL_BREAK} consecutive launch failures`);
			return { scope: cfg.scope, error: e?.message, breaker_tripped: true };
		}
		return { scope: cfg.scope, error: e?.message };
	}
}

// ── public entry ────────────────────────────────────────────────────────────────
/**
 * Run one launcher tick across every enabled scope. Safe to call on a schedule;
 * fully inert unless a launcher_config row is enabled. Never throws — each scope is
 * isolated and every failure is contained and recorded.
 * @returns {Promise<{ok:true, scopes:number, results:object[]}>}
 */
export async function runLauncherTick() {
	await ensureSchema();

	const configs = await sql`
		select * from launcher_config where enabled = true order by scope = 'global' desc
	`;
	if (!configs.length) return { ok: true, scopes: 0, results: [], note: 'no enabled launcher config' };

	const results = [];
	for (const cfg of configs) {
		// Normalise jsonb columns the driver may hand back as strings.
		cfg.sources = typeof cfg.sources === 'string' ? safeJson(cfg.sources, []) : cfg.sources;
		cfg.categories = typeof cfg.categories === 'string' ? safeJson(cfg.categories, []) : cfg.categories;
		cfg.target_cadence_seconds = Number(cfg.target_cadence_seconds) || 60;
		cfg.max_per_hour = Number(cfg.max_per_hour) || 0;
		cfg.buyback_bps = cfg.buyback_bps == null ? 5000 : Number(cfg.buyback_bps);
		try {
			results.push({ ok: true, ...(await runScopeTick(cfg)) });
		} catch (e) {
			if (e instanceof Skip) {
				results.push({ ok: false, scope: cfg.scope, skipped: e.message });
			} else {
				// A full/unavailable DB is infrastructure, not a launcher bug — the tick is
				// already caught and the next one retries, so log it at warn (not error) so
				// a storage-cap blip doesn't read as a code fault in the error stream.
				const infra = isDbCapacityError(e) || isDbUnavailableError(e);
				const log = infra ? console.warn : console.error;
				log('[launcher] scope tick failed', cfg.scope, e?.message);
				results.push({ ok: false, scope: cfg.scope, error: String(e?.message || e).slice(0, 300) });
			}
		}
	}
	return { ok: true, scopes: configs.length, results };
}

function safeJson(s, dflt) {
	try { return JSON.parse(s); } catch { return dflt; }
}