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.

9.9 KB
Raw Blame
// Strategy loop settings: the per-agent agent_loops row, its defaults from the
// strategy preset, and owner edits.
//
// Every setting has a preset default (data/agent-strategies.json `loop` block
// plus the preset's toolsAllowed), so enabling the loop on an agent created
// from a preset needs no configuration at all. An owner may override the goal,
// the interval, the read tools, the caps and whether the financial tier is on.
// The financial tier is off until the owner turns it on explicitly with
// `confirm_financial: true` AND has signed the real-funds agreements.

import { sql } from '../db.js';
import { AGENT_TOOLS } from '../agent-tools.js';
import { getStrategy } from '../agents-v1/strategies.js';

export const MIN_INTERVAL_SECONDS = 60;
export const MAX_INTERVAL_SECONDS = 86_400;
export const DEFAULT_INTERVAL_SECONDS = 300;
export const DEFAULT_MAX_STEPS = 12;
export const DEFAULT_CREDIT_CAP_USD = 0.5;
export const MAX_CAP_USD = 10_000;
export const MAX_GOAL_CHARS = 2000;

// When a loop runs without a preset: read tools that change nothing and
// answer the questions a strategy asks every tick.
export const DEFAULT_READ_TOOLS = Object.freeze(['token_price', 'trending_tokens', 'token_safety', 'sol_balance', 'web_search']);

export const DEFAULT_GOAL =
	'Check the markets and the agent wallet, compare with what you remembered from earlier ticks, report only what changed, and remember anything worth tracking next time.';

/** The v1 error shape, without importing the HTTP layer into the worker. */
export class LoopSettingsError extends Error {
	constructor(status, code, message, details = null) {
		super(message);
		this.status = status;
		this.code = code;
		this.details = details;
	}
}

const bad = (code, message, parameter) => new LoopSettingsError(400, code, message, parameter ? { parameter } : null);

/** The strategy preset an agent was created with, or null. */
export function presetFor(agent) {
	const id = agent?.meta?.runtime?.strategy || null;
	return id ? getStrategy(id) || null : null;
}

/** The settings a brand-new loop starts from for this agent. */
export function loopDefaults(agent) {
	const preset = presetFor(agent);
	return {
		strategyId: preset?.id || null,
		goal: preset?.loop?.goal || DEFAULT_GOAL,
		intervalSeconds: preset?.loop?.intervalMinutes ? preset.loop.intervalMinutes * 60 : DEFAULT_INTERVAL_SECONDS,
		tools: [...(preset?.toolsAllowed || DEFAULT_READ_TOOLS)],
		dailyCreditCapUsd: preset?.loop?.dailyCreditCapUsd ?? DEFAULT_CREDIT_CAP_USD,
		dailyUsdcCapUsd: 0,
		financialEnabled: false,
		maxSteps: DEFAULT_MAX_STEPS,
	};
}

function num(v) {
	const n = Number(v);
	return Number.isFinite(n) ? n : 0;
}

/** Shape an agent_loops row (or the defaults when there is none) for callers. */
export function serializeLoop(row, agent) {
	if (!row) {
		const d = loopDefaults(agent);
		return {
			configured: false,
			enabled: false,
			strategyId: d.strategyId,
			goal: d.goal,
			intervalSeconds: d.intervalSeconds,
			tools: d.tools,
			financialEnabled: false,
			maxSteps: d.maxSteps,
			caps: { dailyCreditsUsd: d.dailyCreditCapUsd, dailyUsdcUsd: 0 },
			paused: null,
			nextTickAt: null,
			lastTickAt: null,
			lastTickStatus: null,
			consecutiveErrors: 0,
		};
	}
	return {
		configured: true,
		enabled: row.enabled,
		strategyId: row.strategy_id,
		goal: row.goal || DEFAULT_GOAL,
		intervalSeconds: row.interval_seconds,
		tools: row.tools || [],
		financialEnabled: row.financial_enabled,
		maxSteps: row.max_steps,
		caps: { dailyCreditsUsd: num(row.daily_credit_cap_usd), dailyUsdcUsd: num(row.daily_usdc_cap_usd) },
		paused: row.paused_reason
			? { reason: row.paused_reason, detail: row.paused_detail || null, at: row.paused_at, until: row.paused_until }
			: null,
		nextTickAt: row.next_tick_at,
		lastTickAt: row.last_tick_at,
		lastTickStatus: row.last_tick_status,
		consecutiveErrors: row.consecutive_errors,
	};
}

