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.

83.2 KB
Raw Blame
// Wallet Intents engine — the programmable, conversational money layer.
//
// An intent is an owner-owned policy that makes an agent's custodial Solana
// wallet REACT to real events. The owner describes it in plain language; an LLM
// compiles it into a STRICT, server-validated structured intent; and the cron
// engine here executes enabled intents on their trigger through the SAME
// owner-authorized, spend-policy-gated, audited signing paths every other
// outbound action uses. An intent can NEVER exceed the agent's spend policy
// (enforceSpendLimit), and every real execution writes an agent_custody_events
// row with meta.intent_id so the owner sees real receipts.
//
// Triggers : on_tip_received | on_income | on_balance_below | on_schedule
//            | on_launch_matching | on_stream_started | credits_below | on_mail_received
// Actions  : tip | transfer | buy | snipe | withdraw | split_income | freeze | notify
//            | fund_inference (USDC -> account credits, api/_lib/inference-topup.js)
//
// $THREE is the only coin three.ws promotes. "$THREE"/"three" resolves to its
// canonical mint; any other mint is the owner's own runtime input (a snipe
// target), never hardcoded or recommended.
//
// This file deliberately reuses the building blocks proven by the Treasury
// Autopilot engine (sendSol, swap, the gated-spend → claim → finalize custody
// pattern) so intents move money exactly the way the rest of the wallet does.

import { PublicKey } from '@solana/web3.js';
import { sql } from './db.js';
import { runLocked } from './locked-sql.js';
import { confirmOrThrow } from './solana/confirm.js';
import { solUsdPrice, sendSol, explorerTxUrl } from './avatar-wallet.js';
import { solanaConnection } from './agent-pumpfun.js';
import { getSolanaAddressBalances, recoverSolanaAgentKeypair } from './agent-wallet.js';
import {
	getSpendLimits,
	getTradeLimits,
	setSpendLimits,
	enforceSpendLimit,
	SpendLimitError,
	recordCustodyEvent,
	updateCustodyEvent,
	validateSolanaAddress,
	lamportsToUsd,
	countPriorSpendsTo,
	SOL_FEE_HEADROOM_LAMPORTS,
} from './agent-trade-guards.js';
import { THREE_MINT } from './networth-model.js';
import { OPENROUTER_ATTRIBUTION_HEADERS } from './openrouter-attribution.js';
import { XAI_CHAT_COMPLETIONS_URL, GROK_BUDGET_MODEL, GROK_BUDGET_EXTRA_BODY } from './chat-models.js';
import { resolveSolanaRecipient } from '../../src/solana/sns.js';
import { recentPumpLaunches, enrichCreatorStats } from './pump-launch-feed.js';
import { logAudit } from './audit.js';
import { createApprovalRequest, runApproved, TTL_MS } from './approvals.js';
import { getCreditAccount } from './credits.js';
import { topupFromIntent, normalizeTopupAmount, TopupError } from './inference-topup.js';

const WSOL_MINT = 'So11111111111111111111111111111111111111112';
const JUPITER_BASE = 'https://lite-api.jup.ag/swap/v1';
const LAMPORTS_PER_SOL = 1_000_000_000n;
const DUST_USD = 0.02;
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;

export const INTENT_TRIGGERS = Object.freeze([
	'on_tip_received',
	'on_income',
	'on_balance_below',
	'on_schedule',
	'on_launch_matching',
	'on_stream_started',
	// Fired only by the v1 automation engine (api/_lib/agents-v1/automations.js),
	// never by the sweep or an event hook: the automation owns the trigger and
	// this intent owns the guarded execution.
	'on_automation',
	'credits_below',
	// Fired by agent mail when a message lands in the agent's inbox
	// (api/_lib/mail/inbound.js). Email is untrusted input, so this trigger
	// only pairs with notify and freeze: a message can never move funds.
	'on_mail_received',
]);

export const INTENT_ACTIONS = Object.freeze([
	'tip',
	'transfer',
	'buy',
	'snipe',
	'withdraw',
	'split_income',
	'freeze',
	'notify',
	'fund_inference',
]);

// Actions that move funds (need spend-policy enforcement + a signing keypair).
const SPENDING_ACTIONS = new Set(['tip', 'transfer', 'buy', 'snipe', 'withdraw', 'split_income']);

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

function num(v, def = null) {
	const n = Number(v);
	return Number.isFinite(n) ? n : def;
}
function clamp(n, min, max) {
	return Math.max(min, Math.min(max, n));
}
function posNum(v) {
	const n = Number(v);
	return Number.isFinite(n) && n > 0 ? n : null;
}
function str(v, max = 280) {
	return typeof v === 'string' ? v.slice(0, max) : '';
}
function solToLamports(sol) {
	return BigInt(Math.floor(Number(sol) * 1e9));
}

// Resolve a free-text asset reference to a canonical Solana asset. $THREE is the
// only coin we resolve by name; everything else is SOL, USDC, a raw mint, or
// unknown — mirrors api/agents/solana-intent.js so both speak the same language.
export function resolveAssetToken(raw, { threeMint = THREE_MINT } = {}) {
	const s = String(raw || '').trim();
	if (!s) return { kind: 'none', mint: null, symbol: null };
	const lower = s.toLowerCase().replace(/^\$/, '');
	if (lower === 'sol' || lower === 'solana') return { kind: 'sol', mint: null, symbol: 'SOL' };
	if (lower === 'usdc') return { kind: 'usdc', mint: null, symbol: 'USDC' };
	if (lower === 'three') return { kind: 'three', mint: threeMint, symbol: '$THREE' };
	if (BASE58_RE.test(s)) {
		return { kind: s === threeMint ? 'three' : 'mint', mint: s, symbol: s === threeMint ? '$THREE' : null };
	}
	return { kind: 'unknown', mint: null, symbol: s };
}

// ── normalization / validation ───────────────────────────────────────────────────
//
// Turn a raw intent (from the LLM tool call OR the manual form) into the canonical
// stored shape. Anything malformed degrades to a precise validation error — money
// must never move on a guess. Returns { ok, intent } | { ok:false, error, message }.

export function normalizeIntent(raw, { threeMint = THREE_MINT } = {}) {
	const r = raw && typeof raw === 'object' ? raw : {};

	const triggerType = String(r.trigger_type || r.trigger?.type || '').trim();
	if (!INTENT_TRIGGERS.includes(triggerType)) {
		return { ok: false, error: 'bad_trigger', message: `unsupported trigger "${triggerType || '(none)'}"` };
	}
	const actionType = String(r.action_type || r.action?.type || '').trim();
	if (!INTENT_ACTIONS.includes(actionType)) {
		return { ok: false, error: 'bad_action', message: `unsupported action "${actionType || '(none)'}"` };
	}

	const tcfg = r.trigger_config || r.trigger || {};
	const acfg = r.action_config || r.action || {};

	// ── trigger config ──
	const trigger = { type: triggerType };
	if (triggerType === 'on_tip_received') {
		trigger.min_sol = posNum(tcfg.min_sol) ?? 0;
	} else if (triggerType === 'on_balance_below') {
		const t = posNum(tcfg.threshold_sol);
		if (t == null) return { ok: false, error: 'needs_threshold', message: 'a balance threshold (SOL) is required' };
		trigger.threshold_sol = t;
	} else if (triggerType === 'on_schedule') {
		trigger.cadence = ['daily', 'weekly'].includes(tcfg.cadence) ? tcfg.cadence : 'weekly';
		const wd = Number(tcfg.weekday);
		trigger.weekday = trigger.cadence === 'weekly' ? (Number.isInteger(wd) && wd >= 0 && wd <= 6 ? wd : 5) : null;
		const hr = Number(tcfg.hour);
		trigger.hour = Number.isInteger(hr) && hr >= 0 && hr <= 23 ? hr : 13;
	} else if (triggerType === 'on_launch_matching') {
		const creator = str(tcfg.creator, 64).trim();
		trigger.creator = creator && BASE58_RE.test(creator) ? creator : null;
		trigger.max_mcap_usd = posNum(tcfg.max_mcap_usd);
		trigger.min_mcap_usd = posNum(tcfg.min_mcap_usd);
		if (!trigger.creator && trigger.max_mcap_usd == null) {
			return { ok: false, error: 'needs_filter', message: 'a launch rule needs a creator address and/or a max market cap to match on' };
		}
	} else if (triggerType === 'credits_below') {
		const t = posNum(tcfg.threshold_usd);
		if (t == null) return { ok: false, error: 'needs_threshold', message: 'a credits threshold (USD) is required' };
		trigger.threshold_usd = t;
	} else if (triggerType === 'on_mail_received') {
		// Optional filters, matched case-insensitively against the sender address
		// and the subject. Owner-authored strings; the email itself is never read
		// as a rule.
		trigger.from_contains = str(tcfg.from_contains, 120).trim().toLowerCase() || null;
		trigger.subject_contains = str(tcfg.subject_contains, 120).trim().toLowerCase() || null;
	}
	// on_income / on_stream_started carry no required config.

	// ── action config ──
	const action = { type: actionType };
	if (actionType === 'freeze') {
		// no params — the kill switch
	} else if (actionType === 'fund_inference') {
		// Top up the owner's account credits from this agent's USDC. The window is
		// one UTC day: however often the trigger holds, a rule tops up once a day.
		if (!['credits_below', 'on_schedule'].includes(triggerType)) {
			return { ok: false, error: 'bad_pairing', message: 'fund_inference runs on a credits_below or on_schedule trigger' };
		}
		try {
			action.amount_usdc = normalizeTopupAmount(acfg.amount_usdc);
		} catch (e) {
			return { ok: false, error: 'needs_amount', message: e.message };
		}
	} else if (actionType === 'notify') {
		action.message = str(acfg.message, 280) || null;
		action.channel = ['email', 'log'].includes(acfg.channel) ? acfg.channel : 'email';
	} else if (actionType === 'buy' || actionType === 'snipe') {
		// For on_launch_matching/snipe the mint is supplied at fire time (the matched
		// launch); otherwise the owner names a mint/symbol to acquire.
		const tgt = resolveAssetToken(acfg.mint || acfg.destination_or_mint || acfg.target, { threeMint });
		action.mint = tgt.mint || (tgt.kind === 'three' ? threeMint : null);
		action.mint_symbol = tgt.symbol || null;
		action.amount_sol = posNum(acfg.amount_sol);
		if (action.amount_sol == null) return { ok: false, error: 'needs_amount', message: `${actionType} needs a SOL amount to spend` };
		const slip = num(acfg.slippage_pct);
		action.slippage_pct = slip != null ? clamp(slip, 0, 50) : 5;
		// For a non-launch buy the mint must be known up front.
		// An automation on a launch trigger supplies the matched mint at fire time too.
		action.mint_from_event = triggerType === 'on_automation' && acfg.mint_from_event === true;
		if (triggerType !== 'on_launch_matching' && !action.mint && !action.mint_from_event) {
			return { ok: false, error: 'needs_mint', message: 'name the token to buy ($THREE or a mint address)' };
		}
	} else {
		// tip | transfer | withdraw | split_income — move SOL to a destination.
		const pct = posNum(acfg.pct);
		const amount = posNum(acfg.amount_sol);
		const above = posNum(acfg.above_sol);
		action.pct = pct != null ? clamp(pct, 0.01, 100) : null;
		action.amount_sol = amount;
		action.above_sol = above; // for withdraw: "profit above N SOL"
		action.of = ['tip', 'income', 'balance'].includes(acfg.of) ? acfg.of : (pct != null ? (actionType === 'split_income' ? 'income' : 'tip') : null);
		action.destination = str(acfg.destination, 64).trim();
		action.destination_label = str(acfg.destination_label, 80) || null;
		// A tip back to whoever just tipped has no static destination — the engine
		// fills the tipper in at fire time. Recognize that here so the rule validates.
		action.to_tipper = acfg.to_tipper === true || (actionType === 'tip' && triggerType === 'on_tip_received' && !action.destination);

		if (actionType === 'split_income') {
			if (action.pct == null) return { ok: false, error: 'needs_pct', message: 'split needs a percentage of income' };
			action.of = 'income';
		}
		if (actionType === 'tip' || actionType === 'transfer') {
			if (action.pct == null && action.amount_sol == null) {
				return { ok: false, error: 'needs_amount', message: 'a tip/transfer needs a fixed SOL amount or a percentage' };
			}
		}
		if (actionType === 'withdraw') {
			if (action.amount_sol == null && action.above_sol == null && action.pct == null) {
				return { ok: false, error: 'needs_amount', message: 'a withdraw needs an amount, a "profit above N SOL" threshold, or a percentage' };
			}
		}
		if (!action.destination && !action.to_tipper) {
			return { ok: false, error: 'needs_destination', message: `${actionType} needs a destination address or .sol name` };
		}
	}

	if (triggerType === 'credits_below' && !['fund_inference', 'notify'].includes(actionType)) {
		return { ok: false, error: 'bad_pairing', message: 'a credits_below rule can top up credits (fund_inference) or notify you' };
	}
	if (triggerType === 'on_mail_received' && !['notify', 'freeze'].includes(actionType)) {
		return { ok: false, error: 'bad_pairing', message: 'an email can only notify you or freeze the wallet; it can never move funds' };
	}

	// ── owner-set caps (clamped under the spend policy at execution time) ──
	const lim = r.limits || {};
	const limits = {
		per_action_usd: posNum(lim.per_action_usd),
		daily_usd: posNum(lim.daily_usd),
		total_usd: posNum(lim.total_usd),
	};

	const intent = {
		title: str(r.title, 80).trim() || defaultTitle(triggerType, actionType, action),
		trigger,
		action,
		limits,
		readback: str(r.readback, 280).trim() || null,
	};
	return { ok: true, intent };
}

