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.

12.9 KB
Raw Blame
// @ts-check
/**
 * The three.ws sniper fleet expressed as an @three-ws/agent-vitals chart.
 *
 * This is the concrete answer to "why is this armed bot not trading", built
 * from the failure that motivated the whole library. On 2026-08-28 ten of
 * twelve armed arms had not attempted an entry in weeks while the worker
 * reported Ready:True with minScale 1, the launch feed was flowing, and every
 * strategy row said enabled = true. Three independent causes were stacked:
 *
 *   - the deployed worker image predated the commit that moved every free LLM
 *     rung onto models that still exist, so the whole chain answered 404/410;
 *   - the model providers behind the surviving rungs were out of credit (402)
 *     or on a billing hold (403);
 *   - several arm wallets could not fund a single entry.
 *
 * Every one of those was individually invisible, and a flat checklist would
 * have shown three red rows without saying which to chase. The `needs` edges
 * below encode the real causality: for an arm that needs a model, cognition
 * cannot be judged while the image is stale, and an entry cannot be judged
 * while cognition is down. Attesting this chart returns the deepest cause and
 * the command that fixes it.
 *
 * Every probe reads a real system: the strategies table, the position ledger,
 * a Solana RPC, the live launch feed, the deployed image digest. Nothing here
 * is sampled, cached or simulated.
 *
 * @example
 * import { sniperChart } from './api/_lib/agent-vitals/sniper-chart.js';
 * const verdict = await sniperChart({ strategy, balanceSol }).attest();
 * verdict.can.enter;      // false
 * verdict.explain();      // 'cannot enter because cognition is blocked, because ...'
 */

import { vitals } from '../../../packages/agent-vitals/src/index.js';
import { walletTradeState } from '../sniper-solvency.js';
import { fundTargetSol } from '../agent-funding-policy.js';

/** How long an armed arm may go without ATTEMPTING an entry before it is stalled. */
export const STALE_ENTRY_MS = 7 * 24 * 60 * 60 * 1000;

/**
 * How stale the launch feed may be before an arm has nothing to look at. The
 * pump.fun feed produces candidates continuously, so a gap this long is an
 * upstream outage, not a quiet market.
 */
export const STALE_FEED_MS = 30 * 60 * 1000;

/** A worker image older than this is a deploy-drift suspect, not a fresh rollout. */
export const STALE_IMAGE_MS = 7 * 24 * 60 * 60 * 1000;

const SUBMIT_WORKER =
	'gcloud builds submit --config workers/agent-sniper/cloudbuild.yaml --region us-central1 ' +
	'--project aerial-vehicle-466722-p5 --substitutions=SHORT_SHA=manual$(date +%s)';

const humanAge = (ms) => {
	if (!Number.isFinite(ms) || ms < 0) return 'unknown age';
	const days = Math.floor(ms / 86_400_000);
	if (days >= 1) return `${days} day${days === 1 ? '' : 's'}`;
	const hours = Math.floor(ms / 3_600_000);
	if (hours >= 1) return `${hours} hour${hours === 1 ? '' : 's'}`;
	return `${Math.max(1, Math.floor(ms / 60_000))} min`;
};

/**
 * @typedef {object} SniperArmInput
 * @property {object} strategy            a row from agent_sniper_strategies
 * @property {number|null} [balanceSol]   live wallet balance; null when unread
 * @property {string|null} [wallet]       the arm's trading wallet address
 * @property {Date|string|null} [lastEntryAt]  most recent entry ATTEMPT
 * @property {Date|string|null} [feedFreshAt]  most recent launch seen by the feed
 * @property {Date|string|null} [imageBuiltAt] build time of the running worker image
 * @property {{ ok: boolean|null, detail?: string }} [cognition] model-chain reachability
 * @property {{ ok: boolean|null, detail?: string }} [rpc]       RPC reachability
 */

const asTime = (v) => {
	if (!v) return null;
	const t = v instanceof Date ? v.getTime() : Date.parse(String(v));
	return Number.isFinite(t) ? t : null;
};

/**
 * Build the vitals chart for one sniper arm.
 *
 * Readings are injected rather than fetched here so the chart stays pure and
 * a caller sweeping a whole fleet pays for one RPC round and one feed read
 * instead of one per arm. `api/_lib/agent-vitals/sniper-probe.js` does that
 * gathering against the live systems.
 *
 * @param {SniperArmInput} input
 * @param {{ now?: number }} [opts]
 * @returns {import('../../../packages/agent-vitals/src/index.js').VitalsChart}
 */