export async function getLoopRow(agentId) {
	const [row] = await sql`SELECT * FROM agent_loops WHERE agent_id = ${agentId}`;
	return row || null;
}

function capParam(v, name) {
	const n = Number(v);
	if (!Number.isFinite(n) || n < 0 || n > MAX_CAP_USD) throw bad('invalid_parameter', `${name} must be a number from 0 to ${MAX_CAP_USD}.`, name);
	return Math.round(n * 1e6) / 1e6;
}

/**
 * Validate a PATCH body into a partial settings object. Unknown keys are
 * ignored; a present key with a bad value is a 400 naming the parameter.
 */
export function parseLoopPatch(body) {
	const b = body && typeof body === 'object' ? body : {};
	const out = {};
	if ('enabled' in b) {
		if (typeof b.enabled !== 'boolean') throw bad('invalid_parameter', 'enabled must be true or false.', 'enabled');
		out.enabled = b.enabled;
	}
	if ('goal' in b) {
		if (b.goal === null || b.goal === '') out.goal = null;
		else if (typeof b.goal !== 'string' || b.goal.trim().length > MAX_GOAL_CHARS) {
			throw bad('invalid_parameter', `goal must be text of at most ${MAX_GOAL_CHARS} characters.`, 'goal');
		} else out.goal = b.goal.trim();
	}
	if ('intervalSeconds' in b || 'intervalMinutes' in b) {
		const secs = 'intervalSeconds' in b ? Number(b.intervalSeconds) : Number(b.intervalMinutes) * 60;
		if (!Number.isInteger(secs) || secs < MIN_INTERVAL_SECONDS || secs > MAX_INTERVAL_SECONDS) {
			throw bad('invalid_parameter', `The interval must be a whole number of seconds from ${MIN_INTERVAL_SECONDS} to ${MAX_INTERVAL_SECONDS}.`, 'intervalSeconds');
		}
		out.intervalSeconds = secs;
	}
	if ('tools' in b) {
		if (!Array.isArray(b.tools) || b.tools.length > 20) throw bad('invalid_parameter', 'tools must be an array of tool names.', 'tools');
		const unknown = b.tools.filter((t) => typeof t !== 'string' || !AGENT_TOOLS[t]);
		if (unknown.length) {
			throw new LoopSettingsError(400, 'unknown_tool', `Unknown read tool: ${unknown.join(', ')}.`, {
				parameter: 'tools',
				available: Object.keys(AGENT_TOOLS),
			});
		}
		out.tools = [...new Set(b.tools)];
	}
	if ('maxSteps' in b) {
		const n = Number(b.maxSteps);
		if (!Number.isInteger(n) || n < 3 || n > 40) throw bad('invalid_parameter', 'maxSteps must be an integer from 3 to 40.', 'maxSteps');
		out.maxSteps = n;
	}
	const caps = b.caps && typeof b.caps === 'object' ? b.caps : {};
	if ('dailyCreditsUsd' in caps) out.dailyCreditCapUsd = capParam(caps.dailyCreditsUsd, 'caps.dailyCreditsUsd');
	if ('dailyUsdcUsd' in caps) out.dailyUsdcCapUsd = capParam(caps.dailyUsdcUsd, 'caps.dailyUsdcUsd');
	if ('financialEnabled' in b) {
		if (typeof b.financialEnabled !== 'boolean') throw bad('invalid_parameter', 'financialEnabled must be true or false.', 'financialEnabled');
		if (b.financialEnabled && b.confirm_financial !== true) {
			throw new LoopSettingsError(
				400,
				'confirmation_required',
				'Turning on the financial tier lets loop ticks trade from the agent wallet within your caps and guards. Resend with "confirm_financial": true to confirm.',
				{ parameter: 'confirm_financial' },
			);
		}
		out.financialEnabled = b.financialEnabled;
	}
	return out;
}

