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
// Memory-grounded Autopilot — explainable autonomy (Living Agents · Task 08).
//
// The agent acts on the user's behalf, grounded in its memory, and always shows
// the receipt. This module is the engine:
//
// 1. generateProposals() — the "mind" turns high-salience memories + pending
// reflections ("dreams") into concrete, REAL action proposals, each citing
// the memory/reflection ids that motivated it (provenance is mandatory).
// 2. The owner grants scoped capabilities (meta.autopilot) and reviews the
// queue: dry-run, approve, dismiss, adjust.
// 3. executeProposal() — within scope, takes the real action: creates a real
// pump_alert_rules row, authors a real briefing notification, or transfers
// real $THREE through the custodial wallet path. Every execution writes a
// signed agent_actions row carrying its provenance and is linked back.
// 4. computeTrust() derives a real trust level from the action history.
// 5. undoProposal() reverses reversible actions and writes a feedback memory so
// the agent learns the owner's boundaries (closing the loop with reflection).
//
// No mocks. Alert rules are real, briefings are real notifications, SOL
// transfers are real on-chain System-program transfers gated by real
// confirmation + scope. Autopilot spends SOL — never $THREE: the agent only ever
// accumulates and burns $THREE, never sells or sends it. The only coin named for
// alerts is $THREE.
import { sql } from './db.js';
import { llmComplete, llmConfigured, LlmUnavailableError } from './llm.js';
import { THREE_CA } from './three-gate.js';
import { recordCustodyEvent } from './agent-trade-guards.js';
// pump.fun mints (including $THREE) are 6-decimal SPL tokens.
export const THREE_DECIMALS = 6;
// Native SOL has 9 decimals (lamports). Autopilot's spend cap and wallet_transfer
// are denominated in SOL — the currency the agent actually spends on gas and fees
// (and, via the trading capability, buying coins). $THREE is never spent here.
const LAMPORTS_PER_SOL = 1_000_000_000;
const MAX_DAILY_SOL = 1000; // sane ceiling on the daily autonomous SOL spend cap
export const AUTOPILOT_ACTION_KINDS = ['create_alert', 'briefing', 'wallet_transfer'];
// The actions /api/autopilot/proposals accepts on a POST. Kept beside the engine
// so the handler's allowlist and its error message can never drift apart.
export const AUTOPILOT_PROPOSAL_ACTIONS = Object.freeze([
'generate', 'dryrun', 'execute', 'dismiss', 'undo', 'adjust',
]);
// ── Request-input guards for the autopilot read surfaces ─────────────────────
// Every autopilot endpoint takes the same two user-supplied paging inputs. Both
// reach Postgres directly, which rejects a negative LIMIT and an out-of-range
// bigint cursor with an error that would surface to the caller as a 500. Clamp
// and validate them here, at the boundary, so bad input reads as bad input.
const MAX_BIGINT = 9223372036854775807n;
export function pageLimit(raw, { fallback = 50, max = 200 } = {}) {
const n = Math.trunc(Number(raw));
if (!Number.isFinite(n) || n <= 0) return fallback;
return Math.min(n, max);
}
// agent_actions.id is a bigserial, so the cursor is an opaque decimal string.
export function parseCursor(raw) {
if (raw == null || raw === '') return { ok: true, cursor: null };
if (typeof raw !== 'string' || !/^\d{1,19}$/.test(raw)) return { ok: false, reason: 'cursor must be numeric' };
if (BigInt(raw) > MAX_BIGINT) return { ok: false, reason: 'cursor out of range' };
return { ok: true, cursor: raw };
}
// Action types written to the signed agent_actions log, one per executable kind.
const ACTION_TYPE = {
create_alert: 'autopilot.alert.created',
briefing: 'autopilot.briefing.authored',
wallet_transfer: 'autopilot.wallet.transfer',
};
// ── Scope / permission model (stored on agent_identities.meta.autopilot) ──────
export const AUTOPILOT_DEFAULTS = Object.freeze({
enabled: false,
// Which capabilities the owner has granted. Nothing is granted by default —
// the agent can propose but not act until the owner opts in per capability.
scopes: Object.freeze({ create_alert: false, briefing: false, wallet_transfer: false }),
// Reversible actions may auto-execute within scope when the owner allows it;
// wallet_transfer is irreversible and can never auto-execute here.
auto_execute: Object.freeze({ create_alert: false, briefing: false }),
// Daily ceiling on autonomous SOL outflow (in SOL). 0 ⇒ no spending. The agent
// spends SOL, never $THREE — $THREE is buy-and-hold/burn only.
daily_spend_sol: 0,
// Irreversible actions require an explicit confirmation unless the owner
// durably pre-authorized that exact scope. Default: always ask.
require_confirm: true,
});
export function normalizeAutopilotConfig(raw) {
const r = raw && typeof raw === 'object' ? raw : {};
const scopesIn = r.scopes && typeof r.scopes === 'object' ? r.scopes : {};
const autoIn = r.auto_execute && typeof r.auto_execute === 'object' ? r.auto_execute : {};
// Read the SOL cap. A legacy daily_spend_three (denominated in $THREE) is
// intentionally NOT migrated — the units differ — so autopilot fails closed
// until the owner sets a SOL cap. SOL is fractional; we don't round to whole.
const spend = Number(r.daily_spend_sol);
return {
enabled: r.enabled === true,
scopes: {
create_alert: scopesIn.create_alert === true,
briefing: scopesIn.briefing === true,
wallet_transfer: scopesIn.wallet_transfer === true,
},
auto_execute: {
create_alert: autoIn.create_alert === true,
briefing: autoIn.briefing === true,
},
daily_spend_sol: Number.isFinite(spend) && spend > 0 ? Math.min(spend, MAX_DAILY_SOL) : 0,
require_confirm: r.require_confirm !== false,
updated_at: typeof r.updated_at === 'string' ? r.updated_at : null,
};
}
export function getAutopilotConfig(meta) {
return normalizeAutopilotConfig(meta?.autopilot);
}
/** Persist a scope-config patch onto meta.autopilot. Owner-scoped; caller checks ownership. */
export async function setAutopilotConfig(agentId, patch) {
const [row] = await sql`SELECT meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;
if (!row) throw new Error('agent not found');
const current = getAutopilotConfig(row.meta);
const next = normalizeAutopilotConfig({
enabled: 'enabled' in patch ? patch.enabled : current.enabled,
scopes: { ...current.scopes, ...(patch.scopes || {}) },
auto_execute: { ...current.auto_execute, ...(patch.auto_execute || {}) },
daily_spend_sol: 'daily_spend_sol' in patch ? patch.daily_spend_sol : current.daily_spend_sol,
require_confirm: 'require_confirm' in patch ? patch.require_confirm : current.require_confirm,
});
next.updated_at = new Date().toISOString();
const nextMeta = { ...(row.meta || {}), autopilot: next };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(nextMeta)}::jsonb, updated_at = now() WHERE id = ${agentId}`;
return next;
}
// ── Proposal validation (per kind) ────────────────────────────────────────────
const SOLANA_ADDR_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const ALERT_CONDITIONS = ['price_above', 'price_below', 'graduation', 'whale_buy'];
// Map a high-level proposal into concrete, validated params + a pump_alert_rules
// body. Returns { ok, params, rule } or { ok:false, reason }. Never throws.
function buildAlertRule(params) {
const condition = ALERT_CONDITIONS.includes(params?.condition) ? params.condition : null;
if (!condition) return { ok: false, reason: 'unknown alert condition' };
// Resolve the asset to a real mint. 'three' (or the bare CA) → $THREE; an
// explicit mint must be a valid Solana address.
let mint = null;
const asset = String(params?.asset ?? params?.target_mint ?? 'three').trim();
if (asset.toLowerCase() === 'three' || asset === THREE_CA) mint = THREE_CA;
else if (SOLANA_ADDR_RE.test(asset)) mint = asset;
else return { ok: false, reason: 'alert asset must be $THREE or a valid mint' };
const rule = {
kind: condition,
target_mint: mint,
target_agent: null,
threshold: null,
deliver_in_app: true,
webhook_url: null,
telegram_chat: null,
cooldown_seconds: 300,
enabled: true,
label: typeof params?.label === 'string' ? params.label.slice(0, 80) : null,
};
if (condition === 'price_above' || condition === 'price_below') {
const t = Number(params?.threshold_usd ?? params?.threshold);
if (!Number.isFinite(t) || t <= 0) return { ok: false, reason: `${condition} needs a positive USD threshold` };
rule.threshold = t;
} else if (condition === 'whale_buy') {
const t = Number(params?.threshold_sol ?? params?.threshold);
if (!Number.isFinite(t) || t <= 0) return { ok: false, reason: 'whale_buy needs a positive SOL threshold' };
rule.threshold = t;
}
return { ok: true, params: { ...params, asset: mint === THREE_CA ? 'three' : mint, condition }, rule };
}
function validateBriefing(params) {
const summary = typeof params?.summary === 'string' ? params.summary.trim().slice(0, 300) : '';
if (!summary) return { ok: false, reason: 'briefing needs a summary' };
const cadence = ['once', 'daily', 'weekly'].includes(params?.cadence) ? params.cadence : 'once';
const topic = typeof params?.topic === 'string' ? params.topic.trim().slice(0, 200) : summary;
return { ok: true, params: { summary, cadence, topic } };
}
function validateWalletTransfer(params) {
const recipient = typeof params?.recipient === 'string' ? params.recipient.trim() : '';
if (!SOLANA_ADDR_RE.test(recipient)) return { ok: false, reason: 'recipient must be a valid Solana address' };
// Buy-only $THREE: autopilot sends NATIVE SOL only. Any attempt to route this
// through a token mint — $THREE above all — is refused. The agent never sells
// or sends $THREE; it only accumulates and burns it.
const token = String(params?.mint ?? params?.asset ?? params?.token ?? '').trim().toLowerCase();
if (token && token !== 'sol' && token !== 'native') {
return { ok: false, reason: 'wallet_transfer sends native SOL only — it will never sell or send $THREE or any SPL token' };
}
const amount = Number(params?.amount_sol);
if (!Number.isFinite(amount) || amount <= 0) return { ok: false, reason: 'amount_sol must be > 0' };
const reason = typeof params?.reason === 'string' ? params.reason.trim().slice(0, 200) : '';
return { ok: true, params: { recipient, amount_sol: amount, reason } };
}
/** Validate + normalize a proposal of a given kind. Returns { ok, kind, params, rule? } | { ok:false, reason }. */
export function validateProposal(kind, params) {
if (!AUTOPILOT_ACTION_KINDS.includes(kind)) return { ok: false, reason: `unknown action kind '${kind}'` };
if (kind === 'create_alert') {
const r = buildAlertRule(params);
return r.ok ? { ok: true, kind, params: r.params, rule: r.rule } : r;
}
if (kind === 'briefing') {
const r = validateBriefing(params);
return r.ok ? { ok: true, kind, params: r.params } : r;
}
const r = validateWalletTransfer(params);
return r.ok ? { ok: true, kind, params: r.params } : r;
}
// A canonical key so the generator never enqueues a duplicate of a live proposal.
export function proposalDedupeKey(kind, params) {
if (kind === 'create_alert') return `create_alert:${params.condition}:${params.asset}:${params.threshold_usd ?? params.threshold_sol ?? params.threshold ?? ''}`;
if (kind === 'briefing') return `briefing:${params.cadence}:${(params.topic || params.summary || '').toLowerCase().slice(0, 60)}`;
return `wallet_transfer:${params.recipient}:${params.amount_sol}`;
}
// ── Proposal generation (the "mind") ──────────────────────────────────────────
const PROPOSAL_SYSTEM = [
'You are the autonomous-action planner of a personal AI agent. You read the',
'agent\'s high-salience MEMORIES and propose concrete actions the agent could',
'take on the user\'s behalf — each justified by the memories it cites.',
'',
'Allowed action kinds (use ONLY these):',
' • "create_alert" — watch a token and notify on an event. params:',
' { asset: "three" | "<mint>", condition: "price_above"|"price_below"|"graduation"|"whale_buy",',
' threshold_usd?: number (for price_*), threshold_sol?: number (for whale_buy) }',
' • "briefing" — a memory-grounded digest. params:',
' { summary: string, cadence: "once"|"daily"|"weekly", topic: string }',
' • "wallet_transfer" — send native SOL from the agent\'s own wallet. params:',
' { recipient: "<solana address>", amount_sol: number, reason: string }',
'',
'RULES:',
'1. PROVENANCE IS MANDATORY. Every proposal must cite "source_memory_ids" using',
' ONLY ids that appear in the provided memories. A proposal you cannot ground',
' in specific memories is invalid — do not emit it.',
'2. Propose ONLY what the memories justify. Prefer 1-3 high-value proposals over',
' a long list. If nothing is warranted, return {"proposals":[]}.',
'3. For alerts the ONLY coin you name is $THREE (asset:"three"); an explicit mint',
' is allowed only when a memory supplies one. NEVER sell or send $THREE.',
'4. wallet_transfer spends real SOL (never $THREE) — propose only when a memory',
' explicitly asks the agent to pay/tip/fund a recipient, with amount_sol.',
'5. "rationale" is the receipt the user reads: one sentence, plain language,',
' explaining WHY (referencing what the memories show).',
'',
'Return ONLY a JSON object, no prose, no fences:',
'{"proposals":[{"kind":"...","title":"...","rationale":"...","confidence":0.0,"source_memory_ids":["uuid"],"params":{...}}]}',
].join('\n');
function truncate(s, n) {
const str = String(s ?? '');
return str.length > n ? str.slice(0, n - 1) + '…' : str;
}
function buildProposalPrompt({ agent, memories }) {
const lines = [];
lines.push(`AGENT: ${agent?.name || 'Agent'}${agent?.description ? ` — ${agent.description}` : ''}`);
lines.push(`$THREE mint: ${THREE_CA}`);
lines.push('');
lines.push('HIGH-SALIENCE MEMORIES:');
for (const m of memories) {
const tags = Array.isArray(m.tags) && m.tags.length ? ` [${m.tags.join(', ')}]` : '';
lines.push(`- id=${m.id} (${m.type}, salience ${Number(m.salience).toFixed(2)})${tags}: ${truncate(m.content, 400)}`);
}
lines.push('');
lines.push('Propose the actions these memories justify, as the specified JSON.');
return lines.join('\n');
}
function parseProposalPayload(text) {
if (!text) return null;
let body = String(text).trim();
const fence = body.match(/```(?:json)?\s*([\s\S]*?)```/i);
if (fence) body = fence[1].trim();
if (body[0] !== '{') {
const start = body.indexOf('{');
const end = body.lastIndexOf('}');
if (start === -1 || end === -1 || end <= start) return null;
body = body.slice(start, end + 1);
}
try {
return JSON.parse(body);
} catch {
return null;
}
}
// Deterministic fallback when no LLM provider is configured (the platform must
// degrade, never fake). Mines memories for two well-grounded patterns:
// • interest in a $THREE price/market-cap level → a price alert
// • a stated routine ("every morning", "daily digest") → a daily briefing
// Each proposal cites the exact memory it came from. Pure + synchronous.
export function heuristicProposals(memories) {
const out = [];
for (const m of memories) {
const text = String(m.content || '').toLowerCase();
const mentionsThree = /\bthree\b|\$three/.test(text);
const priceMatch = text.match(/\$?\s?([\d,]+(?:\.\d+)?)\s?(k|m)?\b/);
if (mentionsThree && /(market\s?cap|price|hits?|reaches?|above|target|alert)/.test(text) && priceMatch) {
let n = parseFloat(priceMatch[1].replace(/,/g, ''));
if (priceMatch[2] === 'k') n *= 1_000;
if (priceMatch[2] === 'm') n *= 1_000_000;
if (Number.isFinite(n) && n > 0) {
out.push({
kind: 'create_alert',
title: `Alert when $THREE market cap crosses $${n.toLocaleString()}`,
rationale: `You noted interest in $THREE around $${n.toLocaleString()}. I'll watch it and ping you when it crosses.`,
confidence: 0.55,
source_memory_ids: [m.id],
params: { asset: 'three', condition: 'price_above', threshold_usd: n },
});
}
}
if (/(every morning|each morning|daily|each day|every day|digest|briefing|catch me up)/.test(text)) {
out.push({
kind: 'briefing',
title: 'Daily $THREE briefing',
rationale: `You mentioned wanting a regular catch-up. I'll author a short daily briefing grounded in what I know.`,
confidence: 0.5,
source_memory_ids: [m.id],
params: { summary: 'Daily $THREE briefing', cadence: 'daily', topic: truncate(m.content, 120) },
});
}
}
return out;
}
// Map a reflection's proposed_action (Task 04) into one of our action kinds.
function reflectionToProposal(dream) {
const pa = dream.proposed_action;
if (!pa || typeof pa !== 'object') return null;
const rawKind = String(pa.kind || '').toLowerCase();
let kind = null;
let params = {};
if (rawKind.includes('alert') || pa.condition) {
kind = 'create_alert';
params = {
asset: pa.asset || 'three',
condition: ALERT_CONDITIONS.includes(pa.condition) ? pa.condition : 'price_above',
threshold_usd: pa.threshold_usd ?? pa.threshold,
threshold_sol: pa.threshold_sol,
};
} else if (rawKind.includes('brief') || rawKind.includes('digest') || pa.summary || pa.trigger) {
kind = 'briefing';
params = {
summary: pa.summary || dream.statement,
cadence: /week/i.test(pa.trigger || '') ? 'weekly' : /day|morning/i.test(pa.trigger || pa.cadence || '') ? 'daily' : 'once',
topic: dream.statement,
};
} else {
return null; // unknown automation shape — don't guess into a spend
}
const v = validateProposal(kind, params);
if (!v.ok) return null;
return {
kind,
title: dream.statement.slice(0, 120),
rationale: dream.rationale || `Your agent reflected: "${truncate(dream.statement, 160)}"`,
confidence: dream.confidence ?? 0.6,
source_memory_ids: dream.source_memory_ids || [],
source_reflection_id: dream.id,
params: v.params,
};
}
const MAX_PROPOSALS_PER_RUN = 6;
const MIN_SALIENCE = 0.6;
/**
* Generate real action proposals for an agent from its mind (pending dreams +
* high-salience memories). Inserts them into agent_autopilot_proposals. Returns
* { created: [...], source } — never throws on LLM failure (falls back to
* deterministic heuristics so the feature degrades, never fakes).
*/
export async function generateProposals({ agentId, userId, agent }) {
// Existing live proposals — used to dedupe so we never enqueue the same thing.
const existing = await sql`
SELECT kind, params, source_reflection_id FROM agent_autopilot_proposals
WHERE agent_id = ${agentId} AND status IN ('pending', 'executed')
`;
const seenKeys = new Set();
const seenReflections = new Set();
for (const e of existing) {
if (e.source_reflection_id) seenReflections.add(e.source_reflection_id);
const v = validateProposal(e.kind, e.params);
if (v.ok) seenKeys.add(proposalDedupeKey(e.kind, v.params));
}
const candidates = [];
let source = 'memory';
// Source A: pending dreams that proposed an automation (provenance: reflection).
const dreams = await sql`
SELECT id, statement, rationale, confidence, source_memory_ids, proposed_action
FROM agent_reflections
WHERE agent_id = ${agentId} AND status = 'pending' AND proposed_action IS NOT NULL
ORDER BY created_at DESC
LIMIT 20
`;
for (const d of dreams) {
if (seenReflections.has(d.id)) continue;
const p = reflectionToProposal(d);
if (p) {
candidates.push(p);
source = 'reflection';
}
}
// Source B: high-salience memories → LLM synthesis (or heuristic fallback).
const memories = await sql`
SELECT id, type, content, tags, salience
FROM agent_memories
WHERE agent_id = ${agentId}
AND (expires_at IS NULL OR expires_at > now())
AND salience >= ${MIN_SALIENCE}
ORDER BY salience DESC, created_at DESC
LIMIT 40
`;
const validMemIds = new Set(memories.map((m) => m.id));
if (memories.length) {
let raw = [];
if (llmConfigured()) {
try {
const completion = await llmComplete({
system: PROPOSAL_SYSTEM,
user: buildProposalPrompt({ agent, memories }),
maxTokens: 1200,
timeoutMs: 30_000,
track: { userId, agentId, tool: 'autopilot.propose' },
});
const payload = parseProposalPayload(completion.text);
if (payload && Array.isArray(payload.proposals)) raw = payload.proposals;
} catch (err) {
if (!(err instanceof LlmUnavailableError)) {
console.warn('[autopilot] proposal LLM failed, using heuristics:', err?.message);
}
raw = heuristicProposals(memories);
source = 'heuristic';
}
} else {
raw = heuristicProposals(memories);
source = 'heuristic';
}
for (const r of raw) candidates.push(r);
}
// Validate + provenance-check + dedupe, then persist.
const created = [];
for (const c of candidates) {
if (created.length >= MAX_PROPOSALS_PER_RUN) break;
const kind = String(c.kind || '');
const v = validateProposal(kind, c.params || c);
if (!v.ok) continue;
// Provenance: keep only cited ids that are real memories of this agent.
// Reflection-sourced proposals already carry verified provenance.
const cited = Array.isArray(c.source_memory_ids) ? c.source_memory_ids : [];
const sourceIds = c.source_reflection_id
? [...new Set(cited.filter((id) => typeof id === 'string'))]
: [...new Set(cited.filter((id) => typeof id === 'string' && validMemIds.has(id)))];
if (!c.source_reflection_id && sourceIds.length === 0) continue; // ungrounded — drop
const key = proposalDedupeKey(kind, v.params);
if (seenKeys.has(key)) continue;
seenKeys.add(key);
const title = (typeof c.title === 'string' && c.title.trim() ? c.title : defaultTitle(kind, v)).slice(0, 160);
const rationale = (typeof c.rationale === 'string' && c.rationale.trim()
? c.rationale
: 'Grounded in your agent\'s memory.').slice(0, 600);
const confidence = clamp01(c.confidence, 0.6);
// wallet_transfer is irreversible → always requires confirmation here.
const requiresConfirmation = kind === 'wallet_transfer';
try {
const [row] = await sql`
INSERT INTO agent_autopilot_proposals
(agent_id, user_id, kind, title, rationale, params, source_memory_ids,
source_reflection_id, confidence, requires_confirmation)
VALUES (
${agentId}, ${userId}, ${kind}, ${title}, ${rationale},
${JSON.stringify(v.params)}::jsonb, ${sourceIds}::uuid[],
${c.source_reflection_id || null}, ${confidence}, ${requiresConfirmation}
)
RETURNING *
`;
created.push(decorateProposal(row));
} catch (err) {
// Unique-index race (same reflection enqueued concurrently) — skip, not fatal.
if (!/duplicate key|unique/i.test(err?.message || '')) throw err;
}
}
return { created, source, scanned: { memories: memories.length, dreams: dreams.length } };
}
function defaultTitle(kind, v) {
if (kind === 'create_alert') {
const m = v.params.asset === 'three' ? '$THREE' : `${v.rule.target_mint.slice(0, 6)}…`;
return `Alert: ${m} ${v.rule.kind.replace('_', ' ')}`;
}
if (kind === 'briefing') return v.params.summary;
return `Send ${v.params.amount_sol} SOL`;
}
function clamp01(n, dflt) {
const v = Number(n);
if (!Number.isFinite(v)) return dflt;
return Math.max(0, Math.min(1, v));
}
// ── Signed receipts ───────────────────────────────────────────────────────────
// Build the canonical message that gets ERC-191 signed for a receipt.
export function actionMessage({ agentId, type, ts, payload }) {
return [
'three.ws/autopilot',
`agent:${agentId}`,
`type:${type}`,
`ts:${ts}`,
`payload:${stableStringify(payload)}`,
].join('\n');
}
function stableStringify(obj) {
if (obj === null || typeof obj !== 'object') return JSON.stringify(obj);
if (Array.isArray(obj)) return `[${obj.map(stableStringify).join(',')}]`;
const keys = Object.keys(obj).sort();
return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
}
// Sign an action with the agent's EVM custodial key (ERC-191 personal_sign).
// Best-effort: returns { signature, signer_address } or nulls when no key
// exists — a missing key never blocks the action, the receipt is just unsigned.
async function signAction(agentId, userId, meta, type, ts, payload) {
const encrypted = meta?.encrypted_wallet_key;
if (!encrypted) return { signature: null, signer_address: null };
try {
const { recoverAgentKey } = await import('./agent-wallet.js');
const { Wallet } = await import('ethers');
const pk = await recoverAgentKey(encrypted, { agentId, userId, reason: 'autopilot.sign' });
const wallet = new Wallet(pk);
const signature = await wallet.signMessage(actionMessage({ agentId, type, ts, payload }));
return { signature, signer_address: wallet.address };
} catch (err) {
console.warn('[autopilot] action signing skipped:', err?.message);
return { signature: null, signer_address: null };
}
}
// Append a signed action to the real agent_actions log. Returns the row id.
async function recordAction({ agentId, userId, meta, type, payload }) {
const ts = new Date().toISOString();
const signed = { ...payload, ts };
const { signature, signer_address } = await signAction(agentId, userId, meta, type, ts, signed);
const [row] = await sql`
INSERT INTO agent_actions (agent_id, type, payload, source_skill, signature, signer_address)
VALUES (${agentId}, ${type}, ${JSON.stringify(signed)}::jsonb, 'autopilot', ${signature}, ${signer_address})
RETURNING id
`;
return { id: row.id, signature, signer_address, ts };
}
// ── Execution ─────────────────────────────────────────────────────────────────
export class AutopilotError extends Error {
constructor(message, { status = 400, code = 'autopilot_error' } = {}) {
super(message);
this.name = 'AutopilotError';
this.status = status;
this.code = code;
}
}
/** Sum of SOL sent by autopilot in the trailing 24h (real history from agent_actions). */
export async function dailySolSpent(agentId) {
const [row] = await sql`
SELECT COALESCE(SUM((payload->>'amount_sol')::numeric), 0) AS spent
FROM agent_actions
WHERE agent_id = ${agentId}
AND type = ${ACTION_TYPE.wallet_transfer}
AND created_at > now() - interval '24 hours'
`;
return Number(row?.spent ?? 0);
}
/** Live native SOL balance (in SOL) for an address. Best-effort RPC read. */
async function agentSolBalance(address) {
const { PublicKey } = await import('@solana/web3.js');
const { solanaConnection } = await import('./solana/connection.js');
// The operator's SOLANA_RPC_URL stays primary; the shared keyed/public lanes
// rotate in behind it so one provider's outage never blanks a balance check.
const conn = solanaConnection({ url: process.env.SOLANA_RPC_URL || null, network: 'mainnet', commitment: 'confirmed' });
const lamports = await conn.getBalance(new PublicKey(address), 'confirmed');
return lamports / LAMPORTS_PER_SOL;
}
/**
* A non-mutating preview of exactly what executing a proposal would do — the
* "dry run" that lets a cautious owner see before granting. Returns
* { kind, willDo, checks: [{label, ok, detail}], blocked }.
*/
export async function dryRunProposal({ proposal, agent, config }) {
const checks = [];
const kind = proposal.kind;
const scoped = config.scopes[kind] === true;
checks.push({ label: `Scope "${kind}" granted`, ok: scoped, detail: scoped ? 'granted' : 'not granted — enable it above' });
let willDo = '';
if (kind === 'create_alert') {
const v = validateProposal(kind, proposal.params);
willDo = v.ok
? `Create a real alert rule: ${v.rule.kind.replace('_', ' ')} on ${v.params.asset === 'three' ? '$THREE' : v.rule.target_mint}` +
(v.rule.threshold != null ? ` at ${v.rule.threshold}` : '') + '. Reversible — you can undo it.'
: `Invalid: ${v.reason}`;
checks.push({ label: 'Alert parameters valid', ok: v.ok, detail: v.ok ? 'ok' : v.reason });
} else if (kind === 'briefing') {
willDo = `Author a memory-grounded briefing ("${proposal.params.topic || proposal.params.summary}") and deliver it to your inbox. Reversible.`;
checks.push({ label: 'LLM available for synthesis', ok: llmConfigured(), detail: llmConfigured() ? 'ready' : 'will use a grounded summary fallback' });
} else {
const amt = Number(proposal.params.amount_sol) || 0;
willDo = `Send ${amt} SOL to ${proposal.params.recipient}. IRREVERSIBLE — always requires explicit confirmation. (Autopilot never sells or sends $THREE.)`;
const cap = config.daily_spend_sol;
const spent = await dailySolSpent(proposal.agentId);
const withinCap = config.scopes.wallet_transfer && cap > 0 && spent + amt <= cap;
checks.push({ label: `Within daily SOL cap (${cap})`, ok: withinCap, detail: `${spent} spent in 24h + ${amt} ≤ ${cap}` });
// Live native SOL balance check — real RPC read, no spend.
let bal = null;
try {
const { ensureAgentWallet } = await import('./agent-wallet.js');
const w = await ensureAgentWallet(proposal.agentId, agent.user_id, { reason: 'autopilot.dryrun' });
bal = await agentSolBalance(w.address);
} catch { /* balance is decoration on the preview */ }
checks.push({ label: 'Wallet SOL balance covers transfer', ok: bal == null ? false : bal >= amt, detail: bal == null ? 'could not read balance' : `${bal} SOL available` });
}
const blocked = checks.some((c) => !c.ok);
return { kind, willDo, checks, blocked };
}
/**
* Execute a proposal for real, within scope. Writes a signed agent_actions row
* with full provenance, links it back to the proposal, and returns
* { proposal, action, receipt }. Throws AutopilotError (4xx) on a guard breach —
* never a 500 for an expected denial.
*
* @param {object} opts.confirmed the owner explicitly confirmed an irreversible action this call
*/
export async function executeProposal({ proposal, agent, userId, meta, confirmed = false }) {
const config = getAutopilotConfig(meta);
const kind = proposal.kind;
if (!config.enabled) throw new AutopilotError('Autopilot is off — enable it to let the agent act.', { code: 'autopilot_disabled', status: 409 });
if (!config.scopes[kind]) throw new AutopilotError(`This agent isn't scoped to ${kind.replace('_', ' ')}.`, { code: 'scope_denied', status: 403 });
const irreversible = kind === 'wallet_transfer';
if (irreversible && config.require_confirm && !confirmed) {
throw new AutopilotError('This action moves real SOL and needs explicit confirmation.', { code: 'confirmation_required', status: 428 });
}
const provenance = {
proposal_id: proposal.id,
rationale: proposal.rationale,
source_memory_ids: proposal.sourceMemoryIds || [],
source_reflection_id: proposal.sourceReflectionId || null,
};
let action;
let result = {};
if (kind === 'create_alert') {
const v = validateProposal(kind, proposal.params);
if (!v.ok) throw new AutopilotError(`Invalid alert: ${v.reason}`);
const r = v.rule;
const [rule] = await sql`
INSERT INTO pump_alert_rules
(user_id, kind, target_mint, target_agent, threshold, deliver_in_app,
webhook_url, telegram_chat, cooldown_seconds, enabled, label)
VALUES (
${userId}, ${r.kind}, ${r.target_mint}, ${r.target_agent}, ${r.threshold},
${r.deliver_in_app}, ${r.webhook_url}, ${r.telegram_chat}, ${r.cooldown_seconds},
${r.enabled}, ${r.label}
)
RETURNING id
`;
result = { rule_id: rule.id, rule_kind: r.kind, target_mint: r.target_mint, threshold: r.threshold };
action = await recordAction({ agentId: proposal.agentId, userId, meta, type: ACTION_TYPE.create_alert, payload: { ...provenance, ...result } });
} else if (kind === 'briefing') {
const body = await composeBriefing({ agentId: proposal.agentId, userId, agent, params: proposal.params });
const [notif] = await sql`
INSERT INTO user_notifications (user_id, type, payload)
VALUES (${userId}, 'autopilot_briefing', ${JSON.stringify({
agent_id: proposal.agentId,
agent_name: agent.name || 'Your agent',
title: proposal.title,
body,
cadence: proposal.params.cadence,
proposal_id: proposal.id,
source_memory_ids: provenance.source_memory_ids,
})}::jsonb)
RETURNING id
`;
result = { notification_id: notif.id, cadence: proposal.params.cadence, body_preview: body.slice(0, 140) };
action = await recordAction({ agentId: proposal.agentId, userId, meta, type: ACTION_TYPE.briefing, payload: { ...provenance, ...result } });
} else {
// wallet_transfer — real, irreversible native SOL transfer (never $THREE).
result = await executeWalletTransfer({ proposal, agent, userId, config });
action = await recordAction({ agentId: proposal.agentId, userId, meta, type: ACTION_TYPE.wallet_transfer, payload: { ...provenance, ...result } });
}
const [row] = await sql`
UPDATE agent_autopilot_proposals
SET status = 'executed', decided_at = now(), executed_at = now(),
executed_action_id = ${action.id}, result = ${JSON.stringify(result)}::jsonb
WHERE id = ${proposal.id} AND status = 'pending'
RETURNING *
`;
if (!row) {
// Lost the race — already decided. The action is logged; surface idempotently.
const [cur] = await sql`SELECT * FROM agent_autopilot_proposals WHERE id = ${proposal.id}`;
return { proposal: decorateProposal(cur), action, receipt: buildReceipt(kind, result) };
}
return { proposal: decorateProposal(row), action, receipt: buildReceipt(kind, result) };
}
async function executeWalletTransfer({ proposal, agent, userId, config }) {
const amount = Number(proposal.params.amount_sol);
const recipient = proposal.params.recipient;
if (!SOLANA_ADDR_RE.test(recipient)) throw new AutopilotError('Invalid recipient address.');
if (!(amount > 0)) throw new AutopilotError('Transfer amount must be positive.');
// Daily SOL cap — real history. Autopilot spends SOL only; it never sells $THREE.
const cap = config.daily_spend_sol;
if (!(cap > 0)) throw new AutopilotError('No daily SOL spend budget is set.', { code: 'no_budget', status: 403 });
const spent = await dailySolSpent(proposal.agentId);
if (spent + amount > cap) {
throw new AutopilotError(`Daily SOL budget exceeded (${spent} + ${amount} > ${cap}).`, { code: 'budget_exceeded', status: 403 });
}
const { enforceDestinationAllowlist, SpendLimitError } = await import('./agent-trade-guards.js');
try {
await enforceDestinationAllowlist({ agentId: proposal.agentId, meta: agent.meta, category: 'autopilot', destination: recipient, usdValue: null });
} catch (e) {
if (e instanceof SpendLimitError) throw new AutopilotError(e.message, { code: e.code, status: 403 });
throw e;
}
const { ensureAgentWallet, recoverSolanaAgentKeypair } = await import('./agent-wallet.js');
const { transferNativeSol } = await import('./solana-transfer.js');
await ensureAgentWallet(proposal.agentId, agent.user_id, { reason: 'autopilot.transfer' });
const [row] = await sql`SELECT meta FROM agent_identities WHERE id = ${proposal.agentId}`;
const encryptedSecret = row?.meta?.encrypted_solana_secret;
const fromAddress = row?.meta?.solana_address;
if (!encryptedSecret || !fromAddress) throw new AutopilotError('Agent wallet not provisioned.', { code: 'no_wallet', status: 409 });
// Live native SOL balance must cover the transfer.
const lamports = BigInt(Math.round(amount * LAMPORTS_PER_SOL));
const balanceSol = await agentSolBalance(fromAddress).catch(() => null);
if (balanceSol != null && balanceSol < amount) {
throw new AutopilotError(`Insufficient SOL: wallet holds ${balanceSol}, needs ${amount}.`, { code: 'insufficient_funds', status: 402 });
}
const custodyId = await recordCustodyEvent({
agentId: proposal.agentId, userId, eventType: 'spend', category: 'autopilot',
network: 'mainnet', asset: 'SOL', amountRaw: lamports.toString(),
destination: recipient, reason: `autopilot ${proposal.params.reason || 'transfer'}`.slice(0, 200),
status: 'pending', meta: { proposal_id: proposal.id, amount_sol: amount },
});
let signature;
try {
const kp = await recoverSolanaAgentKeypair(encryptedSecret, { agentId: proposal.agentId, userId, reason: 'autopilot.transfer' });
signature = await transferNativeSol({
fromKeypair: kp,
toAddress: recipient,
lamports,
network: 'mainnet',
});
} catch (err) {
const { updateCustodyEvent } = await import('./agent-trade-guards.js');
await updateCustodyEvent(custodyId, { status: 'failed', meta: { error: (err?.message || 'transfer failed').slice(0, 300) } });
throw new AutopilotError(`SOL transfer failed: ${(err?.message || 'unknown').slice(0, 200)}`, { code: 'transfer_failed', status: 502 });
}
const { updateCustodyEvent } = await import('./agent-trade-guards.js');
await updateCustodyEvent(custodyId, { status: 'confirmed', signature });
return { signature, amount_sol: amount, recipient, asset: 'SOL', custody_id: custodyId };
}
// Author a real, memory-grounded briefing via the LLM (degrades to a grounded
// summary when no provider is configured — never a fake "the agent said X").
async function composeBriefing({ agentId, userId, agent, params }) {
const memories = await sql`
SELECT content, salience FROM agent_memories
WHERE agent_id = ${agentId} AND (expires_at IS NULL OR expires_at > now())
ORDER BY salience DESC, created_at DESC
LIMIT 12
`;
const grounded = memories.map((m) => `- ${truncate(m.content, 200)}`).join('\n');
if (!llmConfigured() || !memories.length) {
return `${params.summary}\n\nGrounded in what I know:\n${grounded || '(no memories yet)'}`.slice(0, 2000);
}
try {
const completion = await llmComplete({
system: [
`You are ${agent?.name || 'a personal AI agent'} writing a short briefing for your owner.`,
'Ground every statement in the provided memories. Be concise (under 120 words),',
'warm, and specific. The only coin you may reference is $THREE. No markdown headers.',
].join('\n'),
user: `Topic: ${params.topic || params.summary}\n\nWhat you know:\n${grounded}\n\nWrite the briefing.`,
maxTokens: 400,
timeoutMs: 25_000,
track: { userId, agentId, tool: 'autopilot.briefing' },
});
return (completion.text || params.summary).slice(0, 2000);
} catch {
return `${params.summary}\n\nGrounded in what I know:\n${grounded}`.slice(0, 2000);
}
}
function buildReceipt(kind, result) {
if (kind === 'create_alert') return `Created a ${String(result.rule_kind).replace('_', ' ')} alert.`;
if (kind === 'briefing') return 'Authored a briefing and delivered it to your inbox.';
return `Sent ${result.amount_sol} SOL.`;
}
// ── Trust loop (approve / dismiss / undo) ─────────────────────────────────────
/**
* Reverse a reversible action and write a feedback memory so the agent learns
* the boundary. wallet_transfer is irreversible and cannot be undone (on-chain).
*/
export async function undoProposal({ proposal, agentId, userId }) {
if (proposal.status !== 'executed') throw new AutopilotError('Only an executed action can be undone.', { code: 'not_executed', status: 409 });
if (proposal.kind === 'wallet_transfer') {
throw new AutopilotError('A SOL transfer is on-chain and cannot be undone.', { code: 'irreversible', status: 409 });
}
if (proposal.kind === 'create_alert' && proposal.result?.rule_id) {
await sql`DELETE FROM pump_alert_rules WHERE id = ${proposal.result.rule_id} AND user_id = ${userId}`;
} else if (proposal.kind === 'briefing' && proposal.result?.notification_id) {
await sql`DELETE FROM user_notifications WHERE id = ${proposal.result.notification_id} AND user_id = ${userId}`;
}
await sql`
UPDATE agent_autopilot_proposals
SET status = 'undone', decided_at = now()
WHERE id = ${proposal.id} AND status = 'executed'
`;
// Closing the loop with Reflection (Task 04/05): the undo is real feedback the
// agent remembers, so future reflections lean more conservative.
const fb = `I undid an autopilot action ("${truncate(proposal.title, 120)}"). Be more conservative before taking this kind of action again.`;
await sql`
INSERT INTO agent_memories (agent_id, type, content, tags, context, salience, tier, pinned)
VALUES (${agentId}, 'feedback', ${fb}, ${['autopilot', 'undo', 'boundary']},
${JSON.stringify({ source: 'autopilot_undo', proposal_id: proposal.id, kind: proposal.kind })}::jsonb,
0.8, 'recall', true)
`;
return { ok: true };
}
/** Dismiss a pending proposal; records a light feedback signal. */
export async function dismissProposal({ proposal, agentId }) {
if (proposal.status !== 'pending') throw new AutopilotError('Only a pending proposal can be dismissed.', { code: 'not_pending', status: 409 });
await sql`
UPDATE agent_autopilot_proposals
SET status = 'dismissed', decided_at = now()
WHERE id = ${proposal.id} AND status = 'pending'
`;
await sql`
INSERT INTO agent_memories (agent_id, type, content, tags, context, salience, tier, pinned)
VALUES (${agentId}, 'feedback', ${`I dismissed an autopilot proposal: "${truncate(proposal.title, 120)}". Don't propose this again.`},
${['autopilot', 'dismissed']},
${JSON.stringify({ source: 'autopilot_dismiss', proposal_id: proposal.id, kind: proposal.kind })}::jsonb,
0.6, 'recall', false)
`;
return { ok: true };
}
const TRUST_LEVELS = [
{ key: 'sandbox', label: 'Sandbox', min: 0, blurb: 'Proposes; you approve everything.' },
{ key: 'trusted', label: 'Trusted', min: 5, blurb: 'A track record of approved actions.' },
{ key: 'autonomous', label: 'Autonomous', min: 20, blurb: 'Consistently acts within your boundaries.' },
];
/**
* Trust level derived from REAL action history — not a vanity number.
* Score = approved actions, penalized by undos/dismissals, normalized by volume.
*/
export async function computeTrust({ agentId }) {
const [counts] = await sql`
SELECT
COUNT(*) FILTER (WHERE status = 'executed') AS executed,
COUNT(*) FILTER (WHERE status = 'undone') AS undone,
COUNT(*) FILTER (WHERE status = 'dismissed') AS dismissed,
COUNT(*) FILTER (WHERE status = 'pending') AS pending
FROM agent_autopilot_proposals
WHERE agent_id = ${agentId}
`;
const executed = Number(counts?.executed ?? 0);
const undone = Number(counts?.undone ?? 0);
const dismissed = Number(counts?.dismissed ?? 0);
const pending = Number(counts?.pending ?? 0);
// Net successful actions: each kept execution is +1, each undo cancels one out.
const net = Math.max(0, executed - undone);
const decided = executed + dismissed + undone;
// Reliability: of everything decided, how much did the owner keep?
const reliability = decided > 0 ? executed / decided : 0;
const score = Math.round(net * Math.max(0.25, reliability));
let level = TRUST_LEVELS[0];
for (const l of TRUST_LEVELS) if (score >= l.min) level = l;
return {
level: level.key,
label: level.label,
blurb: level.blurb,
score,
stats: { executed, undone, dismissed, pending, reliability: Math.round(reliability * 100) },
next: nextLevel(level, score),
};
}
function nextLevel(current, score) {
const idx = TRUST_LEVELS.findIndex((l) => l.key === current.key);
const nxt = TRUST_LEVELS[idx + 1];
if (!nxt) return null;
return { label: nxt.label, at: nxt.min, remaining: Math.max(0, nxt.min - score) };
}
// ── Serialization ─────────────────────────────────────────────────────────────
export function decorateProposal(row) {
return {
id: row.id,
agentId: row.agent_id,
userId: row.user_id,
kind: row.kind,
title: row.title,
rationale: row.rationale,
params: row.params || {},
sourceMemoryIds: row.source_memory_ids || [],
sourceReflectionId: row.source_reflection_id || null,
confidence: row.confidence != null ? Number(row.confidence) : null,
requiresConfirmation: row.requires_confirmation,
status: row.status,
executedActionId: row.executed_action_id != null ? String(row.executed_action_id) : null,
result: row.result || {},
createdAt: toIso(row.created_at),
decidedAt: toIso(row.decided_at),
executedAt: toIso(row.executed_at),
};
}
function toIso(d) {
if (!d) return null;
return d instanceof Date ? d.toISOString() : d;
}