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.

feat(strategy-loop): loop status read model, shutdown handover between steps and simulate-by-default loop trades

nirholas0405f6acc765
diff --git a/api/_lib/strategy-loop/lease.js b/api/_lib/strategy-loop/lease.js
index 64247f020..f0d28e6fa 100644
--- a/api/_lib/strategy-loop/lease.js
+++ b/api/_lib/strategy-loop/lease.js
@@ -17,11 +17,14 @@ import { sql } from '../db.js';
/**
* Claim up to `limit` agents whose loop is due (or has a tick left open by a
- * worker whose lease lapsed).
+ * worker whose lease lapsed). `agentIds`, when given, limits the sweep to
+ * those agents: a local run against the shared database uses it so it never
+ * picks up anyone else's loop.
* @returns {Promise<Array<{ agent_id: string, reclaimed: boolean, previous_worker: string|null }>>}
*/
-export async function claimDue({ workerId, limit, leaseMs }) {
+export async function claimDue({ workerId, limit, leaseMs, agentIds = null }) {
const leaseSecs = Math.max(10, Math.round(leaseMs / 1000));
+ const only = Array.isArray(agentIds) && agentIds.length ? agentIds : null;
const rows = await sql`
WITH due AS (
SELECT l.agent_id
@@ -29,6 +32,7 @@ export async function claimDue({ workerId, limit, leaseMs }) {
JOIN agent_identities a ON a.id = l.agent_id AND a.deleted_at IS NULL
LEFT JOIN agent_leases k ON k.agent_id = l.agent_id
WHERE (k.agent_id IS NULL OR k.lease_until < now())
+ AND (${only}::uuid[] IS NULL OR l.agent_id = ANY(${only}::uuid[]))
AND (
(l.enabled = true AND a.status = 'running' AND l.next_tick_at IS NOT NULL AND l.next_tick_at <= now()
AND (l.paused_until IS NULL OR l.paused_until <= now()))
diff --git a/api/_lib/strategy-loop/status.js b/api/_lib/strategy-loop/status.js
new file mode 100644
index 000000000..4423ba231
--- /dev/null
+++ b/api/_lib/strategy-loop/status.js
@@ -0,0 +1,205 @@
+// Strategy loop read model: one shape for GET /api/v1/agents/:id/loop, the
+// three://agents/{id}/loop MCP resource and the loop card on the agent page.
+//
+// state what the loop is doing right now (see loopState)
+// settings the agent_loops row, or the preset defaults before first save
+// lease which worker holds the agent, its last heartbeat and expiry
+// today ticks, failures and loop spend since UTC midnight, against caps
+// lastTick / nextTickAt / errors / ticks (the recent timeline)
+//
+// listTicks() and getTick() page through the full history and one tick's steps.
+
+import { sql } from '../db.js';
+import { serializeLoop } from './settings.js';
+import { loopSpendToday } from './budget.js';
+import { toolTiers } from './tools.js';
+
+export const TIMELINE_TICKS = 12;
+export const MAX_TICKS_PAGE = 100;
+const SUMMARY_PREVIEW_CHARS = 600;
+
+/**
+ * The loop's current state, derived from the agent, the loop row and the lease.
+ *
+ * off no loop, or the owner turned it off
+ * stopped the loop is on but the agent is stopped: nothing ticks
+ * paused a gate closed (cap, frozen wallet, credits, repeated errors)
+ * ticking a worker holds the agent and a tick is open
+ * backing_off the last ticks failed; the next one waits longer than usual
+ * scheduled healthy, waiting for the next tick
+ *
+ * @param {{ agentStatus: string, loop: object, lease: object|null, openTick: boolean, now?: Date }} o
+ */
+export function loopState({ agentStatus, loop, lease, openTick, now = new Date() }) {
+ if (!loop.configured || !loop.enabled) {
+ return loop.paused?.reason === 'repeated_errors' ? 'paused' : 'off';
+ }
+ if (agentStatus && agentStatus !== 'running') return 'stopped';
+ if (loop.paused) {
+ const until = loop.paused.until ? new Date(loop.paused.until) : null;
+ if (!until || until > now) return 'paused';
+ }
+ if (openTick && lease?.live) return 'ticking';
+ if (loop.consecutiveErrors > 0) return 'backing_off';
+ return 'scheduled';
+}
+
+function money(v) {
+ const n = Number(v);
+ return Number.isFinite(n) ? Math.round(n * 1e6) / 1e6 : 0;
+}
+
+/** Timeline row for one tick (no steps). */
+export function serializeTick(row) {
+ const summary = row.summary || null;
+ return {
+ id: row.id,
+ slot: row.slot,
+ status: row.status,
+ strategyId: row.strategy_id || null,
+ steps: row.step_count,
+ attempts: row.attempts,
+ resumed: row.attempts > 1,
+ spentCreditsUsd: money(row.spent_credits_usd),
+ spentUsd: money(row.spent_usd),
+ actions: row.actions,
+ summary: summary && summary.length > SUMMARY_PREVIEW_CHARS ? `${summary.slice(0, SUMMARY_PREVIEW_CHARS)}...` : summary,
+ error: row.error || null,
+ workerId: row.worker_id || null,
+ startedAt: row.started_at,
+ finishedAt: row.finished_at || null,
+ durationMs: row.finished_at ? new Date(row.finished_at) - new Date(row.started_at) : null,
+ };
+}
+
+function serializeLease(row, now = new Date()) {
+ if (!row) return null;
+ return {
+ workerId: row.worker_id,
+ heartbeatAt: row.heartbeat_at,
+ leaseUntil: row.lease_until,
+ live: new Date(row.lease_until) > now,
+ tickId: row.tick_id || null,
+ claims: row.claims,
+ reclaims: row.reclaims,
+ };
+}
+
+const TICK_COLUMNS = sql`
+ id, slot, status, strategy_id, step_count, attempts, spent_credits_usd, spent_usd, actions,
+ summary, error, worker_id, started_at, finished_at
+`;
+
+/**
+ * Everything the owner needs to see about an agent's loop.
+ * @param {{ id: string, user_id: string, status?: string, meta?: object, name?: string }} agent
+ */
+export async function loopStatus(agent) {
+ const [[row], [leaseRow], today, ticks] = await Promise.all([
+ sql`SELECT * FROM agent_loops WHERE agent_id = ${agent.id}`,
+ sql`SELECT * FROM agent_leases WHERE agent_id = ${agent.id}`,
+ loopSpendToday(agent.id),
+ sql`
+ SELECT ${TICK_COLUMNS} FROM agent_loop_ticks
+ WHERE agent_id = ${agent.id}
+ ORDER BY started_at DESC
+ LIMIT ${TIMELINE_TICKS}
+ `,
+ ]);
+ const loop = serializeLoop(row || null, agent);
+ const now = new Date();
+ const lease = serializeLease(leaseRow, now);
+ const timeline = ticks.map(serializeTick);
+ const open = timeline.find((t) => t.status === 'running') || null;
+ const last = timeline.find((t) => t.status !== 'running') || null;
+ const recentErrors = timeline.filter((t) => t.status === 'failed').slice(0, 5).map((t) => ({ tickId: t.id, at: t.startedAt, error: t.error }));
+ const agentStatus = agent.status || 'running';
+
+ return {
+ agentId: agent.id,
+ agentStatus,
+ state: loopState({ agentStatus, loop, lease, openTick: Boolean(open), now }),
+ settings: {
+ configured: loop.configured,
+ enabled: loop.enabled,
+ strategyId: loop.strategyId,
+ goal: loop.goal,
+ intervalSeconds: loop.intervalSeconds,
+ maxSteps: loop.maxSteps,
+ tools: loop.tools,
+ financialEnabled: loop.financialEnabled,
+ caps: loop.caps,
+ },
+ toolTiers: toolTiers(loop),
+ paused: loop.paused,
+ lease,
+ openTick: open,
+ lastTick: last,
+ lastTickAt: loop.lastTickAt,
+ lastTickStatus: loop.lastTickStatus,
+ nextTickAt: loop.enabled && agentStatus === 'running' ? loop.nextTickAt : null,
+ today: {
+ ticks: today.ticks,
+ failed: today.failed,
+ spentCreditsUsd: money(today.creditsUsd),
+ spentUsd: money(today.usdcUsd),
+ remainingCreditsUsd: money(Math.max(0, loop.caps.dailyCreditsUsd - today.creditsUsd)),
+ remainingUsd: money(Math.max(0, loop.caps.dailyUsdcUsd - today.usdcUsd)),
+ },
+ errors: { consecutive: loop.consecutiveErrors, recent: recentErrors },
+ ticks: timeline,
+ generatedAt: now.toISOString(),
+ };
+}
+
+/**
+ * A page of an agent's ticks, newest first. `before` is the startedAt of the
+ * last tick on the previous page.
+ */
+export async function listTicks(agentId, { limit = 25, before = null } = {}) {
+ const n = Math.max(1, Math.min(MAX_TICKS_PAGE, limit));
+ const rows = before
+ ? await sql`
+ SELECT ${TICK_COLUMNS} FROM agent_loop_ticks
+ WHERE agent_id = ${agentId} AND started_at < ${before}
+ ORDER BY started_at DESC LIMIT ${n + 1}`
+ : await sql`
+ SELECT ${TICK_COLUMNS} FROM agent_loop_ticks
+ WHERE agent_id = ${agentId}
+ ORDER BY started_at DESC LIMIT ${n + 1}`;
+ const items = rows.slice(0, n).map(serializeTick);
+ const hasMore = rows.length > n;
+ return { items, hasMore, nextCursor: hasMore ? new Date(items[items.length - 1].startedAt).toISOString() : null };
+}
+
+/** One tick with every step, or null when it is not this agent's. */
+export async function getTick(agentId, tickId) {
+ const [row] = await sql`
+ SELECT ${TICK_COLUMNS}, goal, previews FROM agent_loop_ticks WHERE id = ${tickId} AND agent_id = ${agentId}
+ `;
+ if (!row) return null;
+ const steps = await sql`
+ SELECT seq, kind, provider, model, tool_name, input, output, input_tokens, output_tokens, cost_usd, latency_ms, created_at
+ FROM agent_loop_tick_steps WHERE tick_id = ${row.id} ORDER BY seq ASC LIMIT 400
+ `;
+ return {
+ ...serializeTick(row),
+ summary: row.summary || null,
+ goal: row.goal,
+ previews: Object.entries(row.previews || {}).map(([id, p]) => ({ id, ...p })),
+ steps: steps.map((s) => ({
+ seq: s.seq,
+ kind: s.kind,
+ provider: s.provider || null,
+ model: s.model || null,
+ tool: s.tool_name || null,
+ input: s.input ?? null,
+ output: s.output ?? null,
+ inputTokens: s.input_tokens ?? null,
+ outputTokens: s.output_tokens ?? null,
+ costUsd: s.cost_usd == null ? null : money(s.cost_usd),
+ latencyMs: s.latency_ms ?? null,
+ at: s.created_at,
+ })),
+ };
+}
diff --git a/api/_lib/strategy-loop/tick.js b/api/_lib/strategy-loop/tick.js
index 0af423e7b..cbcc190d1 100644
--- a/api/_lib/strategy-loop/tick.js
+++ b/api/_lib/strategy-loop/tick.js
@@ -85,7 +85,7 @@ function fmtUsd(n) {
* The messages that open a tick: persona, the loop's operating rules, what the
* agent remembers and what its last ticks concluded, then the goal.
*/
-export function buildTickMessages({ agent, loop, preset, memory, recentTicks, tickNumber, now, remainingUsd }) {
+export function buildTickMessages({ agent, loop, preset, memory, recentTicks, tickNumber, now, remainingUsd, tradeMode = 'live' }) {
const name = agent.name || 'this agent';
const persona =
(agent.persona_prompt && agent.persona_prompt.trim()) ||
@@ -93,8 +93,12 @@ export function buildTickMessages({ agent, loop, preset, memory, recentTicks, ti
`You are ${name}, an autonomous agent on three.ws. You are careful, factual and concise.`;
const minutes = Math.round(loop.intervalSeconds / 60);
+ const wallet = agent.meta?.solana_address || null;
const rules = [
`You are running unattended as the strategy loop of ${name}, one tick every ${minutes} minute${minutes === 1 ? '' : 's'}. This is tick ${tickNumber}, at ${now.toISOString()}.`,
+ wallet
+ ? `The agent's own Solana wallet address is ${wallet}. Use it whenever the goal mentions the agent wallet.`
+ : 'This agent has no Solana wallet yet, so skip any wallet check and say so.',
'Use your tools to gather what you need. Never invent prices, balances or verdicts; if a tool returns nothing, say so.',
'Keep the tick short. Finish with a report of at most 120 words that starts with the most important change since the last tick, or with "No change." when nothing material moved.',
'Call remember for anything the next tick needs (levels, tokens you track, balances). Call notify_owner only for something the owner would act on.',
@@ -104,6 +108,9 @@ export function buildTickMessages({ agent, loop, preset, memory, recentTicks, ti
rules.push(
`You may trade from the agent wallet: call trade_preview first, then trade_execute with its preview_id and confirm_swap: true. Every trade passes the owner's spend limits, the rug and honeypot firewall and the anomaly guard. The loop may buy at most ${fmtUsd(remainingUsd)} more today. Trade only when your evidence clearly supports it, and report every trade.`,
);
+ if (tradeMode === 'simulate') {
+ rules.push('This loop host runs trades in simulate mode: trade_execute returns a simulation that signs and sends nothing, so report such trades as simulated, never as filled.');
+ }
} else {
rules.push('You cannot trade or move funds in this loop. Report and recommend instead.');
}
@@ -414,12 +421,18 @@ function eventRow(event) {
* @param {object} o
* @param {string} o.agentId
* @param {string} o.workerId
- * @param {{ tickTimeoutMs: number }} o.cfg
+ * @param {{ tickTimeoutMs: number, tradeMode?: 'simulate'|'live' }} o.cfg
+ * tradeMode 'simulate' (the worker default) runs every trade_execute as
+ * a simulation that signs and broadcasts nothing.
* @param {{ info: Function, warn: Function, error: Function }} o.log
+ * @param {{ aborted: boolean }} [o.signal] set by a draining worker: the tick
+ * stops at the next step boundary, still open with its checkpoint, so
+ * whichever worker claims the agent next resumes it.
* @param {object} [o.deps] { chain, trade } overrides for tests
* @returns {Promise<{ outcome: string, tickId?: string, reason?: string }>}
*/
-export async function runAgentTick({ agentId, workerId, cfg, log, deps = {} }) {
+export async function runAgentTick({ agentId, workerId, cfg, log, signal = null, deps = {} }) {
+ const tradeMode = cfg.tradeMode === 'live' ? 'live' : 'simulate';
const [agent] = await sql`
SELECT id, user_id, name, persona_prompt, meta, status, deleted_at
FROM agent_identities WHERE id = ${agentId}
@@ -484,6 +497,7 @@ export async function runAgentTick({ agentId, workerId, cfg, log, deps = {} }) {
tickNumber: n,
now: new Date(),
remainingUsd: Math.max(0, loop.caps.dailyUsdcUsd - spent.usdcUsd),
+ tradeMode,
});
({ state, context } = initialLoopState({ operationId: `tick-${tick.id}`, messages, maxSteps: runtimeSteps }));
}
@@ -495,7 +509,7 @@ export async function runAgentTick({ agentId, workerId, cfg, log, deps = {} }) {
return { outcome: 'failed', tickId: tick.id, reason: 'no_provider' };
}
- const tools = buildTickTools({ agent, loop, tick, deps });
+ const tools = buildTickTools({ agent, loop, tick, deps, tradeMode });
let pending = [];
const agentLoop = createAgentLoop({
chain,
@@ -516,6 +530,12 @@ export async function runAgentTick({ agentId, workerId, cfg, log, deps = {} }) {
try {
while (!loopFinished(state, context)) {
+ // A draining worker hands the tick over between steps: it stays open
+ // with its checkpoint and the next claimant resumes it.
+ if (signal?.aborted) {
+ log.info('tick interrupted for shutdown', { agentId, tickId: tick.id, step: stepCount });
+ return { outcome: 'interrupted', tickId: tick.id };
+ }
// Everything that can stop a tick is re-checked before each step.
if (!(await stillOwned({ workerId, agentId }))) {
log.warn('lease lost mid-tick', { agentId, tickId: tick.id });
diff --git a/api/_lib/strategy-loop/tools.js b/api/_lib/strategy-loop/tools.js
index 4a6b5b8ee..0e2c2d875 100644
--- a/api/_lib/strategy-loop/tools.js
+++ b/api/_lib/strategy-loop/tools.js
@@ -110,8 +110,10 @@ function clampText(v, max) {
* @param {object} o.loop serialized loop settings (serializeLoop)
* @param {object} o.tick agent_loop_ticks row
* @param {object} [o.deps] injectable trade engine (tests); defaults to the real one
+ * @param {'simulate'|'live'} [o.tradeMode] 'simulate' runs every execute as a
+ * simulation that signs and broadcasts nothing (the worker default)
*/
-export function buildTickTools({ agent, loop, tick, deps = {} }) {
+export function buildTickTools({ agent, loop, tick, deps = {}, tradeMode = 'simulate' }) {
const tiers = toolTiers(loop);
const schemas = [];
const handlers = {};
@@ -163,7 +165,7 @@ export function buildTickTools({ agent, loop, tick, deps = {} }) {
schemas.push(schema('trade_preview', FINANCIAL_TOOLS.trade_preview));
schemas.push(schema('trade_execute', FINANCIAL_TOOLS.trade_execute));
handlers.trade_preview = (args) => tradePreview({ agent, loop, tick, args, engine });
- handlers.trade_execute = (args) => tradeExecute({ agent, loop, tick, args, engine });
+ handlers.trade_execute = (args) => tradeExecute({ agent, loop, tick, args, engine, simulate: tradeMode !== 'live' });
}
return { schemas, handlers, tiers };
@@ -286,7 +288,7 @@ async function tradePreview({ agent, loop, tick, args, engine }) {
};
}
-async function tradeExecute({ agent, loop, tick, args, engine }) {
+async function tradeExecute({ agent, loop, tick, args, engine, simulate }) {
if (args?.confirm_swap !== true) {
return { ok: false, error: 'confirm_swap must be true to execute a trade.' };
}
@@ -357,6 +359,7 @@ async function tradeExecute({ agent, loop, tick, args, engine }) {
} catch (err) {
return { ok: false, error: err?.message || 'invalid trade' };
}
+ if (simulate) input.simulate = true;
const out = await engine.execute({
id: agent.id,
userId: agent.user_id,
@@ -368,6 +371,24 @@ async function tradeExecute({ agent, loop, tick, args, engine }) {
if (!out.ok) {
return { ok: false, blocked: true, code: out.code, error: out.message, detail: out.detail || null };
}
+ if (simulate) {
+ // Nothing was signed, so nothing counts against the loop's USD cap, but
+ // the action is still recorded on the tick.
+ if (!replay) {
+ await sql`UPDATE agent_loop_ticks SET actions = actions + 1, updated_at = now() WHERE id = ${tick.id}`;
+ }
+ return {
+ ok: true,
+ simulated: true,
+ side: preview.side,
+ mint: preview.mint,
+ amount: preview.amount,
+ usd_value: preview.usd,
+ expected_out: out.data?.expected_out ?? null,
+ signature: null,
+ note: 'Simulate mode: the trade passed every guard and was simulated on chain. Nothing was signed or sent.',
+ };
+ }
if (!replay && !out.data?.replayed) {
const usd = preview.side === 'buy' && preview.usd ? preview.usd : 0;
await sql`