function defaultTitle(triggerType, actionType, action) {
	const T = {
		on_tip_received: 'On a tip',
		on_income: 'On income',
		on_balance_below: 'On low balance',
		on_schedule: 'On schedule',
		on_launch_matching: 'On matching launch',
		on_stream_started: 'On stream start',
		credits_below: 'On low credits',
		on_mail_received: 'On new email',
	}[triggerType] || 'Intent';
	const A = {
		tip: 'tip back',
		transfer: 'transfer',
		buy: `buy ${action?.mint_symbol || 'token'}`,
		snipe: 'snipe',
		withdraw: 'withdraw',
		split_income: 'split income',
		freeze: 'freeze the wallet',
		notify: 'notify me',
		fund_inference: 'top up credits',
	}[actionType] || actionType;
	return `${T} → ${A}`;
}

// One-sentence human read-back when the model didn't supply one.
export function describeIntent(intent) {
	if (intent.readback) return intent.readback;
	const t = intent.trigger || {};
	const a = intent.action || {};
	const dest = a.destination_label || (a.destination ? `${a.destination.slice(0, 4)}…${a.destination.slice(-4)}` : '');
	const amt = a.pct != null ? `${a.pct}%${a.of ? ` of ${a.of}` : ''}` : a.amount_sol != null ? `${a.amount_sol} SOL` : a.above_sol != null ? `anything above ${a.above_sol} SOL` : '';
	switch (t.type) {
		case 'on_tip_received':
			return `When someone tips ${t.min_sol ? `more than ${t.min_sol} SOL` : 'me'}, ${a.type === 'tip' ? `tip back ${amt}` : `${a.type} ${amt} to ${dest}`}.`;
		case 'on_income':
			return `On income, ${a.type === 'split_income' ? `split ${amt} to ${dest}` : `${a.type} ${amt}`}.`;
		case 'on_balance_below':
			return `When my balance drops below ${t.threshold_sol} SOL, ${a.type === 'freeze' ? 'freeze all spending and notify me' : a.type === 'notify' ? 'notify me' : `${a.type} ${amt}`}.`;
		case 'on_schedule':
			return `${t.cadence === 'weekly' ? `Every ${['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][t.weekday ?? 5]}` : 'Daily'} at ${String(t.hour).padStart(2, '0')}:00 UTC, ${a.type} ${amt}${dest ? ` to ${dest}` : ''}.`;
		case 'on_launch_matching':
			return `When a launch matches${t.creator ? ` creator ${t.creator.slice(0, 4)}…` : ''}${t.max_mcap_usd ? ` under $${Math.round(t.max_mcap_usd / 1000)}k` : ''}, ${a.type} ${a.amount_sol} SOL.`;
		case 'credits_below':
			return `When credits fall below $${t.threshold_usd}, ${a.type === 'fund_inference' ? `top up ${a.amount_usdc} USDC from the wallet, at most once a day` : 'notify me'}.`;
		case 'on_stream_started':
			return `When a money stream starts, ${a.type} ${amt}${dest ? ` to ${dest}` : ''}.`;
		case 'on_mail_received': {
			const filters = [t.from_contains && `from "${t.from_contains}"`, t.subject_contains && `about "${t.subject_contains}"`].filter(Boolean);
			return `When the agent receives an email${filters.length ? ` ${filters.join(' ')}` : ''}, ${a.type === 'freeze' ? 'freeze all spending and notify me' : 'notify me'}.`;
		}
		default:
			return intent.title || 'Wallet intent';
	}
}

// ── DB access ────────────────────────────────────────────────────────────────────

function rowToIntent(row) {
	if (!row) return null;
	return {
		id: row.id,
		agent_id: row.agent_id,
		title: row.title,
		trigger: { type: row.trigger_type, ...(row.trigger_config || {}) },
		action: { type: row.action_type, ...(row.action_config || {}) },
		limits: row.limits || {},
		network: row.network,
		enabled: row.enabled,
		public_trait: row.public_trait,
		source_text: row.source_text,
		readback: row.readback,
		stats: {
			fire_count: row.fire_count,
			spent_usd: Number(row.spent_usd || 0),
			last_fired_at: row.last_fired_at,
			last_status: row.last_status,
			last_note: row.last_note,
			last_signature: row.last_signature,
		},
		created_at: row.created_at,
		updated_at: row.updated_at,
	};
}

export async function listIntents(agentId) {
	const rows = await sql`
		SELECT * FROM agent_wallet_intents WHERE agent_id = ${agentId} ORDER BY created_at DESC
	`;
	return rows.map(rowToIntent);
}

export async function getIntent(agentId, intentId) {
	const [row] = await sql`SELECT * FROM agent_wallet_intents WHERE id = ${intentId} AND agent_id = ${agentId}`;
	return rowToIntent(row);
}

export async function createIntent(agentId, userId, normalized, { network = 'mainnet', sourceText = null, publicTrait = false } = {}) {
	const { trigger, action, limits, title, readback } = normalized;
	const triggerConfig = { ...trigger };
	delete triggerConfig.type;
	const actionConfig = { ...action };
	delete actionConfig.type;
	const [row] = await sql`
		INSERT INTO agent_wallet_intents
			(agent_id, user_id, title, trigger_type, trigger_config, action_type, action_config, limits, network, source_text, readback, public_trait, enabled)
		VALUES (
			${agentId}, ${userId}, ${title}, ${trigger.type}, ${JSON.stringify(triggerConfig)}::jsonb,
			${action.type}, ${JSON.stringify(actionConfig)}::jsonb, ${JSON.stringify(limits || {})}::jsonb,
			${network}, ${sourceText}, ${readback || describeIntent(normalized)}, ${!!publicTrait}, true
		)
		RETURNING *
	`;
	logAudit({ userId, action: 'wallet_intent.create', resourceId: agentId, meta: { intent_id: row.id, trigger: trigger.type, action: action.type } });
	return rowToIntent(row);
}

export async function updateIntent(agentId, userId, intentId, patch) {
	const existing = await getIntent(agentId, intentId);
	if (!existing) return null;

	const fields = [];
	const next = {};
	if ('enabled' in patch) next.enabled = patch.enabled === true;
	if ('public_trait' in patch) next.public_trait = patch.public_trait === true;
	if ('title' in patch) next.title = str(patch.title, 80).trim() || existing.title;
	// A full re-validated intent may replace trigger/action/limits.
	let normalized = null;
	if (patch.intent) {
		const r = normalizeIntent(patch.intent);
		if (!r.ok) return { error: r.error, message: r.message };
		normalized = r.intent;
	}

	const triggerConfig = normalized ? (() => { const c = { ...normalized.trigger }; delete c.type; return c; })() : null;
	const actionConfig = normalized ? (() => { const c = { ...normalized.action }; delete c.type; return c; })() : null;

	const [row] = await sql`
		UPDATE agent_wallet_intents SET
			enabled = ${'enabled' in next ? next.enabled : existing.enabled},
			public_trait = ${'public_trait' in next ? next.public_trait : existing.public_trait},
			title = ${normalized ? normalized.title : ('title' in next ? next.title : existing.title)},
			trigger_type = ${normalized ? normalized.trigger.type : existing.trigger.type},
			trigger_config = ${JSON.stringify(triggerConfig ?? (() => { const c = { ...existing.trigger }; delete c.type; return c; })())}::jsonb,
			action_type = ${normalized ? normalized.action.type : existing.action.type},
			action_config = ${JSON.stringify(actionConfig ?? (() => { const c = { ...existing.action }; delete c.type; return c; })())}::jsonb,
			limits = ${JSON.stringify(normalized ? normalized.limits : existing.limits)}::jsonb,
			readback = ${normalized ? (normalized.readback || describeIntent(normalized)) : existing.readback},
			updated_at = now()
		WHERE id = ${intentId} AND agent_id = ${agentId}
		RETURNING *
	`;
	logAudit({ userId, action: 'wallet_intent.update', resourceId: agentId, meta: { intent_id: intentId } });
	return rowToIntent(row);
}

export async function deleteIntent(agentId, userId, intentId) {
	const rows = await sql`DELETE FROM agent_wallet_intents WHERE id = ${intentId} AND agent_id = ${agentId} RETURNING id`;
	if (rows.length) logAudit({ userId, action: 'wallet_intent.delete', resourceId: agentId, meta: { intent_id: intentId } });
	return rows.length > 0;
}

// Sum the REAL USD this intent has moved within a window (from custody rows it
// wrote). Powers per-intent daily/total caps and the "remaining budget" read-out.
async function intentSpentUsd(agentId, intentId, sinceIso = null) {
	const [row] = await sql`
		SELECT COALESCE(SUM(usd), 0)::float8 AS usd
		FROM agent_custody_events
		WHERE agent_id = ${agentId}
		  AND usd IS NOT NULL
		  AND status IN ('ok', 'pending', 'confirmed')
		  AND meta->>'intent_id' = ${intentId}
		  AND (${sinceIso}::timestamptz IS NULL OR created_at > ${sinceIso}::timestamptz)
	`;
	return Number(row?.usd || 0);
}

// ── NL → structured intent compiler (real LLM proxy, strict tool schema) ─────────

const COMPILE_TOOL = {
	name: 'record_wallet_intent',
	description:
		'Record the single standing wallet RULE the owner described, as a strict structured intent the engine can enforce. ' +
		'A rule is an event TRIGGER plus an ACTION the agent takes automatically when it fires, bounded by owner caps. ' +
		'NEVER invent an amount, destination, creator, or token. If anything required is missing or ambiguous, set ' +
		'needs_clarification true and ask one short question instead of guessing. The only coin the platform promotes is ' +
		'$THREE; treat "$THREE"/"three" as that coin. A mint/creator the owner names is their own runtime input.',
	input_schema: {
		type: 'object',
		properties: {
			title: { type: 'string', description: 'A short label, e.g. "Tip back generously".' },
			trigger_type: {
				type: 'string',
				enum: INTENT_TRIGGERS,
				description:
					'on_tip_received: someone tips the agent. on_income: any income arrives. on_balance_below: SOL balance drops under a floor. ' +
					'on_schedule: a daily/weekly time. on_launch_matching: a new pump.fun launch matches a creator and/or market cap. ' +
					'on_stream_started: a money stream to the agent begins. credits_below: the owner\'s account credits (USD) drop under a floor. ' +
					'on_mail_received: an email lands in the agent\'s inbox (pairs only with notify or freeze).',
			},
			trigger_config: {
				type: 'object',
				description:
					'Fields by trigger. on_tip_received: { min_sol }. on_balance_below: { threshold_sol }. on_schedule: ' +
					'{ cadence: "daily"|"weekly", weekday: 0-6 (Sun=0..Sat=6, Fri=5), hour: 0-23 (UTC) }. on_launch_matching: ' +
					'{ creator: base58|null, max_mcap_usd, min_mcap_usd }. credits_below: { threshold_usd }. ' +
					'on_mail_received: { from_contains, subject_contains } (both optional).',
				properties: {
					min_sol: { type: 'number' },
					threshold_sol: { type: 'number' },
					threshold_usd: { type: 'number' },
					from_contains: { type: 'string' },
					subject_contains: { type: 'string' },
					cadence: { type: 'string', enum: ['daily', 'weekly'] },
					weekday: { type: 'number' },
					hour: { type: 'number' },
					creator: { type: 'string' },
					max_mcap_usd: { type: 'number' },
					min_mcap_usd: { type: 'number' },
				},
			},
			action_type: {
				type: 'string',
				enum: INTENT_ACTIONS,
				description:
					'tip/transfer: send SOL to a destination. buy/snipe: spend SOL to acquire a token. withdraw: send SOL to an ' +
					'owner-controlled address. split_income: send a % of income to a destination. freeze: halt all spending ' +
					'(kill switch). notify: just DM the owner. fund_inference: move USDC from the agent wallet into account credits ' +
					'that pay for model calls (only with credits_below or on_schedule).',
			},
			action_config: {
				type: 'object',
				description:
					'Fields by action. tip/transfer: { amount_sol } OR { pct, of: "tip"|"income"|"balance" }, destination. ' +
					'buy/snipe: { mint ("$THREE" or base58, omit for on_launch_matching), amount_sol, slippage_pct }. ' +
					'withdraw: { amount_sol } OR { above_sol } OR { pct }, destination. split_income: { pct, destination }. ' +
					'notify: { message }. fund_inference: { amount_usdc }. "half of what they sent" → pct 50, of "tip".',
				properties: {
					amount_sol: { type: 'number' },
					above_sol: { type: 'number' },
					pct: { type: 'number' },
					of: { type: 'string', enum: ['tip', 'income', 'balance'] },
					destination: { type: 'string' },
					mint: { type: 'string' },
					slippage_pct: { type: 'number' },
					message: { type: 'string' },
					amount_usdc: { type: 'number' },
				},
			},
			limits: {
				type: 'object',
				description: 'Owner caps. { per_action_usd, daily_usd, total_usd } — each in USD, omit if not stated.',
				properties: {
					per_action_usd: { type: 'number' },
					daily_usd: { type: 'number' },
					total_usd: { type: 'number' },
				},
			},
			readback: { type: 'string', description: 'One plain sentence the owner can confirm, naming real amounts/destinations.' },
			confidence: { type: 'number', description: '0..1 confidence this parse is correct.' },
			needs_clarification: { type: 'boolean' },
			clarifying_question: { type: 'string', description: 'When needs_clarification, the single short question to ask.' },
		},
		required: ['trigger_type', 'action_type', 'readback'],
	},
};

const OPENAI_COMPILE_TOOL = {
	type: 'function',
	function: { name: COMPILE_TOOL.name, description: COMPILE_TOOL.description, parameters: COMPILE_TOOL.input_schema },
};

function compileSystemPrompt({ agentName, network, balanceSol, holdings, limits, tradeLimits }) {
	const held = (holdings || []).slice(0, 6).map((h) => `  - ${h.symbol || h.mint}: ${h.ui_amount}`).join('\n');
	return [
		`You compile the owner's plain-language money rule into ONE structured standing intent for "${agentName || 'this agent'}", a 3D AI agent on three.ws that holds its own real Solana wallet.`,
		'Call record_wallet_intent exactly once. Map the request to one trigger + one action. Output nothing else.',
		'',
		'Rules:',
		'- NEVER invent an amount, destination, creator address, token, or schedule. If the rule is missing any of these, set needs_clarification=true with one short question.',
		'- "tip back half of what they sent" → trigger on_tip_received, action tip, action_config { pct: 50, of: "tip" }, destination is the tipper (leave destination empty — the engine fills the tipper in at fire time).',
		'- "when my balance is under X, freeze and DM me" → trigger on_balance_below { threshold_sol: X }, action freeze.',
		'- "when credits fall below 100, top up 5 USDC from the wallet" → trigger credits_below { threshold_usd: 100 }, action fund_inference { amount_usdc: 5 }. Credits are USD; the engine tops up at most once a day.',
		'- "split 10% of everything I earn to <addr/name>" → trigger on_income, action split_income { pct: 10, destination: <addr/.sol> }.',
		'- "every Friday withdraw profit above 2 SOL to <addr>" → trigger on_schedule { cadence: "weekly", weekday: 5, hour: 13 }, action withdraw { above_sol: 2, destination: <addr> }.',
		'- "snipe launches from <creator> under $40k, max 1 SOL each" → trigger on_launch_matching { creator, max_mcap_usd: 40000 }, action snipe { amount_sol: 1 } (omit mint — it is the matched launch).',
		'- The ONLY coin the platform promotes is $THREE. Treat "$THREE"/"three" as that coin. A mint/creator the owner pastes is their own input — pass it through, never invent one.',
		'- Keep readback to one sentence the owner can confirm.',
		'',
		`Live context — network: ${network}; spendable SOL: ${balanceSol == null ? 'unknown' : balanceSol}.`,
		held ? `Tokens held:\n${held}` : 'Tokens held: none detected.',
		`Owner spend policy (hard ceilings the engine enforces): per-tx $${limits?.per_tx_usd ?? '∞'}, daily $${limits?.daily_usd ?? '∞'}. Any cap the owner sets is clamped under these.`,
	].join('\n');
}

async function fetchWithTimeout(url, opts, ms = 15_000) {
	const ctrl = new AbortController();
	const t = setTimeout(() => ctrl.abort(), ms);
	try {
		return await fetch(url, { ...opts, signal: ctrl.signal });
	} finally {
		clearTimeout(t);
	}
}

async function callAnthropicCompile({ apiKey, system, messages }) {
	const resp = await fetchWithTimeout('https://api.anthropic.com/v1/messages', {
		method: 'POST',
		headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
		body: JSON.stringify({
			model: 'claude-opus-4-8',
			max_tokens: 700,
			system,
			messages,
			tools: [COMPILE_TOOL],
			tool_choice: { type: 'tool', name: COMPILE_TOOL.name },
		}),
	});
	if (!resp.ok) throw new Error(`anthropic ${resp.status}`);
	const j = await resp.json();
	const block = (j.content || []).find((b) => b.type === 'tool_use' && b.name === COMPILE_TOOL.name);
	if (!block) throw new Error('anthropic: no tool_use');
	return block.input;
}

async function callOpenRouterCompile({ apiKey, system, messages }) {
	const resp = await fetchWithTimeout('https://openrouter.ai/api/v1/chat/completions', {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${apiKey}`,
			'content-type': 'application/json',
			...OPENROUTER_ATTRIBUTION_HEADERS,
		},
		body: JSON.stringify({
			model: 'openai/gpt-oss-120b',
			max_tokens: 700,
			messages: [{ role: 'system', content: system }, ...messages],
			tools: [OPENAI_COMPILE_TOOL],
			tool_choice: { type: 'function', function: { name: COMPILE_TOOL.name } },
		}),
	});
	if (!resp.ok) throw new Error(`openrouter ${resp.status}`);
	const j = await resp.json();
	const call = j.choices?.[0]?.message?.tool_calls?.[0];
	if (!call?.function?.arguments) throw new Error('openrouter: no tool_call');
	return JSON.parse(call.function.arguments);
}

async function callGrokCompile({ apiKey, system, messages }) {
	const resp = await fetchWithTimeout(XAI_CHAT_COMPLETIONS_URL, {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${apiKey}`,
			'content-type': 'application/json',
		},
		body: JSON.stringify({
			model: GROK_BUDGET_MODEL,
			...GROK_BUDGET_EXTRA_BODY,
			max_tokens: 700,
			messages: [{ role: 'system', content: system }, ...messages],
			tools: [OPENAI_COMPILE_TOOL],
			tool_choice: { type: 'function', function: { name: COMPILE_TOOL.name } },
		}),
	});
	if (!resp.ok) throw new Error(`grok ${resp.status}`);
	const j = await resp.json();
	const call = j.choices?.[0]?.message?.tool_calls?.[0];
	if (!call?.function?.arguments) throw new Error('grok: no tool_call');
	return JSON.parse(call.function.arguments);
}

/**
 * Compile a plain-language rule into a validated structured intent. The model is
 * forced to emit the tool schema; the server then re-validates every field. A
 * missing-key deployment returns a precise "unavailable" so the client falls back
 * to the manual form rather than faking a parse.
 *
 * @returns {Promise<{ ok:true, intent, provider, clarify?:string }
 *                  | { ok:false, error, message, clarify?:string }>}
 */
export async function compileIntentFromText(text, ctx = {}) {
	const utterance = String(text || '').trim();
	if (!utterance) return { ok: false, error: 'empty', message: 'describe a rule first' };
	if (utterance.length > 1000) return { ok: false, error: 'too_long', message: 'that is too long — shorten the rule' };

	const anthropicKey = ctx.anthropicKey || process.env.ANTHROPIC_API_KEY;
	const grokKey = ctx.grokKey || process.env.GROK_API_KEY;
	const openrouterKey = ctx.openrouterKey || process.env.OPENROUTER_API_KEY;
	if (!anthropicKey && !grokKey && !openrouterKey) {
		return { ok: false, error: 'unavailable', message: 'the rule compiler is not configured on this deployment — build the rule with the form instead' };
	}

	const system = compileSystemPrompt(ctx);
	const messages = [];
	for (const h of (ctx.history || []).slice(-4)) {
		if (h && (h.role === 'user' || h.role === 'assistant') && typeof h.content === 'string') {
			messages.push({ role: h.role, content: h.content.slice(0, 800) });
		}
	}
	messages.push({ role: 'user', content: utterance });
	if (messages[0].role !== 'user') messages.shift();

	let raw = null;
	let provider = null;
	const tried = [];
	if (anthropicKey) {
		try { raw = await callAnthropicCompile({ apiKey: anthropicKey, system, messages }); provider = 'anthropic'; }
		catch (e) { tried.push(`anthropic:${e.message}`); }
	}
	if (!raw && grokKey) {
		try { raw = await callGrokCompile({ apiKey: grokKey, system, messages }); provider = 'grok'; }
		catch (e) { tried.push(`grok:${e.message}`); }
	}
	if (!raw && openrouterKey) {
		try { raw = await callOpenRouterCompile({ apiKey: openrouterKey, system, messages }); provider = 'openrouter'; }
		catch (e) { tried.push(`openrouter:${e.message}`); }
	}
	if (!raw) {
		console.warn('[wallet-intents] compile providers failed:', tried.join(' | '));
		return { ok: false, error: 'parse_failed', message: 'could not parse that — rephrase, or build the rule with the form' };
	}

	if (raw.needs_clarification && raw.clarifying_question) {
		return { ok: false, error: 'clarify', message: 'I need one more detail', clarify: str(raw.clarifying_question, 280), provider };
	}

	const norm = normalizeIntent(raw, { threeMint: THREE_MINT });
	if (!norm.ok) {
		return { ok: false, error: norm.error, message: norm.message, clarify: raw.clarifying_question ? str(raw.clarifying_question, 280) : null, provider };
	}

	// Resolve a .sol / name destination to a real address now, so the read-back and
	// the stored intent both carry the real recipient. An unresolved name clarifies.
	const a = norm.intent.action;
	const needsDest = ['tip', 'transfer', 'withdraw', 'split_income'].includes(a.type) && a.destination;
	// A tip-back to the tipper has an empty destination by design (filled at fire time).
	const tipBackToTipper = a.type === 'tip' && norm.intent.trigger.type === 'on_tip_received' && !a.destination;
	if (needsDest && !BASE58_RE.test(a.destination)) {
		const resolved = await resolveSolanaRecipient(a.destination).catch(() => ({ address: null }));
		if (resolved.address) {
			a.destination_label = a.destination;
			a.destination = resolved.address;
		} else {
			return { ok: false, error: 'bad_destination', message: `couldn't resolve "${a.destination}"`, clarify: `What Solana address or .sol name should "${norm.intent.title}" send to?`, provider };
		}
	} else if (needsDest && !a.destination_label) {
		a.destination_label = `${a.destination.slice(0, 4)}…${a.destination.slice(-4)}`;
	}
	if (tipBackToTipper) a.to_tipper = true;

	norm.intent.readback = norm.intent.readback || describeIntent(norm.intent);
	return { ok: true, intent: norm.intent, provider };
}

// ── execution ─────────────────────────────────────────────────────────────────────
//
// Every spending action flows through gatedSpend: clamp to the agent spend policy
// AND the intent's own caps, claim an idempotent custody row stamped with
// intent_id, run the real transfer/swap, finalize the row. doSpend(lamports)
// returns { signature }.

// Why did the atomic claim above write no row? Exactly one of: this event already
// fired, or one of the three rolling ceilings is full. Re-read them (outside the
// lock, which is fine for a message) so the owner sees the real reason instead of
// a generic skip.
async function claimRejection({ agentId, intentId, idemKey, usd, network, dailyUsd, intentDailyUsd, intentTotalUsd, sinceIso }) {
	const [dupe] = await sql`
		SELECT id FROM agent_custody_events
		WHERE agent_id = ${agentId} AND idempotency_key = ${idemKey} LIMIT 1
	`;
	if (dupe) return { status: 'skipped', note: 'already fired for this event' };

	if (intentTotalUsd != null) {
		const spent = await intentSpentUsd(agentId, intentId, null);
		if (spent + usd > intentTotalUsd + 1e-9) {
			return { status: 'paused', note: `would exceed this rule's lifetime cap ($${intentTotalUsd})`, usd };
		}
	}
	if (intentDailyUsd != null) {
		const spent = await intentSpentUsd(agentId, intentId, sinceIso);
		if (spent + usd > intentDailyUsd + 1e-9) {
			return { status: 'paused', note: `would exceed this rule's daily budget ($${intentDailyUsd}; $${spent.toFixed(2)} used today)`, usd };
		}
	}
	if (dailyUsd != null) {
		const [row] = await sql`
			SELECT COALESCE(SUM(usd), 0)::float8 AS s
			FROM agent_custody_events
			WHERE agent_id = ${agentId} AND network = ${network} AND event_type = 'spend'
			  AND status IN ('ok', 'pending', 'confirmed') AND usd IS NOT NULL
			  AND created_at > now() - interval '24 hours'
		`;
		const spent = Number(row?.s || 0);
		return {
			status: 'paused',
			note: `would bring today's wallet spend to $${(spent + usd).toFixed(2)}, over the $${dailyUsd} daily limit`,
			usd,
		};
	}
	// No ceiling explains it and no duplicate exists: another writer claimed the
	// same key between the insert and this read. Treat it as already fired.
	return { status: 'skipped', note: 'already fired for this event' };
}

// Intent-level caps (per-action / daily / total): the owner's own ceilings for one
// rule. Returns a skip/pause verdict, or null when the spend fits every cap.
async function intentCapVerdict({ ctx, intent, usd }) {
	const { agentId, now } = ctx;
	const lim = intent.limits || {};
	if (lim.per_action_usd != null && usd > lim.per_action_usd + 1e-9) {
		return { status: 'skipped', note: `over this rule's per-action cap ($${lim.per_action_usd})`, usd };
	}
	if (lim.daily_usd != null) {
		const since = new Date(now.getTime() - 24 * 3600 * 1000).toISOString();
		const spent = await intentSpentUsd(agentId, intent.id, since);
		if (spent + usd > lim.daily_usd + 1e-9) {
			return { status: 'paused', note: `would exceed this rule's daily budget ($${lim.daily_usd}; $${spent.toFixed(2)} used today)`, usd };
		}
	}
	if (lim.total_usd != null) {
		const spent = await intentSpentUsd(agentId, intent.id, null);
		if (spent + usd > lim.total_usd + 1e-9) {
			return { status: 'paused', note: `would exceed this rule's lifetime cap ($${lim.total_usd})`, usd };
		}
	}
	return null;
}

// Top up the owner's credits from the agent wallet (USDC through the
// self-facilitator). The top-up path runs its own spend-policy reserve, so this
// only applies the rule's caps and maps the outcome onto the intent vocabulary.
async function fundInference({ ctx, intent, discriminator }) {
	const usd = Number(intent.action.amount_usdc);
	const capped = await intentCapVerdict({ ctx, intent, usd });
	if (capped) return capped;
	if (ctx.dryRun) return { status: 'would_run', note: `would top up ${usd} USDC of credits from the agent wallet`, usd };
	try {
		const r = await topupFromIntent({
			agentId: ctx.agentId,
			ownerId: ctx.ownerId,
			amountUsdc: usd,
			intentId: intent.id,
			idempotencyKey: `intent:${intent.id}:${discriminator}`,
		});
		if (r.status === 'skipped') return { status: 'skipped', note: r.note };
		if (r.status === 'settled') {
			return { status: 'ok', signature: r.signature, explorer: explorerTxUrl(r.signature, 'mainnet'), usd, note: `topped up $${r.credits_usd} of credits` };
		}
		return { status: 'paused', note: r.note || 'top-up broadcast, waiting for confirmation', signature: r.signature, usd };
	} catch (e) {
		if (e instanceof TopupError && e.status < 500) return { status: 'paused', note: e.message, usd };
		return { status: 'error', note: (e?.message || 'top-up failed').slice(0, 240), usd };
	}
}

async function gatedSpend({ ctx, intent, discriminator, category, usd, lamports, rowMeta, doSpend }) {
	const { agentId, ownerId, userId, network, dryRun, now } = ctx;

	// 1) intent-level caps (per-action / daily / total): the owner's own ceilings.
	// The per-action cap is exact here (one value against a constant); the daily and
	// lifetime budgets are re-checked atomically inside the claim in step 3, so this
	// pass exists to reject early with a precise message, not to be the gate.
	const capped = await intentCapVerdict({ ctx, intent, usd });
	if (capped) return capped;
	const lim = intent.limits || {};

	// 2) the agent spend policy: the SAME hard ceiling every outbound path obeys.
	// This runs every non-daily guard (freeze, allowlist, NL policy rules, per-tx
	// ceiling, anomaly, capability) and gives a fast, specific pause message. Its
	// daily-cap read is advisory only; the binding daily check is the atomic claim
	// below, which reserves headroom in the same statement that writes the row.
	//
	// A policy step-up ("ask me first") does not dead-end here: it queues the
	// exact action in the owner's approval inbox (api/_lib/approvals.js), and an
	// approval re-enters this function with ctx.approval set, which lifts only that
	// step-up. Every cap in this function still applies on the approved run.
	try {
		await enforceSpendLimit({
			agentId, meta: ctx.meta, category: 'intent', usdValue: usd, network,
			destination: rowMeta.destination || undefined,
			stepUpApproved: Boolean(ctx.approval),
		});
	} catch (e) {
		if (e instanceof SpendLimitError) {
			if (e.code === 'policy_step_up' && !dryRun && !ctx.approval) {
				return requestIntentApproval({ ctx, intent, discriminator, category, usd, lamports, rowMeta, gateReason: e.message, doSpend });
			}
			return { status: 'paused', note: e.message, usd };
		}
		throw e;
	}

	if (dryRun) return { status: 'would_run', note: `would move ~$${usd.toFixed(2)}`, usd };

	// 3) Atomic claim: one execution per (intent, discriminator) AND a reservation
	// against every rolling ceiling this spend answers to, in ONE statement under a
	// per-agent advisory lock.
	//
	// The idempotency key alone only stops the SAME intent firing twice (security
	// review M5). Racing distinct intents, or two overlapping sweeps, each read the
	// same pre-spend totals under the old read-then-write shape and each passed,
	// overshooting the wallet's daily USD cap and the rule's own budgets by up to
	// one spend apiece. Counting 'pending' rows inside the lock is what makes the
	// second caller see the first one's in-flight claim.
	const idemKey = `intent:${intent.id}:${discriminator}`;
	const dailyUsd = getSpendLimits(ctx.meta)?.daily_usd ?? null;
	const intentDailyUsd = lim.daily_usd ?? null;
	const intentTotalUsd = lim.total_usd ?? null;
	const sinceIso = new Date(now.getTime() - 24 * 3600 * 1000).toISOString();
	const claim = await runLocked([agentId], sql`
		WITH wallet_day AS (
			SELECT COALESCE(SUM(usd), 0)::float8 AS s
			FROM agent_custody_events
			WHERE agent_id = ${agentId} AND network = ${network} AND event_type = 'spend'
			  AND status IN ('ok', 'pending', 'confirmed') AND usd IS NOT NULL
			  AND created_at > now() - interval '24 hours'
		),
		rule_day AS (
			SELECT COALESCE(SUM(usd), 0)::float8 AS s
			FROM agent_custody_events
			WHERE agent_id = ${agentId} AND usd IS NOT NULL
			  AND status IN ('ok', 'pending', 'confirmed')
			  AND meta->>'intent_id' = ${intent.id}
			  AND created_at > ${sinceIso}::timestamptz
		),
		rule_life AS (
			SELECT COALESCE(SUM(usd), 0)::float8 AS s
			FROM agent_custody_events
			WHERE agent_id = ${agentId} AND usd IS NOT NULL
			  AND status IN ('ok', 'pending', 'confirmed')
			  AND meta->>'intent_id' = ${intent.id}
		)
		INSERT INTO agent_custody_events
			(agent_id, user_id, event_type, category, network, asset, amount_lamports, usd, status, idempotency_key, meta)
		SELECT ${agentId}, ${userId ?? ownerId ?? null}, 'spend', ${category}, ${network}, 'SOL',
		       ${lamports != null ? String(lamports) : null}, ${usd ?? null}, 'pending', ${idemKey},
		       ${JSON.stringify({ ...rowMeta, intent_id: intent.id, intent_title: intent.title, trigger: intent.trigger?.type, action: intent.action?.type, ...(ctx.approval ? { approval_id: ctx.approval.id } : {}) })}::jsonb
		FROM wallet_day, rule_day, rule_life
		WHERE NOT EXISTS (SELECT 1 FROM agent_custody_events WHERE agent_id = ${agentId} AND idempotency_key = ${idemKey})
		  AND (${dailyUsd}::float8 IS NULL OR wallet_day.s + ${usd}::float8 <= ${dailyUsd}::float8 + 1e-9)
		  AND (${intentDailyUsd}::float8 IS NULL OR rule_day.s + ${usd}::float8 <= ${intentDailyUsd}::float8 + 1e-9)
		  AND (${intentTotalUsd}::float8 IS NULL OR rule_life.s + ${usd}::float8 <= ${intentTotalUsd}::float8 + 1e-9)
		RETURNING id
	`);
	if (!claim.length) return await claimRejection({ agentId, intentId: intent.id, idemKey, usd, network, dailyUsd, intentDailyUsd, intentTotalUsd, sinceIso });
	const eventId = claim[0].id;

	try {
		const { signature } = await doSpend(lamports);
		await updateCustodyEvent(eventId, { status: 'confirmed', signature, meta: { settled_at: now.toISOString() } });
		return { status: 'ok', signature, explorer: explorerTxUrl(signature, network), usd };
	} catch (e) {
		await updateCustodyEvent(eventId, { status: 'failed', meta: { error: (e?.message || 'failed').slice(0, 200) } });
		return { status: 'error', note: (e?.message || 'transaction failed').slice(0, 240), usd };
	}
}

function shortKey(a) {
	const s = String(a || '');
	return s.length > 12 ? `${s.slice(0, 4)}...${s.slice(-4)}` : s;
}

// Queue a step-up-gated spend in the owner's approval inbox. The payload is
// everything executeApprovedIntentAction needs to run THIS action and nothing
// else; its hash is what the owner approves. An auto-approve policy that covers
// it runs it inline, under the same caps, without asking.
async function requestIntentApproval({ ctx, intent, discriminator, category, usd, lamports, rowMeta, gateReason, doSpend }) {
	const isSwap = Boolean(rowMeta.mint);
	const sol = Number(lamports) / 1e9;
	const solText = sol.toLocaleString('en-US', { maximumFractionDigits: 6 });
	const who = ctx.agentName || 'Your agent';
	const destination = rowMeta.destination || null;
	const payload = {
		v: 1,
		source: 'wallet_intent',
		agent_id: ctx.agentId,
		intent_id: intent.id,
		action_type: intent.action.type,
		category,
		network: ctx.network,
		discriminator,
		lamports: String(lamports),
		destination,
		destination_label: rowMeta.destination_label || null,
		mint: rowMeta.mint || null,
		slippage_bps: rowMeta.slippage_bps ?? null,
	};
	const riskNotes = [`Rule: "${intent.title}"`];
	let autoApprovable = true;
	if (isSwap) {
		riskNotes.push(`Swaps SOL into token ${rowMeta.mint}. Check the mint before approving.`);
		if (rowMeta.slippage_bps != null) riskNotes.push(`Max slippage ${(rowMeta.slippage_bps / 100).toFixed(1)}%. The price is re-quoted when you approve.`);
	} else {
		const priors = await countPriorSpendsTo(ctx.agentId, destination, ctx.network).catch(() => 0);
		if (priors === 0) {
			autoApprovable = false;
			riskNotes.push('This wallet has never paid this address before. Payments on Solana cannot be reversed.');
		} else {
			riskNotes.push(`This wallet has paid this address ${priors} time${priors === 1 ? '' : 's'} before.`);
		}
	}
	if (ctx.network !== 'mainnet') riskNotes.push(`Runs on Solana ${ctx.network}.`);

	const ref = `${intent.id}:${destination || rowMeta.mint || 'self'}`;
	let created;
	try {
		created = await createApprovalRequest({
			userId: ctx.ownerId,
			agentId: ctx.agentId,
			source: 'wallet_intent',
			sourceRef: ref,
			actionType: intent.action.type,
			venue: isSwap ? 'jupiter' : 'wallet_transfer',
			payload,
			summary: isSwap
				? `${who} wants to buy ${shortKey(rowMeta.mint)} with ${solText} SOL`
				: `${who} wants to send ${solText} SOL to ${rowMeta.destination_label || shortKey(destination)}`,
			amount: sol,
			amountUsd: Number.isFinite(usd) ? Math.round(usd * 100) / 100 : null,
			asset: 'SOL',
			chain: 'solana',
			network: ctx.network,
			recipient: isSwap ? ctx.address : destination,
			recipientLabel: isSwap ? `${who}'s own wallet (swap)` : (rowMeta.destination_label || null),
			riskNotes,
			gateReason,
			idempotencyKey: `wallet_intent:${intent.id}:${discriminator}`,
			ttlMs: isSwap ? TTL_MS.swap : TTL_MS.transfer,
			autoApprovable,
		});
	} catch (e) {
		return { status: 'paused', note: `${gateReason} (could not queue the approval: ${(e?.message || 'error').slice(0, 120)})`, usd };
	}
	const req = created.request;

	if (created.autoApproved) {
		const { outcome } = await runApproved(req, () => gatedSpend({
			ctx: { ...ctx, approval: { id: req.id, auto: true } },
			intent, discriminator, category, usd, lamports, rowMeta, doSpend,
		}));
		return outcome || { status: 'skipped', note: 'already handled through the approval inbox', usd };
	}

	switch (req.status) {
		case 'pending':
			return {
				status: 'awaiting_approval',
				note: created.created
					? `Waiting for your approval: ${req.summary}. Approve or deny it at /approvals.`
					: 'Waiting on your answer to an earlier approval request for this rule at /approvals.',
				usd,
				approval_id: req.id,
			};
		case 'denied':
			return { status: 'paused', note: 'You denied this action in the approval inbox.', usd, approval_id: req.id };
		case 'expired':
			return { status: 'paused', note: 'The approval request for this action expired unanswered, so nothing was sent.', usd, approval_id: req.id };
		default:
			return { status: 'skipped', note: 'already handled through the approval inbox', usd, approval_id: req.id };
	}
}

// Real SOL transfer from the agent's wallet → destination.
async function transferSol({ ctx, intent, discriminator, category, lamports, rowMeta }) {
	if (lamports <= 0n) return { status: 'skipped', note: 'amount rounds to zero' };
	// Keep a fee headroom so the wallet never bricks itself.
	const usable = ctx.balanceLamports - SOL_FEE_HEADROOM_LAMPORTS;
	if (lamports > usable) return { status: 'skipped', note: 'not enough SOL after the fee buffer' };
	const usd = await lamportsToUsd(lamports).catch(() => null);
	if (usd == null) return { status: 'paused', note: 'SOL/USD price feed unavailable — will retry' };
	return gatedSpend({
		ctx, intent, discriminator, category, usd, lamports, rowMeta,
		doSpend: async (lams) => ({ signature: await sendSol({ connection: ctx.conn, fromKeypair: ctx.keypair, to: rowMeta.destination, lamports: Number(lams), memo: `intent:${intent.action.type}`, network: ctx.network }) }),
	});
}

// Real SOL → token swap (Jupiter, mainnet) for buy/snipe.
async function buyToken({ ctx, intent, discriminator, mint, lamports, slippagePct, slippageBps: fixedBps = null }) {
	if (ctx.network !== 'mainnet') return { status: 'skipped', note: 'buys/snipes are mainnet-only — this wallet is on devnet' };
	if (lamports <= 0n) return { status: 'skipped', note: 'amount rounds to zero' };
	if ((ctx.balanceLamports - SOL_FEE_HEADROOM_LAMPORTS) < lamports) return { status: 'skipped', note: 'not enough SOL after the fee buffer' };
	const usd = await lamportsToUsd(lamports).catch(() => null);
	if (usd == null) return { status: 'paused', note: 'SOL/USD price feed unavailable — will retry' };
	// An approved request replays the exact slippage the owner was shown.
	const slippageBps = fixedBps != null ? Math.round(clamp(Number(fixedBps), 0, 5000)) : Math.round(clamp(slippagePct ?? 5, 0, 50) * 100);
	return gatedSpend({
		ctx, intent, discriminator, category: intent.action.type === 'snipe' ? 'snipe' : 'trade', usd, lamports,
		rowMeta: { action: intent.action.type, mint, slippage_bps: slippageBps },
		doSpend: async (lams) => {
			const res = await swapSolToToken({ keypair: ctx.keypair, lamports: lams, outputMint: mint, slippageBps, network: ctx.network, conn: ctx.conn });
			return { signature: res.signature };
		},
	});
}

// Build the Jupiter quote query from validated parts. The mint was interpolated
// raw, so a mint string carrying `&slippageBps=10000` or `&amount=` rewrote the
// quote the agent then signed. A mint must be a real base58 pubkey, slippage a
// bounded integer, and every value is encoded.
export function jupiterQuoteParams({ outputMint, lamports, slippageBps }) {
	let mint;
	try {
		mint = new PublicKey(String(outputMint)).toBase58();
	} catch {
		mint = null;
	}
	if (!mint || mint !== outputMint) {
		throw Object.assign(new Error('output mint is not a valid Solana address'), { code: 'invalid_mint' });
	}
	const bps = Math.trunc(Number(slippageBps));
	if (!Number.isFinite(bps) || bps < 0 || bps > 10_000) {
		throw Object.assign(new Error('slippage must be 0-10000 bps'), { code: 'invalid_slippage' });
	}
	return new URLSearchParams({
		inputMint: WSOL_MINT,
		outputMint: mint,
		amount: BigInt(lamports).toString(),
		slippageBps: String(bps),
		swapMode: 'ExactIn',
	}).toString();
}

async function swapSolToToken({ keypair, lamports, outputMint, slippageBps, conn }) {
	const { VersionedTransaction } = await import('@solana/web3.js');
	const qUrl = `${JUPITER_BASE}/quote?${jupiterQuoteParams({ outputMint, lamports, slippageBps })}`;
	const qRes = await fetchWithTimeout(qUrl, {}, 15_000);
	if (!qRes.ok) throw Object.assign(new Error(`no swap route (${qRes.status})`), { code: 'no_route' });
	const quote = await qRes.json();
	if (!quote?.outAmount) throw Object.assign(new Error('no swap route for this pair'), { code: 'no_route' });
	const sRes = await fetchWithTimeout(`${JUPITER_BASE}/swap`, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({ quoteResponse: quote, userPublicKey: keypair.publicKey.toBase58(), wrapAndUnwrapSol: true, dynamicComputeUnitLimit: true, prioritizationFeeLamports: 'auto' }),
	}, 20_000);
	if (!sRes.ok) throw Object.assign(new Error(`swap build failed (${sRes.status})`), { code: 'swap_failed' });
	const { swapTransaction } = await sRes.json();
	if (!swapTransaction) throw Object.assign(new Error('swap build returned no transaction'), { code: 'swap_failed' });
	const tx = VersionedTransaction.deserialize(Buffer.from(swapTransaction, 'base64'));
	tx.sign([keypair]);
	const sig = await conn.sendRawTransaction(tx.serialize(), { skipPreflight: false, maxRetries: 3 });
	const bh = await conn.getLatestBlockhash();
	// HTTP-polling confirm (no WebSocket) — throws on a landed-but-reverted swap so
	// a revert is never reported back as a successful intent execution.
	await confirmOrThrow(conn, { signature: sig, ...bh }, 'confirmed');
	return { signature: sig, outAmount: quote.outAmount };
}

