Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
sniper(risk-officer): add the adversarial pre-trade reviewer, shadow mode by default
nirholasc201ee080616
diff --git a/api/_lib/migrations/20260904020000_sniper_risk_officer.sql b/api/_lib/migrations/20260904020000_sniper_risk_officer.sqlnew file mode 100644index 000000000..3deee0ebc--- /dev/null+++ b/api/_lib/migrations/20260904020000_sniper_risk_officer.sql@@ -0,0 +1,86 @@+-- Migration: adversarial pre-trade Risk Officer for the agent-sniper fleet.+-- Apply: psql "$DATABASE_URL" -f api/_lib/migrations/20260904020000_sniper_risk_officer.sql+-- Additive and idempotent, safe to re-run.+--+-- The executor's existing gates (Mayhem exclusion, market-cap band, budget and+-- concurrency caps, spend policy, price-impact breaker, trade firewall) are all+-- mechanical. The Risk Officer (workers/agent-sniper/risk-officer.js) is the+-- independent second opinion that sits behind them: it is shown the trade the+-- agent wants to make plus the agent's own thesis, and is told to look for what+-- the agent missed.+--+-- This migration adds:+--+-- 1. agent_sniper_strategies.risk_officer_level — per-strategy enforcement.+-- 'shadow' (default): the review runs and is recorded, and changes nothing.+-- 'enforce': a 'block' severity aborts the buy; a smaller+-- size_adjustment shrinks it.+-- 'off': never called.+-- Shadow is the default ON PURPOSE. Enforcement decides what the live fleet+-- buys with real SOL, so arming it is an owner decision, not a deploy-time+-- default, and shadow rows are the evidence that decision needs.+--+-- 2. agent_sniper_strategies.risk_officer_model — optional per-strategy model+-- override. Left null, the officer uses SNIPER_RISK_OFFICER_MODEL, which+-- deliberately differs from the buy-side judge's model so the second+-- opinion is not an echo of the first.+--+-- 3. sniper_risk_reviews — append-only ledger of every review, enforced or+-- not. A shadow row records the veto that WOULD have been cast against a+-- position that actually opened, so the position's realized P&L later says+-- whether the officer was right.++begin;++-- ── per-strategy enforcement mode ────────────────────────────────────────────+alter table agent_sniper_strategies+ add column if not exists risk_officer_level text not null default 'shadow'+ check (risk_officer_level in ('off', 'shadow', 'enforce'));++alter table agent_sniper_strategies+ add column if not exists risk_officer_model text;++-- ── review ledger ────────────────────────────────────────────────────────────+create table if not exists sniper_risk_reviews (+ id bigint generated always as identity primary key,+ created_at timestamptz not null default now(),+ agent_id uuid not null,+ strategy_id uuid,+ -- the position row the review is attached to; null when the buy never+ -- claimed a slot.+ position_id uuid,+ network text not null default 'mainnet' check (network in ('mainnet', 'devnet')),+ mint text not null,+ symbol text,+ -- the level in force when the review ran ('shadow' rows are counterfactual)+ level text not null check (level in ('shadow', 'enforce')),+ veto boolean not null default false,+ severity text not null check (severity in ('none', 'caution', 'block')),+ reasons text[] not null default '{}',+ proposed_lamports numeric(40, 0) not null,+ -- set when the officer asked for a smaller size (shadow: what it would have been)+ adjusted_lamports numeric(40, 0),+ -- true only when the review actually changed the trade (never true in shadow)+ enforced boolean not null default false,+ model text,+ answered_by text,+ latency_ms integer,+ -- the reviewer was unavailable / unparseable and the trade proceeded unreviewed+ degraded boolean not null default false,+ agent_reason text+);++-- An agent's own review history (owner-facing audit + the arm-it decision).+create index if not exists sniper_risk_reviews_agent+ on sniper_risk_reviews (agent_id, created_at desc);++-- Did the officer's call match what the position actually did?+create index if not exists sniper_risk_reviews_position+ on sniper_risk_reviews (position_id)+ where position_id is not null;++-- Veto-rate analytics across the fleet.+create index if not exists sniper_risk_reviews_severity+ on sniper_risk_reviews (network, severity, created_at desc);++commit;diff --git a/workers/agent-sniper/risk-officer.js b/workers/agent-sniper/risk-officer.jsnew file mode 100644index 000000000..1812aa941--- /dev/null+++ b/workers/agent-sniper/risk-officer.js@@ -0,0 +1,416 @@+// agent-sniper — adversarial pre-trade Risk Officer.+//+// The executor already enforces a stack of MECHANICAL gates before any buy is+// broadcast: Mayhem exclusion, the market-cap band, throttle/concurrency/budget+// caps, the shared spend policy, wallet headroom, the price-impact breaker and+// the trade firewall's real on-chain buy→sell round-trip. Every one of those+// answers a question with a number. None of them asks the question a human risk+// desk asks last: "knowing everything we know, is this specific trade still a+// good idea?"+//+// This module is that second opinion, and it is deliberately ADVERSARIAL. It is+// not the buy-side judge (llm-judge.js) run twice: the judge is looking for a+// reason to buy, the officer is looking for the reason the judge missed. It sees+// the judge's own thesis and is told to assume the trade is bad until the facts+// prove otherwise. That asymmetry is the whole value; running the same optimistic+// prompt a second time would only launder the first answer.+//+// ENFORCEMENT IS OFF BY DEFAULT, ON PURPOSE. The officer decides what the live+// fleet buys with real SOL, so arming it is an owner call, not a deploy-time+// default. Three levels, per strategy (`agent_sniper_strategies.risk_officer_level`)+// with an env default (`SNIPER_RISK_OFFICER`):+//+// 'shadow' (default) — the review runs and is recorded, and NOTHING changes.+// Fire-and-forget, so it adds zero latency to the buy+// path. This is how the owner gets the evidence to arm+// it: `sniper_risk_reviews` accumulates the vetoes it+// WOULD have cast against the positions that actually+// opened, and their realized P&L answers whether the+// officer was right.+// 'enforce' — awaited before the broadcast. A 'block' severity kills+// the buy; a smaller `size_adjustment` shrinks it. Never+// upsizes: an adversarial reviewer may only reduce risk.+// 'off' — never called.+//+// FAIL OPEN, unlike the firewall. The firewall proves a coin is not a honeypot,+// so an unavailable firewall must block ('couldn't prove it's safe' is not+// 'safe'). The officer is a judgment layer sitting BEHIND that proof: if the+// model is down, timed out, or answered with garbage, every mechanical gate has+// already passed and the trade proceeds unchanged. A reviewer outage must never+// become a fleet-wide halt.++import { log } from './log.js';+import { sql } from '../../api/_lib/db.js';+import { llmComplete } from '../../api/_lib/llm.js';++const OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';++export const RISK_OFFICER_LEVELS = ['off', 'shadow', 'enforce'];++const LAMPORTS_PER_SOL = 1_000_000_000n;++// Short by design: this sits between a quote and a broadcast on a coin that is+// seconds old. An officer that answers late has already answered wrong.+const TIMEOUT_MS = Math.max(1_500, Number(process.env.SNIPER_RISK_OFFICER_TIMEOUT_MS || 6_000));+const MAX_CONCURRENT = Math.max(1, Number(process.env.SNIPER_RISK_OFFICER_MAX_CONCURRENT || 3));++// Independence is the point, so the officer's default model is NOT the judge's+// (`strat.llm_model`). 'openrouter/auto' on both would frequently route to the+// same weights and turn a second opinion into an echo.+const DEFAULT_MODEL = (process.env.SNIPER_RISK_OFFICER_MODEL || 'anthropic/claude-sonnet-4.5').trim();++let _active = 0;++const SYSTEM_PROMPT = [+ 'You are an independent risk reviewer for an autonomous pump.fun trader on Solana.',+ 'The trading agent wants to BUY. Your ONLY job is to catch what it missed.',+ 'Assume the trade is bad until the facts prove otherwise.',+ '',+ 'Veto (severity "block") ONLY for concrete, nameable danger: a creator with a rug',+ 'history, extreme holder concentration, price impact that eats the edge, a failed',+ 'or warned safety check, or a breach of the mandate. Default to NOT vetoing on a',+ 'thin-but-clean setup — the agent already skipped the obvious junk, and a reviewer',+ 'that blocks everything is the same as no reviewer at all.',+ '',+ 'Prefer a smaller size over a full veto when the concern is size-shaped rather',+ 'than existential: set "size_adjustment" to a SMALLER SOL amount than proposed.',+ 'You may never suggest a LARGER size.',+ '',+ 'Never write generic risk boilerplate ("crypto is volatile", "memecoins are risky").',+ 'Every reason must cite a specific fact you were given. If you have no such fact,',+ 'you have no veto.',+ '',+ 'Respond with ONLY a JSON object, no prose, no code fences:',+ '{"veto": true|false, "severity": "none"|"caution"|"block",',+ ' "reasons": ["specific, fact-based"], "size_adjustment": <SOL number>|null}',+].join('\n');++function n(v) {+ const x = Number(v);+ return Number.isFinite(x) ? x : null;+}++function lamportsToSol(l) {+ return Number(BigInt(l)) / 1e9;+}++/**+ * Which enforcement level applies to one strategy. A valid per-strategy column+ * wins; otherwise the env default; otherwise 'shadow'. An unrecognised value+ * (hand-edited row, stale deploy) degrades to 'shadow' rather than silently+ * enforcing something nobody armed.+ */+export function resolveRiskOfficerLevel(strat, envDefault = process.env.SNIPER_RISK_OFFICER) {+ const perStrategy = String(strat?.risk_officer_level || '').trim().toLowerCase();+ if (RISK_OFFICER_LEVELS.includes(perStrategy)) return perStrategy;+ const env = String(envDefault || '').trim().toLowerCase();+ if (RISK_OFFICER_LEVELS.includes(env)) return env;+ return 'shadow';+}++/**+ * Parse the model's answer into a normalized review, or null when it is not+ * usable. Null always fails open — an unparseable review never blocks a trade.+ *+ * Tolerates the two things models actually do wrong here: wrapping the JSON in+ * a ```json fence, and emitting `veto: true` with `severity: "caution"` (or the+ * reverse). Severity is the authority on enforcement; `veto` is normalized to+ * agree with it so a downstream reader can trust either field.+ */+export function parseReview(text) {+ if (!text) return null;+ const raw = String(text).trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');+ const start = raw.indexOf('{');+ const end = raw.lastIndexOf('}');+ if (start < 0 || end <= start) return null;+ let obj;+ try {+ obj = JSON.parse(raw.slice(start, end + 1));+ } catch {+ return null;+ }+ if (!obj || typeof obj !== 'object') return null;++ let severity = String(obj.severity || '').trim().toLowerCase();+ if (!['none', 'caution', 'block'].includes(severity)) {+ // No usable severity: infer it from the veto flag rather than discarding a+ // review that named real reasons.+ severity = obj.veto === true ? 'block' : 'none';+ }+ const reasons = (Array.isArray(obj.reasons) ? obj.reasons : [])+ .map((r) => String(r || '').trim())+ .filter(Boolean)+ .slice(0, 6)+ .map((r) => r.slice(0, 240));++ // A 'block' with nothing to point at is boilerplate, not a finding. Downgrade+ // it: the prompt is explicit that a veto must cite a fact.+ if (severity === 'block' && !reasons.length) severity = 'caution';++ const sizeSol = n(obj.size_adjustment);+ return {+ veto: severity === 'block',+ severity,+ reasons,+ sizeAdjustmentSol: sizeSol != null && sizeSol > 0 ? sizeSol : null,+ };+}++/**+ * Turn a review into the trade's actual outcome. PURE — the executor calls this+ * and acts on the result, and the tests call it with no network or DB.+ *+ * Contract:+ * • Only 'enforce' can change anything. 'shadow'/'off' are always a no-op.+ * • A missing/degraded review is always a no-op (fail open).+ * • 'block' aborts. 'caution' never aborts on its own.+ * • A size adjustment may only SHRINK the trade, and never below the network's+ * minimum tradeable size — a suggestion under that floor clamps up to the+ * floor rather than aborting, because the officer asked for less risk, not+ * for no trade.+ */+export function applyReview({ review, level, perTradeLamports, minTradeLamports }) {+ const size = BigInt(perTradeLamports);+ const unchanged = { blocked: false, reason: null, sizeLamports: size, resized: false };+ if (level !== 'enforce') return unchanged;+ if (!review || review.degraded) return unchanged;++ if (review.severity === 'block') {+ return {+ blocked: true,+ reason: review.reasons[0] || 'risk_officer_veto',+ sizeLamports: size,+ resized: false,+ };+ }++ if (review.sizeAdjustmentSol == null) return unchanged;+ const suggested = BigInt(Math.floor(review.sizeAdjustmentSol * 1e9));+ if (suggested >= size) return unchanged; // never upsize+ const floor = BigInt(minTradeLamports ?? 0);+ const next = suggested < floor ? floor : suggested;+ if (next >= size) return unchanged; // the floor already equals the proposed size+ return { blocked: false, reason: null, sizeLamports: next, resized: true };+}++/**+ * The brief. Only facts the caller actually has — an omitted field is omitted,+ * never guessed, because a fabricated holder count is exactly the kind of thing+ * an adversarial reviewer would (correctly) veto on.+ */+export function reviewBrief({ mint, sizeSol, budgetLeftSol, slotsLeft, priceImpactPct, firewall, agentReason }) {+ const facts = {+ symbol: mint.symbol || null,+ name: mint.name || null,+ mint: mint.mint,+ market_cap_usd: mint.market_cap_usd != null ? Math.round(Number(mint.market_cap_usd)) : null,+ entry_trigger: mint.entry_trigger || 'new_mint',+ creator_prior_launches: mint.creator_launches ?? null,+ creator_graduated_coins: mint.creator_graduated ?? null,+ dev_initial_buy_sol: mint.initial_buy_sol != null ? Number(mint.initial_buy_sol) : null,+ twitter: mint.twitter || null,+ telegram: mint.telegram || null,+ website: mint.website || null,+ price_impact_pct: priceImpactPct != null ? Number(Number(priceImpactPct).toFixed(3)) : null,+ safety_firewall_verdict: firewall?.verdict || null,+ safety_firewall_score: firewall?.score ?? null,+ };+ const lines = Object.entries(facts)+ .filter(([, v]) => v != null && v !== '')+ .map(([k, v]) => `${k}: ${v}`);++ return [+ `PROPOSED: BUY ${Number(sizeSol).toFixed(4)} SOL of ${mint.symbol || mint.mint.slice(0, 6)}.`,+ agentReason ? `AGENT'S REASON: "${String(agentReason).slice(0, 400)}"` : 'AGENT\'S REASON: (rule-based entry, no stated thesis)',+ '',+ 'FACTS (on-chain / feed data — do not invent any others):',+ ...lines.map((l) => `- ${l}`),+ '',+ 'MANDATE REMAINING:',+ `- daily budget left: ${Number(budgetLeftSol).toFixed(4)} SOL`,+ `- open position slots left: ${slotsLeft}`,+ ].join('\n');+}++async function askOpenRouter({ model, user }) {+ const key = process.env.OPENROUTER_API_KEY;+ if (!key) throw new Error('OPENROUTER_API_KEY not configured');+ const ac = new AbortController();+ const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);+ try {+ const resp = await fetch(OPENROUTER_URL, {+ method: 'POST',+ signal: ac.signal,+ headers: {+ authorization: `Bearer ${key}`,+ 'content-type': 'application/json',+ 'x-title': 'three.ws agent-sniper risk officer',+ },+ body: JSON.stringify({+ model,+ max_tokens: 300,+ temperature: 0,+ messages: [+ { role: 'system', content: SYSTEM_PROMPT },+ { role: 'user', content: user },+ ],+ }),+ });+ if (!resp.ok) {+ const body = await resp.text().catch(() => '');+ throw new Error(`openrouter ${resp.status}: ${body.slice(0, 160)}`);+ }+ const body = await resp.json();+ return body?.choices?.[0]?.message?.content || '';+ } finally {+ clearTimeout(timer);+ }+}++// One review per proposed trade. OpenRouter is the primary route (it is where+// the fleet's model choice lives); the platform's free-first chain is the+// backstop so an OpenRouter outage degrades to a different reviewer rather than+// to no reviewer, honestly labeled with who actually answered.+async function ask(user, model) {+ const t0 = Date.now();+ try {+ const text = await askOpenRouter({ model, user });+ const review = parseReview(text);+ if (review) return { ...review, model, answeredBy: model, latencyMs: Date.now() - t0, degraded: false };+ throw new Error('unparseable review');+ } catch (err) {+ log.warn('risk officer openrouter failed, free-chain fallback', { model, err: err?.message });+ const res = await llmComplete({ system: SYSTEM_PROMPT, user, maxTokens: 300, timeoutMs: TIMEOUT_MS });+ const review = parseReview(res?.text ?? res);+ if (!review) return null;+ return {+ ...review,+ model,+ answeredBy: res?.model || res?.provider || 'free-chain',+ latencyMs: Date.now() - t0,+ degraded: false,+ };+ }+}++// Append-only review ledger. Fire-and-forget in every mode: the review's value+// is the evidence it accumulates, and a ledger hiccup must never cost a trade.+function recordReview(row) {+ sql`+ insert into sniper_risk_reviews+ (agent_id, strategy_id, position_id, network, mint, symbol, level, veto, severity,+ reasons, proposed_lamports, adjusted_lamports, enforced, model, answered_by,+ latency_ms, degraded, agent_reason)+ values+ (${row.agentId}, ${row.strategyId}, ${row.positionId ?? null}, ${row.network}, ${row.mint},+ ${row.symbol || null}, ${row.level}, ${row.veto}, ${row.severity},+ ${row.reasons || []}, ${row.proposedLamports}, ${row.adjustedLamports ?? null},+ ${row.enforced}, ${row.model || null}, ${row.answeredBy || null},+ ${row.latencyMs ?? null}, ${row.degraded}, ${row.agentReason || null})+ `.catch((err) => log.warn('risk review record failed', { mint: row.mint, err: err?.message }));+}++/**+ * Review one proposed buy.+ *+ * Returns `{ blocked, reason, sizeLamports, resized, review }`. In 'shadow' and+ * 'off' the returned decision is ALWAYS the caller's own proposal unchanged;+ * shadow additionally kicks the review off in the background so the ledger fills+ * without the buy path ever waiting on it.+ */+export async function reviewBuy({ cfg, strat, mint, posId, perTradeLamports, minTradeLamports, budgetLeftLamports, slotsLeft, priceImpactPct, firewall, agentReason }) {+ const size = BigInt(perTradeLamports);+ const passthrough = { blocked: false, reason: null, sizeLamports: size, resized: false, review: null };++ const level = resolveRiskOfficerLevel(strat, cfg?.riskOfficer);+ if (level === 'off') return passthrough;++ if (_active >= MAX_CONCURRENT) {+ // Saturated. Fail open: every mechanical gate has already passed.+ log.info('risk officer saturated, proceeding unreviewed', { agent: strat.agent_id, mint: mint.mint, active: _active });+ return passthrough;+ }++ const model = strat.risk_officer_model || DEFAULT_MODEL;+ const user = reviewBrief({+ mint,+ sizeSol: lamportsToSol(size),+ budgetLeftSol: lamportsToSol(budgetLeftLamports ?? 0n),+ slotsLeft,+ priceImpactPct,+ firewall,+ agentReason,+ });++ const base = {+ agentId: strat.agent_id,+ strategyId: strat.id,+ positionId: posId ?? null,+ network: cfg.network,+ mint: mint.mint,+ symbol: mint.symbol || null,+ level,+ proposedLamports: size.toString(),+ agentReason: agentReason || null,+ };++ _active++;+ const pending = ask(user, model)+ .catch((err) => {+ log.warn('risk officer unavailable, proceeding unreviewed', { agent: strat.agent_id, mint: mint.mint, err: err?.message });+ return null;+ })+ .finally(() => { _active--; });++ // Shadow: never awaited, so the live fleet pays no latency for evidence+ // collection. The verdict lands in the ledger next to the position that DID+ // open, which is exactly the comparison the owner needs to arm 'enforce'.+ if (level !== 'enforce') {+ pending.then((review) => {+ if (!review) {+ recordReview({ ...base, veto: false, severity: 'none', reasons: [], enforced: false, degraded: true });+ return;+ }+ const would = applyReview({ review, level: 'enforce', perTradeLamports: size, minTradeLamports });+ recordReview({+ ...base,+ veto: review.veto,+ severity: review.severity,+ reasons: review.reasons,+ adjustedLamports: would.resized ? would.sizeLamports.toString() : null,+ enforced: false,+ model: review.model,+ answeredBy: review.answeredBy,+ latencyMs: review.latencyMs,+ degraded: false,+ });+ if (would.blocked || would.resized) {+ log.info('risk officer (shadow) would have acted', {+ agent: strat.agent_id, mint: mint.mint, severity: review.severity,+ wouldBlock: would.blocked, reasons: review.reasons,+ });+ }+ });+ return passthrough;+ }++ const review = await pending;+ if (!review) {+ recordReview({ ...base, veto: false, severity: 'none', reasons: [], enforced: false, degraded: true });+ return passthrough;+ }+ const decision = applyReview({ review, level, perTradeLamports: size, minTradeLamports });+ recordReview({+ ...base,+ veto: review.veto,+ severity: review.severity,+ reasons: review.reasons,+ adjustedLamports: decision.resized ? decision.sizeLamports.toString() : null,+ enforced: decision.blocked || decision.resized,+ model: review.model,+ answeredBy: review.answeredBy,+ latencyMs: review.latencyMs,+ degraded: false,+ });+ return { ...decision, review };+}