export function sniperChart(input, opts = {}) {
	const now = opts.now ?? Date.now();
	const s = input.strategy || {};
	const perTradeSol = Number(s.per_trade_lamports || 0) / 1e9;
	const label = s.label || s.agent_name || s.agent_id || 'arm';

	const chart = vitals({ agent: String(label), timeoutMs: 8_000 });

	// ── Layer 0: the deployment itself ───────────────────────────────────────
	// First because it CAUSES the failures below it. An image that predates the
	// fix for a dead dependency will keep reproducing that dependency's failure
	// forever, and probing the dependency only rediscovers a known answer.
	chart.vital('deploy-fresh', {
		describe: 'the running worker image is recent enough to contain current config',
		remedy: SUBMIT_WORKER,
		probe: () => {
			const built = asTime(input.imageBuiltAt);
			if (built === null) return { ok: null, detail: 'image build time unread' };
			const age = now - built;
			return {
				ok: age <= STALE_IMAGE_MS,
				detail: `worker image is ${humanAge(age)} old`,
				data: { ageMs: age, builtAt: new Date(built).toISOString() },
			};
		},
	});

	// ── Layer 0: permission ──────────────────────────────────────────────────
	// Deliberately independent of the deployment: an owner who disarmed an arm
	// gets "off by choice", never a stack of infrastructure noise.
	chart.vital('armed', {
		describe: 'the owner has this arm enabled and not killed',
		remedy: 'enable the strategy (or clear its kill switch) from the agent page',
		probe: () => {
			if (s.kill_switch) return { ok: false, detail: 'kill switch engaged on the strategy' };
			if (!s.enabled) return { ok: false, detail: 'strategy is disabled' };
			return { ok: true };
		},
	});

	// ── Layer 0: money ───────────────────────────────────────────────────────
	// Asked of walletTradeState(), which calls the executor's own resolveEntrySize().
	// Re-deriving the threshold here is exactly how a report drifts into calling a
	// wallet tradeable that the executor sits out.
	chart.vital('solvency', {
		describe: 'the wallet can fund at least one entry at the executor\'s own sizing rule',
		remedy: ({ data }) => {
			const deficit = Number(data && typeof data === 'object' ? data.deficitSol : 0);
			const target = input.wallet || 'the arm wallet';
			return deficit > 0
				? `send ${deficit.toFixed(4)} SOL to ${target} (or let the auto-funder refill it)`
				: `fund ${target}`;
		},
		probe: () => {
			if (input.balanceSol == null || !Number.isFinite(Number(input.balanceSol))) {
				// An unread balance is not a balance of zero. Reporting it as down
				// would page an operator to a healthy fleet on one RPC blip.
				return { ok: null, detail: 'wallet balance unread' };
			}
			const balanceSol = Number(input.balanceSol);
			const state = walletTradeState(balanceSol, perTradeSol);
			const deficitSol = state === 'starved' ? Math.max(0, fundTargetSol({ perTradeSol }) - balanceSol) : 0;
			return {
				// 'shrunk' still trades, just below the configured size. Calling that
				// a failure would mark a working arm dead.
				ok: state !== 'starved',
				detail: `${balanceSol.toFixed(6)} SOL against a ${perTradeSol} SOL entry (${state})`,
				data: { state, balanceSol, perTradeSol, deficitSol },
			};
		},
	});

	// ── Layer 0: the outside world ───────────────────────────────────────────
	chart.vital('rpc', {
		describe: 'a Solana RPC is answering, so a quote and a broadcast are possible',
		remedy: 'check SOLANA_RPC_URL and the provider status; see docs/ops/solana-rpc-lanes.md',
		probe: () => input.rpc ?? { ok: null, detail: 'RPC not probed' },
	});

	chart.vital('feed', {
		describe: 'the launch feed is producing candidates to evaluate',
		remedy: 'check /api/cron/pumpfun-monitor and the upstream pump.fun feed',
		probe: () => {
			const fresh = asTime(input.feedFreshAt);
			if (fresh === null) return { ok: null, detail: 'feed freshness unread' };
			const age = now - fresh;
			return { ok: age <= STALE_FEED_MS, detail: `newest launch seen ${humanAge(age)} ago`, data: { ageMs: age } };
		},
	});

	// ── Layer 1: thinking, which a stale image can break ─────────────────────
	// The deploy-fresh edge exists ONLY for an arm that actually needs a model.
	// A stale image is a hypothesis about why a model chain died, not by itself a
	// reason an agent cannot act, and wiring it as a universal precondition said
	// so: it reported an arm that had entered a position two minutes earlier, on
	// that very image, as definitively unable. Live evidence beats a proxy every
	// time, so the proxy only applies where it can actually bite.
	const needsModel = s.decision_mode === 'llm';
	chart.vital('cognition', {
		describe: needsModel
			? 'the arm can reach a model and get a buy/skip decision'
			: 'this arm decides by rules and needs no model',
		needs: needsModel ? ['deploy-fresh'] : [],
		remedy: 'restore a working rung in api/_lib/llm.js: top up provider credits or clear the GCP billing hold',
		probe: () => {
			if (!needsModel) return { ok: true, detail: 'rules arm: no model required' };
			return input.cognition ?? { ok: null, detail: 'model chain not probed' };
		},
	});

	// ── Layer 2: the capabilities ────────────────────────────────────────────
	chart.capability('enter', {
		describe: 'open a new position if a qualifying launch appeared right now',
		needs: ['armed', 'solvency', 'rpc', 'feed', 'cognition'],
	});

	// Exiting deliberately needs neither the feed nor a model. A fleet that can
	// still close its open risk is not fully dead, and collapsing that distinction
	// is how an operator concludes the positions are stranded when they are not.
	chart.capability('exit', {
		describe: 'close an open position (needs no model and no launch feed)',
		needs: ['rpc'],
	});

	return chart;
}