// Notify the owner (real audit event + best-effort email). No funds move.
async function notifyOwner({ ctx, intent, discriminator, subject, body }) {
	const idemKey = `intent:${intent.id}:${discriminator}`;
	const claim = await sql`
		INSERT INTO agent_custody_events (agent_id, user_id, event_type, category, network, reason, status, idempotency_key, meta)
		SELECT ${ctx.agentId}, ${ctx.ownerId ?? null}, 'intent_notify', 'notify', ${ctx.network}, ${subject.slice(0, 200)}, 'ok', ${idemKey},
		       ${JSON.stringify({ intent_id: intent.id, intent_title: intent.title, message: body })}::jsonb
		WHERE NOT EXISTS (SELECT 1 FROM agent_custody_events WHERE agent_id = ${ctx.agentId} AND idempotency_key = ${idemKey})
		RETURNING id
	`;
	if (!claim.length) return { status: 'skipped', note: 'already notified for this event' };
	// Best-effort email to the owner — never block on the channel being configured.
	try {
		const { sendEmail } = await import('./email.js');
		const [u] = await sql`SELECT email FROM users WHERE id = ${ctx.ownerId}`;
		if (u?.email) await sendEmail({ to: u.email, subject, html: `<p>${body}</p><p style="color:#888">— your agent's wallet copilot</p>` }).catch(() => {});
	} catch { /* email optional */ }
	return { status: 'notified', note: body.slice(0, 200) };
}