/** The first UTC midnight after `now`. */
export function nextUtcMidnight(now = new Date()) {
	return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
}

/**
 * Apply a parsed patch, creating the row from the preset defaults on first
 * write. Turning the loop on schedules the first tick immediately; raising a
 * cap that paused the loop lifts the pause. Returns the new row.
 */
export async function saveLoopSettings(agent, patch) {
	const d = loopDefaults(agent);
	const existing = await getLoopRow(agent.id);
	const cur = existing
		? {
				enabled: existing.enabled,
				goal: existing.goal,
				intervalSeconds: existing.interval_seconds,
				tools: existing.tools,
				financialEnabled: existing.financial_enabled,
				maxSteps: existing.max_steps,
				dailyCreditCapUsd: num(existing.daily_credit_cap_usd),
				dailyUsdcCapUsd: num(existing.daily_usdc_cap_usd),
			}
		: { ...d, enabled: false };
	const next = { ...cur, ...patch };

	const turningOn = next.enabled && !cur.enabled;
	const capRaised =
		(patch.dailyCreditCapUsd != null && patch.dailyCreditCapUsd > cur.dailyCreditCapUsd) ||
		(patch.dailyUsdcCapUsd != null && patch.dailyUsdcCapUsd > cur.dailyUsdcCapUsd);
	const clearCapPause = capRaised || turningOn;

	const [row] = await sql`
		INSERT INTO agent_loops (
			agent_id, user_id, enabled, strategy_id, goal, interval_seconds, tools,
			financial_enabled, max_steps, daily_credit_cap_usd, daily_usdc_cap_usd, next_tick_at
		) VALUES (
			${agent.id}, ${agent.user_id}, ${next.enabled}, ${d.strategyId}, ${next.goal}, ${next.intervalSeconds}, ${next.tools},
			${next.financialEnabled}, ${next.maxSteps}, ${String(next.dailyCreditCapUsd)}, ${String(next.dailyUsdcCapUsd)},
			${next.enabled ? new Date().toISOString() : null}
		)
		ON CONFLICT (agent_id) DO UPDATE SET
			enabled = EXCLUDED.enabled,
			goal = EXCLUDED.goal,
			interval_seconds = EXCLUDED.interval_seconds,
			tools = EXCLUDED.tools,
			financial_enabled = EXCLUDED.financial_enabled,
			max_steps = EXCLUDED.max_steps,
			daily_credit_cap_usd = EXCLUDED.daily_credit_cap_usd,
			daily_usdc_cap_usd = EXCLUDED.daily_usdc_cap_usd,
			next_tick_at = CASE
				WHEN ${turningOn} THEN now()
				WHEN EXCLUDED.enabled AND agent_loops.next_tick_at IS NULL THEN now()
				ELSE agent_loops.next_tick_at END,
			consecutive_errors = CASE WHEN ${turningOn} THEN 0 ELSE agent_loops.consecutive_errors END,
			errors_alerted_at = CASE WHEN ${turningOn} THEN NULL ELSE agent_loops.errors_alerted_at END,
			paused_reason = CASE WHEN ${clearCapPause} AND agent_loops.paused_reason IN ('credit_cap', 'usdc_cap', 'repeated_errors')
				THEN NULL ELSE agent_loops.paused_reason END,
			paused_detail = CASE WHEN ${clearCapPause} AND agent_loops.paused_reason IN ('credit_cap', 'usdc_cap', 'repeated_errors')
				THEN NULL ELSE agent_loops.paused_detail END,
			paused_until = CASE WHEN ${clearCapPause} AND agent_loops.paused_reason IN ('credit_cap', 'usdc_cap', 'repeated_errors')
				THEN NULL ELSE agent_loops.paused_until END,
			updated_at = now()
		RETURNING *
	`;
	return row;
}