/**
 * How recently an entry attempt still counts as proof the arm could act. Short
 * on purpose: it is evidence about the state of the world at that moment, and
 * the world moves.
 */
export const OBSERVED_ACTING_MS = 60 * 60 * 1000;

/**
 * Does the attestation contradict what the arm was observed doing?
 *
 * A capability model is a model, and models are wrong. This one was: an early
 * revision made every arm depend on deployment freshness, and confidently
 * reported an arm as unable to act while that arm was opening positions every
 * few minutes on the very image being complained about.
 *
 * A health tool that cannot notice it is wrong will be trusted right up until
 * it matters. So the ledger gets a vote: if the graph says `unable` and the arm
 * demonstrably acted inside the observation window, the graph is wrong and says
 * so, loudly, instead of quietly winning the argument against reality.
 *
 * @param {'ready'|'unable'|'unknown'|boolean|null} verdictStatus  can.enter, or a capability status
 * @param {Date|string|null|undefined} lastEntryAt
 * @param {{ now?: number }} [opts]
 * @returns {string|null} the contradiction, or null when the model and the ledger agree
 */
export function contradiction(verdictStatus, lastEntryAt, opts = {}) {
	const unable = verdictStatus === false || verdictStatus === 'unable';
	if (!unable) return null;
	const now = opts.now ?? Date.now();
	const last = asTime(lastEntryAt);
	if (last === null) return null;
	const ageMs = now - last;
	if (ageMs > OBSERVED_ACTING_MS) return null;
	return `attested UNABLE but this arm attempted an entry ${humanAge(ageMs)} ago: ` +
		'the vitals model is wrong, not the arm';
}

/**
 * Was this arm attempting entries recently? Kept beside the chart rather than
 * inside it because it is evidence, not a precondition: an arm can be perfectly
 * capable and simply have found nothing it liked. A stalled arm whose vitals are
 * all `up` is the interesting case, and it means the filters are the answer.
 *
 * @param {Date|string|null|undefined} lastEntryAt
 * @param {{ now?: number }} [opts]
 * @returns {{ stalled: boolean, ageMs: number|null, detail: string }}
 */
export function entryActivity(lastEntryAt, opts = {}) {
	const now = opts.now ?? Date.now();
	const last = asTime(lastEntryAt);
	if (last === null) return { stalled: true, ageMs: null, detail: 'never attempted an entry' };
	const ageMs = now - last;
	return {
		stalled: ageMs > STALE_ENTRY_MS,
		ageMs,
		detail: `last entry attempt ${humanAge(ageMs)} ago`,
	};
}