// ── the action dispatcher ──────────────────────────────────────────────────────────

async function executeAction(intent, ctx, event = {}) {
	const a = intent.action;
	const now = ctx.now;

	// Resolve the moving amount in lamports for the SOL-moving actions.
	const resolveLamports = async () => {
		if (a.pct != null) {
			if (a.of === 'tip' || a.of === 'income') {
				// % of the triggering event value, taken in SOL.
				const eventSol = event.amount_sol != null ? event.amount_sol : (event.usd != null ? event.usd / ctx.price : 0);
				return solToLamports(eventSol * (a.pct / 100));
			}
			if (a.of === 'balance') return BigInt(Math.floor(Number(ctx.balanceLamports) * (a.pct / 100)));
		}
		if (a.above_sol != null) {
			// "withdraw profit above N SOL" → everything over the floor (minus headroom).
			const over = ctx.balanceLamports - solToLamports(a.above_sol);
			return over > 0n ? over : 0n;
		}
		if (a.amount_sol != null) return solToLamports(a.amount_sol);
		return 0n;
	};

	switch (a.type) {
		case 'freeze': {
			// Kill switch: freeze every outbound spend + notify. Idempotent per breach/day.
			const disc = ctx.discriminator || `bal:${now.toISOString().slice(0, 10)}`;
			if (!ctx.dryRun) {
				const limits = getSpendLimits(ctx.meta);
				if (!limits.frozen) await setSpendLimits(intent.agent_id || ctx.agentId, ctx.ownerId, { frozen: true }).catch(() => {});
			}
			const note = `Spending frozen${event.balance_sol != null ? ` — balance ${event.balance_sol.toFixed(4)} SOL is below your ${intent.trigger.threshold_sol} SOL floor` : ''}.`;
			if (ctx.dryRun) return { status: 'would_run', note };
			const n = await notifyOwner({ ctx, intent, discriminator: disc, subject: `${ctx.agentName || 'Your agent'}: wallet frozen`, body: note });
			return { status: 'ok', note, frozen: true, notify: n.status };
		}
		case 'fund_inference': {
			// One top-up per UTC day per rule, whatever fired it.
			return fundInference({ ctx, intent, discriminator: ctx.discriminator || `credits:${now.toISOString().slice(0, 10)}` });
		}
		case 'notify': {
			const disc = ctx.discriminator || `notify:${now.toISOString().slice(0, 13)}`;
			const body = a.message || describeIntent(intent);
			if (ctx.dryRun) return { status: 'would_run', note: body };
			return notifyOwner({ ctx, intent, discriminator: disc, subject: `${ctx.agentName || 'Your agent'}: ${intent.title}`, body });
		}
		case 'buy':
		case 'snipe': {
			const mint = ctx.overrideMint || a.mint;
			if (!mint || !BASE58_RE.test(mint)) return { status: 'skipped', note: 'no valid mint to buy' };
			const lamports = solToLamports(a.amount_sol);
			return buyToken({ ctx, intent, discriminator: ctx.discriminator || `buy:${mint}`, mint, lamports, slippagePct: a.slippage_pct });
		}
		case 'tip':
		case 'transfer':
		case 'withdraw':
		case 'split_income': {
			let destination = a.destination;
			if (a.to_tipper && event.from) destination = event.from; // tip-back to the tipper
			if (!destination || !BASE58_RE.test(destination)) return { status: 'skipped', note: 'no valid destination' };
			const lamports = await resolveLamports();
			if (lamports <= 0n) return { status: 'skipped', note: 'nothing to send for this event' };
			const category = a.type === 'withdraw' ? 'withdraw' : a.type === 'split_income' ? 'split' : 'transfer';
			return transferSol({
				ctx, intent, discriminator: ctx.discriminator || `${a.type}:${event.signature || now.toISOString().slice(0, 13)}`,
				category, lamports, rowMeta: { action: a.type, destination, destination_label: a.destination_label },
			});
		}
		default:
			return { status: 'skipped', note: 'unknown action' };
	}
}

// ── execution context (loads the agent, gates safety, recovers the key once) ─────

async function buildExecContext({ agentId, userId, network, dryRun, needsKey }) {
	const [row] = await sql`SELECT id, user_id, name, meta, status FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;
	if (!row) return { error: 'not_found' };
	// A stopped agent pauses every intent without deleting it. An owner's dry run
	// still reports what would happen.
	if (row.status === 'stopped' && !dryRun) return { error: 'agent_stopped' };
	const meta = row.meta || {};
	const address = meta.solana_address;
	const encryptedSecret = meta.encrypted_solana_secret;
	if (!address) return { error: 'no_wallet' };

	const limits = getSpendLimits(meta);
	if (limits.frozen && needsKey) return { error: 'wallet_frozen' };

	let price;
	try { price = await solUsdPrice(); } catch { return { error: 'price_unavailable' }; }

	const conn = solanaConnection(network);
	let balanceSol = 0;
	try { balanceSol = Number((await getSolanaAddressBalances(address, network))?.sol || 0); }
	catch (e) { return { error: 'balance_read_failed', detail: e?.message }; }

	let keypair = null;
	if (needsKey && !dryRun) {
		if (!encryptedSecret) return { error: 'no_secret' };
		try { keypair = await recoverSolanaAgentKeypair(encryptedSecret, { agentId, userId: userId ?? row.user_id, reason: 'wallet_intent' }); }
		catch (e) { return { error: 'key_recover_failed', detail: e?.message }; }
	}

	return {
		ctx: {
			agentId, agentName: row.name, ownerId: row.user_id, userId, network, dryRun,
			now: new Date(), conn, price, meta, address,
			balanceSol, balanceLamports: solToLamports(balanceSol), keypair,
		},
	};
}

async function stampFire(intent, res, now = new Date()) {
	const moved = res.status === 'ok' && res.usd ? Number(res.usd) : 0;
	await sql`
		UPDATE agent_wallet_intents SET
			fire_count = fire_count + ${res.status === 'ok' || res.status === 'notified' ? 1 : 0},
			spent_usd = spent_usd + ${moved},
			last_fired_at = ${now.toISOString()},
			last_status = ${res.status},
			last_note = ${(res.note || (res.signature ? 'executed' : null) || res.status)?.slice?.(0, 280) ?? null},
			last_signature = ${res.signature || null},
			updated_at = now()
		WHERE id = ${intent.id}
	`;
}

// ── approval inbox executor ─────────────────────────────────────────────────────

/**
 * Run the exact action an owner approved in the inbox (api/_lib/approvals.js
 * registers this as the `wallet_intent` executor). Only the stored payload is
 * executed: the same amount in lamports, the same recipient or mint, the same
 * slippage, under the same custody idempotency key the gated fire would have
 * used, so an approval can never move funds twice for one event. The intent's
 * own caps and every wallet ceiling still apply; only the step-up the owner
 * answered is lifted.
 *
 * @param {object} row  the approval_requests row, already claimed as executing
 * @returns {Promise<{ status: string, note?: string, signature?: string, usd?: number }>}
 */
export async function executeApprovedIntentAction(row) {
	const p = row.payload || {};
	const intent = await getIntent(p.agent_id, p.intent_id);
	if (!intent) return { status: 'error', note: 'The rule behind this request was deleted, so nothing was executed.' };
	if (intent.action.type !== p.action_type) return { status: 'error', note: 'The rule changed after this request was made, so nothing was executed.' };
	let lamports;
	try { lamports = BigInt(p.lamports); } catch { return { status: 'error', note: 'The approved amount is unreadable, so nothing was executed.' }; }

	const built = await buildExecContext({ agentId: p.agent_id, userId: row.user_id, network: p.network || 'mainnet', dryRun: false, needsKey: true });
	if (built.error) return { status: 'error', note: `Could not execute: ${built.detail || built.error}` };
	const ctx = built.ctx;
	if (String(ctx.ownerId) !== String(row.user_id)) return { status: 'error', note: 'This agent is no longer owned by the account that approved it, so nothing was executed.' };
	ctx.discriminator = p.discriminator;
	ctx.approval = { id: row.id };

	let res;
	try {
		res = p.mint
			? await buyToken({ ctx, intent, discriminator: p.discriminator, mint: p.mint, lamports, slippageBps: p.slippage_bps })
			: await transferSol({
				ctx, intent, discriminator: p.discriminator, category: p.category, lamports,
				rowMeta: { action: p.action_type, destination: p.destination, destination_label: p.destination_label || undefined },
			});
	} catch (e) {
		res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) };
	}
	await stampFire(intent, res, ctx.now).catch(() => {});
	return res;
}

// ── public entrypoints ─────────────────────────────────────────────────────────────

/**
 * Owner-initiated "test this rule now" — runs the real (or dry) execution path for
 * a single intent. Honors freeze, spend policy, and the intent's caps exactly like
 * the scheduler. dryRun reports what WOULD happen without moving funds.
 */
export async function runIntentNow({ agentId, userId, intentId, network = 'mainnet', dryRun = true }) {
	const intent = await getIntent(agentId, intentId);
	if (!intent) return { ran: false, reason: 'not_found' };
	if (!intent.enabled && !dryRun) return { ran: false, reason: 'disabled' };

	const needsKey = SPENDING_ACTIONS.has(intent.action.type);
	const built = await buildExecContext({ agentId, userId, network, dryRun, needsKey });
	if (built.error) return { ran: false, reason: built.error, note: built.detail || null };
	const ctx = built.ctx;

	// Synthesize a representative event for triggers that need one, so the dry-run is
	// concrete (e.g. tip-back shows what it would send on a sample tip).
	const event = synthEvent(intent, ctx);
	ctx.discriminator = dryRun ? `dryrun:${Date.now ? 'now' : 'x'}` : `manual:${ctx.now.toISOString()}`;
	if (intent.trigger.type === 'on_launch_matching' && intent.action.type === 'snipe') {
		// A manual test of a snipe rule can't pick a real launch — report readiness.
		return { ran: true, dryRun, results: [{ ...intentSummary(intent), status: 'would_run', note: `armed — will snipe up to ${intent.action.amount_sol} SOL on the next matching launch` }] };
	}

	let res;
	try { res = await executeAction(intent, ctx, event); }
	catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
	if (!dryRun) await stampFire(intent, res, ctx.now).catch(() => {});
	return { ran: true, dryRun, results: [{ ...intentSummary(intent), ...res }] };
}

/**
 * Execute one intent for a v1 automation whose trigger just fired. Same guarded
 * path as the sweep: freeze, spend policy, the intent's own caps, and the
 * idempotent custody claim keyed by `discriminator` (one execution per fire).
 *
 * @param {object} o
 * @param {string} o.agentId
 * @param {string} o.intentId
 * @param {string} o.discriminator  unique per fire, e.g. `auto:<id>:<event>`
 * @param {object} [o.event]        trigger event ({ amount_sol, from, signature, mint })
 * @param {string} [o.network]
 */
export async function fireIntentForAutomation({ agentId, intentId, discriminator, event = {}, network = 'mainnet' }) {
	const intent = await getIntent(agentId, intentId);
	if (!intent) return { status: 'error', note: 'backing intent not found' };
	if (!intent.enabled) return { status: 'skipped', note: 'backing intent disabled' };
	const built = await buildExecContext({
		agentId,
		userId: null,
		network,
		dryRun: false,
		needsKey: SPENDING_ACTIONS.has(intent.action.type),
	});
	if (built.error) {
		const res = { status: 'paused', note: built.error };
		await stampFire(intent, res).catch(() => {});
		return res;
	}
	const ctx = built.ctx;
	ctx.discriminator = discriminator;
	if (intent.action.mint_from_event && event.mint) ctx.overrideMint = event.mint;
	let res;
	try {
		res = await executeAction(intent, ctx, event);
	} catch (e) {
		res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) };
	}
	await stampFire(intent, res, ctx.now).catch(() => {});
	return res;
}

function intentSummary(intent) {
	return { id: intent.id, title: intent.title, trigger: intent.trigger.type, action: intent.action.type };
}

function synthEvent(intent, ctx) {
	const t = intent.trigger;
	if (t.type === 'on_tip_received' || t.type === 'on_income') {
		const sampleSol = Math.max(t.min_sol || 0.1, 0.1);
		return { amount_sol: sampleSol, usd: sampleSol * ctx.price, from: null, signature: null, sample: true };
	}
	if (t.type === 'on_balance_below') return { balance_sol: ctx.balanceSol };
	if (t.type === 'credits_below') return { credits_usd: null };
	return {};
}

/**
 * Fired from the tip-recording path: evaluate this agent's on_tip_received /
 * on_income intents against a freshly-recorded REAL tip and execute any that
 * match. Idempotent per (intent, tip signature) via the custody claim.
 *
 * @param {object} tip { signature, amount_sol, usd, from, network }
 */
export async function onTipRecorded(agentId, tip) {
	try {
		const rows = await sql`
			SELECT * FROM agent_wallet_intents
			WHERE agent_id = ${agentId} AND enabled = true AND trigger_type IN ('on_tip_received', 'on_income')
		`;
		if (!rows.length) return { fired: 0 };
		const network = tip.network === 'devnet' ? 'devnet' : 'mainnet';
		const intents = rows.map(rowToIntent).filter((i) => {
			if (i.network !== network) return false;
			if (i.trigger.type === 'on_tip_received') return (tip.amount_sol ?? 0) >= (i.trigger.min_sol || 0);
			return true; // on_income — any inflow
		});
		if (!intents.length) return { fired: 0 };

		const needsKey = intents.some((i) => SPENDING_ACTIONS.has(i.action.type));
		const built = await buildExecContext({ agentId, userId: null, network, dryRun: false, needsKey });
		if (built.error) {
			console.warn('[wallet-intents] tip eval skipped:', built.error);
			return { fired: 0, reason: built.error };
		}
		const ctx = built.ctx;
		const event = { amount_sol: tip.amount_sol ?? null, usd: tip.usd ?? null, from: tip.from || null, signature: tip.signature || null };

		let fired = 0;
		for (const intent of intents) {
			ctx.discriminator = `${intent.action.type}:tip:${tip.signature || ctx.now.toISOString()}`;
			let res;
			try { res = await executeAction(intent, ctx, event); }
			catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
			await stampFire(intent, res, ctx.now).catch(() => {});
			if (res.status === 'ok' || res.status === 'notified') fired++;
		}
		return { fired };
	} catch (e) {
		console.warn('[wallet-intents] onTipRecorded failed', e?.message);
		return { fired: 0, error: e?.message };
	}
}

/**
 * Fired from the money-stream settlement path. A stream's FIRST settlement is its
 * "started" moment; every settlement is also income. Evaluate this agent's
 * on_stream_started (first settlement only) and on_income (every settlement) intents
 * against the real, on-chain-verified settlement and execute any that match. Each
 * fire is idempotent via the custody claim — on_stream_started per stream_id (one
 * fire per session), on_income per settlement signature.
 *
 * @param {object} stream { stream_id, signature, amount_sol, usd, from, network, first }
 */
export async function onStreamSettled(agentId, stream) {
	try {
		const first = stream.first === true;
		// On a non-first settlement there's nothing for the stream-start trigger to do,
		// so don't even load it — only income rules apply to a mid-stream settlement.
		const triggerTypes = first ? ['on_stream_started', 'on_income'] : ['on_income'];
		const rows = await sql`
			SELECT * FROM agent_wallet_intents
			WHERE agent_id = ${agentId} AND enabled = true AND trigger_type = ANY(${triggerTypes})
		`;
		if (!rows.length) return { fired: 0 };
		const network = stream.network === 'devnet' ? 'devnet' : 'mainnet';
		const intents = rows.map(rowToIntent).filter((i) => i.network === network);
		if (!intents.length) return { fired: 0 };

		const needsKey = intents.some((i) => SPENDING_ACTIONS.has(i.action.type));
		const built = await buildExecContext({ agentId, userId: null, network, dryRun: false, needsKey });
		if (built.error) {
			console.warn('[wallet-intents] stream eval skipped:', built.error);
			return { fired: 0, reason: built.error };
		}
		const ctx = built.ctx;
		const event = { amount_sol: stream.amount_sol ?? null, usd: stream.usd ?? null, from: stream.from || null, signature: stream.signature || null };

		let fired = 0;
		for (const intent of intents) {
			// on_stream_started: one fire per stream session. on_income: one per settlement.
			ctx.discriminator = intent.trigger.type === 'on_stream_started'
				? `${intent.action.type}:stream:${stream.stream_id}`
				: `${intent.action.type}:streamincome:${stream.signature || ctx.now.toISOString()}`;
			let res;
			try { res = await executeAction(intent, ctx, event); }
			catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
			await stampFire(intent, res, ctx.now).catch(() => {});
			if (res.status === 'ok' || res.status === 'notified') fired++;
		}
		return { fired };
	} catch (e) {
		console.warn('[wallet-intents] onStreamSettled failed', e?.message);
		return { fired: 0, error: e?.message };
	}
}

/**
 * Sender filter for on_mail_received. The filter is an exact address, a domain
 * ("acme.example" or "@acme.example"), and a domain also covers its subdomains.
 * Never a substring, so "acme.example" cannot match "[email protected]".
 */
export function mailSenderMatches(filter, from) {
	const f = String(filter || '').trim().toLowerCase();
	const sender = String(from || '').trim().toLowerCase();
	const at = sender.lastIndexOf('@');
	if (!f || at < 1) return false;
	if (f.includes('@') && !f.startsWith('@')) return f === sender;
	const wanted = f.replace(/^@/, '');
	const domain = sender.slice(at + 1);
	return domain === wanted || domain.endsWith(`.${wanted}`);
}

/**
 * Fired by agent mail after an inbound message is stored. Evaluates this
 * agent's on_mail_received intents against the sender and subject filters the
 * owner wrote, then runs the matching ones. Only notify and freeze can pair
 * with this trigger (normalizeIntent enforces it), so nothing here signs a
 * transaction, and neither action reads the email: the notification carries
 * the owner's own message, never the sender's words. One fire per message. Fails closed unless the sender passed DMARC (mail.authenticated).
 *
 * @param {object} mail { message_id, from, subject, spam_score, authenticated }
 */
export async function onMailReceived(agentId, mail) {
	if (mail?.authenticated !== true) return { fired: 0, reason: 'unauthenticated_sender' };
	try {
		const rows = await sql`
			SELECT * FROM agent_wallet_intents
			WHERE agent_id = ${agentId} AND enabled = true AND trigger_type = 'on_mail_received'
		`;
		if (!rows.length) return { fired: 0 };
		const from = String(mail.from || '').toLowerCase();
		const subject = String(mail.subject || '').toLowerCase();
		const intents = rows.map(rowToIntent).filter((i) => {
			if (!['notify', 'freeze'].includes(i.action.type)) return false;
			if (i.trigger.from_contains && !mailSenderMatches(i.trigger.from_contains, from)) return false;
			if (i.trigger.subject_contains && !subject.includes(i.trigger.subject_contains)) return false;
			return true;
		});
		if (!intents.length) return { fired: 0 };

		const network = intents[0].network === 'devnet' ? 'devnet' : 'mainnet';
		const built = await buildExecContext({ agentId, userId: null, network, dryRun: false, needsKey: false });
		if (built.error) {
			console.warn('[wallet-intents] mail eval skipped:', built.error);
			return { fired: 0, reason: built.error };
		}
		const ctx = built.ctx;

		let fired = 0;
		for (const intent of intents) {
			ctx.discriminator = `${intent.action.type}:mail:${mail.message_id}`;
			let res;
			try { res = await executeAction(intent, ctx, {}); }
			catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
			await stampFire(intent, res, ctx.now).catch(() => {});
			if (res.status === 'ok' || res.status === 'notified') fired++;
		}
		return { fired };
	} catch (e) {
		console.warn('[wallet-intents] onMailReceived failed', e?.message);
		return { fired: 0, error: e?.message };
	}
}

const UTC_WEEKDAY = (d) => d.getUTCDay();

function scheduleDue(intent, now) {
	const t = intent.trigger;
	if (t.cadence === 'weekly' && t.weekday != null && UTC_WEEKDAY(now) !== t.weekday) return false;
	return now.getUTCHours() === (t.hour ?? 13);
}

/**
 * The cron sweep: evaluate every enabled scheduled / balance / launch intent
 * across all agents and execute the due ones. (Tip/income/stream intents fire
 * inline from their event hooks — onTipRecorded / onStreamSettled.) Each kind is
 * bounded and idempotent. Returns a per-trigger summary (no secrets).
 */
export async function runIntentSweep({ network = 'mainnet', now = new Date(), launchLimit = 60 } = {}) {
	const summary = { scanned: 0, fired: 0, by_trigger: {}, errors: 0 };

	// 1) scheduled intents whose hour/weekday is now.
	const scheduled = (await sql`
		SELECT * FROM agent_wallet_intents WHERE enabled = true AND trigger_type = 'on_schedule' AND network = ${network}
	`).map(rowToIntent).filter((i) => scheduleDue(i, now));
	for (const intent of scheduled) {
		summary.scanned++;
		const r = await fireScheduledLike(intent, network, now, `sched:${isoBucket(intent.trigger, now)}`);
		tallySweep(summary, intent.trigger.type, r);
	}

	// 2) balance-floor intents — poll each agent's SOL balance.
	const balance = (await sql`
		SELECT * FROM agent_wallet_intents WHERE enabled = true AND trigger_type = 'on_balance_below' AND network = ${network}
	`).map(rowToIntent);
	for (const intent of balance) {
		summary.scanned++;
		const r = await fireBalanceIntent(intent, network, now);
		tallySweep(summary, intent.trigger.type, r);
	}

	// 3) credits-floor intents: top the owner's account credits up from the agent
	// wallet when they fall under the rule's threshold (fund_inference).
	const credits = (await sql`
		SELECT * FROM agent_wallet_intents WHERE enabled = true AND trigger_type = 'credits_below' AND network = ${network}
	`).map(rowToIntent);
	for (const intent of credits) {
		summary.scanned++;
		const r = await fireCreditsIntent(intent, network, now);
		tallySweep(summary, intent.trigger.type, r);
	}

	// 4) launch-matching intents: one shared pull of recent launches, matched per rule.
	const launch = (await sql`
		SELECT * FROM agent_wallet_intents WHERE enabled = true AND trigger_type = 'on_launch_matching' AND network = ${network}
	`).map(rowToIntent);
	if (launch.length && network === 'mainnet') {
		let launches = [];
		try { launches = await recentPumpLaunches({ network, limit: launchLimit }); } catch { launches = []; }
		let solPrice = 0;
		try { solPrice = await solUsdPrice(); } catch { solPrice = 0; }
		for (const intent of launch) {
			summary.scanned++;
			const r = await fireLaunchIntent(intent, network, now, launches, solPrice);
			tallySweep(summary, intent.trigger.type, r);
		}
	}

	return summary;
}

function isoBucket(trigger, now) {
	if (trigger.cadence === 'weekly') {
		// year-week bucket
		const oneJan = Date.UTC(now.getUTCFullYear(), 0, 1);
		const week = Math.ceil(((now.getTime() - oneJan) / 86400000 + 1) / 7);
		return `${now.getUTCFullYear()}-W${week}`;
	}
	return now.toISOString().slice(0, 10);
}

function tallySweep(summary, triggerType, r) {
	summary.by_trigger[triggerType] = (summary.by_trigger[triggerType] || 0) + 1;
	if (r?.status === 'ok' || r?.status === 'notified') summary.fired++;
	if (r?.status === 'error') summary.errors++;
}

async function fireScheduledLike(intent, network, now, discriminator) {
	const needsKey = SPENDING_ACTIONS.has(intent.action.type);
	const built = await buildExecContext({ agentId: intent.agent_id, userId: null, network, dryRun: false, needsKey });
	if (built.error) { const res = { status: 'paused', note: built.error }; await stampFire(intent, res, now).catch(() => {}); return res; }
	const ctx = built.ctx; ctx.discriminator = discriminator; ctx.now = now;
	let res;
	try { res = await executeAction(intent, ctx, { balance_sol: ctx.balanceSol }); }
	catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
	await stampFire(intent, res, now).catch(() => {});
	return res;
}

async function fireBalanceIntent(intent, network, now) {
	const built = await buildExecContext({ agentId: intent.agent_id, userId: null, network, dryRun: false, needsKey: SPENDING_ACTIONS.has(intent.action.type) });
	if (built.error) { const res = { status: 'paused', note: built.error }; await stampFire(intent, res, now).catch(() => {}); return res; }
	const ctx = built.ctx; ctx.now = now;
	if (ctx.balanceSol >= intent.trigger.threshold_sol) {
		return { status: 'skipped', note: `balance ${ctx.balanceSol.toFixed(4)} SOL is above the ${intent.trigger.threshold_sol} SOL floor` };
	}
	// Idempotent per UTC day so a sustained low balance notifies/freezes at most daily.
	ctx.discriminator = `bal:${now.toISOString().slice(0, 10)}`;
	let res;
	try { res = await executeAction(intent, ctx, { balance_sol: ctx.balanceSol }); }
	catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
	await stampFire(intent, res, now).catch(() => {});
	return res;
}

async function fireCreditsIntent(intent, network, now) {
	const built = await buildExecContext({ agentId: intent.agent_id, userId: null, network, dryRun: false, needsKey: false });
	if (built.error) { const res = { status: 'paused', note: built.error }; await stampFire(intent, res, now).catch(() => {}); return res; }
	const ctx = built.ctx; ctx.now = now;
	const acct = await getCreditAccount(ctx.ownerId);
	if (acct.balanceUsd >= intent.trigger.threshold_usd) {
		return { status: 'skipped', note: `credits $${acct.balanceUsd.toFixed(2)} are above the $${intent.trigger.threshold_usd} floor` };
	}
	ctx.discriminator = `credits:${now.toISOString().slice(0, 10)}`;
	let res;
	try { res = await executeAction(intent, ctx, { credits_usd: acct.balanceUsd }); }
	catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
	await stampFire(intent, res, now).catch(() => {});
	return res;
}

async function fireLaunchIntent(intent, network, now, launches, solPrice) {
	const t = intent.trigger;
	// Match by creator and/or market cap. Creator-gated rules enrich on demand.
	let match = null;
	for (const raw of launches) {
		if (!raw?.mint) continue;
		if (t.creator && raw.creator !== t.creator) continue;
		const mc = raw.market_cap_usd;
		if (t.max_mcap_usd != null && !(mc != null && mc <= t.max_mcap_usd)) continue;
		if (t.min_mcap_usd != null && !(mc != null && mc >= t.min_mcap_usd)) continue;
		match = raw;
		break;
	}
	if (!match) return { status: 'skipped', note: 'no launch matched this cycle' };
	if (t.creator) { try { await enrichCreatorStats(match, solPrice); } catch { /* best effort */ } }

	const built = await buildExecContext({ agentId: intent.agent_id, userId: null, network, dryRun: false, needsKey: true });
	if (built.error) { const res = { status: 'paused', note: built.error }; await stampFire(intent, res, now).catch(() => {}); return res; }
	const ctx = built.ctx; ctx.now = now;
	ctx.overrideMint = match.mint;
	ctx.discriminator = `snipe:${match.mint}`; // one buy per matched mint, ever
	let res;
	try { res = await executeAction(intent, ctx, {}); }
	catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }
	if (res.signature || res.status === 'ok') res.note = `sniped ${match.symbol || match.mint.slice(0, 6)} @ ~$${Math.round(match.market_cap_usd || 0).toLocaleString()} mc`;
	await stampFire(intent, res, now).catch(() => {});
	return res;
}

// Public, read-only persona traits (owner opt-in). Visitors may see the BEHAVIOR,
// never the rule, caps, or controls. Used by public agent surfaces.
export async function publicIntentTraits(agentId) {
	const rows = await sql`
		SELECT trigger_type, action_type, title FROM agent_wallet_intents
		WHERE agent_id = ${agentId} AND enabled = true AND public_trait = true
		ORDER BY created_at DESC LIMIT 6
	`;
	return rows.map((r) => ({
		label: traitLabel(r.trigger_type, r.action_type) || r.title,
		trigger: r.trigger_type,
		action: r.action_type,
	}));
}

function traitLabel(trigger, action) {
	if (trigger === 'on_tip_received' && action === 'tip') return 'Tips back generously';
	if (action === 'split_income') return 'Shares its income';
	if (trigger === 'on_launch_matching' && action === 'snipe') return 'Snipes fresh launches';
	if (action === 'freeze') return 'Self-protects on low balance';
	if (action === 'fund_inference') return 'Pays for its own thinking';
	return null;
}