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
// agent-orders — order reads + state transitions for the evaluation worker.
//
// Single-worker assumption (documented, mirrors agent-sniper): per-order state
// moves through an atomic claim (active|partial → firing) so a fire is owned by
// exactly one sweep. Across processes, the custody idempotency_key on each fill
// (order:<id>:slice:<n>) is the real double-spend backstop.
import { sql } from '../../api/_lib/db.js';
import { recordOrderEvent } from '../../api/_lib/orders.js';
const SKIP_REFRESH_MS = 60_000;
/**
* Active/partial orders on this network: the sweep's work set, least-recently-seen
* first.
*
* A price or conditional order has no next_fire_at, so ordering by that column
* alone with NULLS LAST parked every one of them behind every scheduled order:
* once the table held more than `limit` orders, the price side of the book would
* never be evaluated again. COALESCE rotates the work set instead (last_eval_at
* is stamped on every sweep), while a due slice still sorts ahead of an order
* that was evaluated a moment ago.
*/
export async function getActiveOrders(network, limit = 500) {
return sql`
SELECT * FROM orders
WHERE network = ${network}
AND status IN ('active', 'partial')
ORDER BY COALESCE(next_fire_at, last_eval_at, created_at) ASC
LIMIT ${limit}
`;
}
/**
* Expire orders past their deadline (active/partial/paused). Returns the expired
* rows so the sweep can log an event and tell the owner.
*/
export async function expireOrders(network) {
return sql`
UPDATE orders SET status = 'expired', cancel_reason = 'expired', updated_at = now()
WHERE network = ${network}
AND status IN ('active', 'partial', 'paused')
AND expires_at IS NOT NULL AND expires_at < now()
RETURNING id, agent_id, user_id, mint, symbol, type, side, fill_count
`;
}
/** Reset orders stuck in 'firing' (a crash mid-fire) back to their prior state. */
export async function recoverStaleFiring(network, staleMs = 180_000) {
const rows = await sql`
UPDATE orders
SET status = CASE WHEN fill_count > 0 THEN 'partial' ELSE 'active' END, updated_at = now()
WHERE network = ${network} AND status = 'firing'
AND updated_at < now() - (${Math.round(staleMs / 1000)} || ' seconds')::interval
RETURNING id
`;
return rows.length;
}
/**
* Atomically claim an order for firing. Returns true iff this caller flipped it
* active|partial → firing (so exactly one sweep fires it).
*/
export async function claimFire(orderId) {
const rows = await sql`
UPDATE orders SET status = 'firing', updated_at = now()
WHERE id = ${orderId} AND status IN ('active', 'partial')
RETURNING id
`;
return rows.length > 0;
}
/** Release a claimed order back to a non-firing state (e.g. fire aborted). */
export async function releaseFire(orderId, status, error = null) {
await sql`
UPDATE orders SET status = ${status}, last_error = ${error}, updated_at = now()
WHERE id = ${orderId} AND status = 'firing'
`;
}
/** Pin the route an order resolved to (launchpad | aggregator) the first time it prices. */
export async function setRoute(orderId, route) {
await sql`UPDATE orders SET route = ${route} WHERE id = ${orderId}`;
}
// One history writer for the API and the worker (api/_lib/orders.js).
export { recordOrderEvent };
/**
* Record why this evaluation did not fill. The reason lives on the order (what
* the book shows now); an event row is written only when the reason CHANGES, so
* an order waiting on the same cap for a day leaves one history row, not 17,000.
* `holdUntil` backs the order off (venue breaker) until that time.
*/
export async function noteSkip(order, code, detail = null, { holdUntil = null } = {}) {
const d = detail ? String(detail).slice(0, 280) : null;
// The same reason seen again within a minute is not news: skip the write, so
// a 3-second sweep over a large book does not rewrite every row every pass.
const lastAt = order.last_skip_at ? new Date(order.last_skip_at).getTime() : 0;
if (order.last_skip_code === code && !holdUntil && Date.now() - lastAt < SKIP_REFRESH_MS) return;
order.last_skip_at = new Date().toISOString();
await sql`
UPDATE orders
SET last_skip_code = ${code}, last_skip_detail = ${d}, last_skip_at = now(),
skip_count = skip_count + 1, hold_until = ${holdUntil}
WHERE id = ${order.id}
`;
if (order.last_skip_code !== code) {
await recordOrderEvent(order, 'skip', { code, detail: d });
order.last_skip_code = code;
}
}
/** A live quote that simply has not triggered: clear a stale skip reason. */
export async function clearSkip(order) {
if (!order.last_skip_code) return;
await sql`UPDATE orders SET last_skip_code = NULL, last_skip_detail = NULL, hold_until = NULL WHERE id = ${order.id}`;
order.last_skip_code = null;
}
/**
* A DCA slice whose price sat outside the order's band is consumed, not
* retried: "buy every hour, only under X" skips that hour. The schedule keeps a
* skipped_slices count beside filled_slices, and the order finishes when the two
* reach `slices` (filled if anything bought, expired if the band never let it).
*/
export async function consumeSkippedSlice(order, { terminal, nextFireAt }) {
const schedule = { ...(order.schedule || {}), skipped_slices: Number(order.schedule?.skipped_slices || 0) + 1 };
const status = terminal ? (order.fill_count > 0 ? 'filled' : 'expired') : order.status;
await sql`
UPDATE orders
SET schedule = ${JSON.stringify(schedule)}::jsonb,
next_fire_at = ${terminal ? null : nextFireAt},
status = ${status},
cancel_reason = ${terminal && order.fill_count === 0 ? 'band_never_reached' : null},
updated_at = now()
WHERE id = ${order.id} AND status IN ('active', 'partial')
`;
order.schedule = schedule;
return status;
}
/** Every order in a ladder or OCO group (for re-basing ladder legs). */
export async function getGroupOrders(groupId) {
return sql`SELECT id, status, sell_pct, size_tokens, group_leg, fill_count FROM orders WHERE group_id = ${groupId}`;
}
/**
* One OCO leg filled: cancel every other leg that can still fire, atomically,
* so the second leg never sells a bag the first one already sold. Returns the
* cancelled ids.
*/
export async function cancelGroupSiblings(order, reason) {
const rows = await sql`
UPDATE orders SET status = 'cancelled', cancel_reason = ${reason}, cancelled_at = now(), updated_at = now()
WHERE group_id = ${order.group_id} AND id <> ${order.id}
AND status IN ('active', 'partial', 'paused')
RETURNING id, agent_id
`;
for (const r of rows) await recordOrderEvent(r, 'cancel', { code: reason, detail: `leg ${order.id} filled` });
return rows.map((r) => r.id);
}
/** Persist the per-sweep observation (last metric value + trailing high/low-water). */
export async function markEvaluated(orderId, { lastPrice = null, peak = null } = {}) {
await sql`
UPDATE orders
SET last_eval_at = now(),
last_price = COALESCE(${lastPrice}, last_price),
peak_price = COALESCE(${peak}, peak_price)
WHERE id = ${orderId}
`;
}
/** Seed reference_price (first observation) so price_change_pct has a baseline. */
export async function seedReference(orderId, value) {
await sql`UPDATE orders SET reference_price = ${value}, peak_price = COALESCE(peak_price, ${value}) WHERE id = ${orderId} AND reference_price IS NULL`;
}
/**
* Record a fill and advance the order's lifecycle in one place.
*
* @param {object} o
* @param {object} o.order the order row
* @param {object} o.fill { sliceIndex, triggerReason, triggerPrice, solAmount, tokenAmount, priceImpactPct, venue, signature, custodyEventId, status, detail, meta }
* @param {boolean} o.terminal true → order is fully filled (price/conditional, or last slice)
* @param {boolean} [o.terminalError] true → a FAILED fill that should halt the order to 'error'
* (a block that won't clear by retrying), not return to active
* @param {string|null} o.nextFireAt ISO for the next scheduled slice (dca/twap), or null
*/
export async function recordFillAndAdvance({ order, fill, terminal, terminalError = false, nextFireAt = null }) {
const confirmedSol = fill.status === 'failed' ? 0 : Number(fill.solAmount || 0);
const confirmedTok = fill.status === 'failed' ? 0 : Number(fill.tokenAmount || 0);
await sql`
INSERT INTO order_fills
(order_id, agent_id, network, slice_index, side, trigger_reason, trigger_price,
sol_amount, token_amount, price_impact_pct, venue, signature, custody_event_id, status, detail, meta)
VALUES (
${order.id}, ${order.agent_id}, ${order.network}, ${fill.sliceIndex ?? null}, ${order.side},
${fill.triggerReason || null}, ${fill.triggerPrice ?? null}, ${fill.solAmount ?? null},
${fill.tokenAmount ?? null}, ${fill.priceImpactPct ?? null}, ${fill.venue || null},
${fill.signature || null}, ${fill.custodyEventId ?? null}, ${fill.status || 'pending'},
${fill.detail || null}, ${fill.meta ? JSON.stringify(fill.meta) : null}::jsonb)
`;
// A failed fill does not advance fills/budget and must not consume a slice. A
// terminal failure (a block that won't clear by retrying) halts the order to
// 'error'; an ordinary failure returns it to its prior state to retry next sweep.
if (fill.status === 'failed') {
const nextStatus = terminalError ? 'error' : (order.fill_count > 0 ? 'partial' : 'active');
await sql`
UPDATE orders SET status = ${nextStatus},
last_error = ${(fill.detail || 'fill_failed').slice(0, 280)},
consecutive_failures = consecutive_failures + 1, updated_at = now()
WHERE id = ${order.id} AND status = 'firing'
`;
return;
}
// Advance the schedule counter for dca/twap. A skipped (out-of-band) slice
// was already counted by consumeSkippedSlice.
let schedule = order.schedule || null;
if (schedule && (order.type === 'dca' || order.type === 'twap')) {
schedule = { ...schedule, filled_slices: (schedule.filled_slices || 0) + 1 };
}
const status = terminal ? 'filled' : 'partial';
await sql`
UPDATE orders SET
status = ${status},
filled_sol = filled_sol + ${confirmedSol},
filled_tokens = filled_tokens + ${confirmedTok},
fill_count = fill_count + 1,
schedule = ${schedule ? JSON.stringify(schedule) : null}::jsonb,
next_fire_at = ${terminal ? null : nextFireAt},
last_error = NULL,
updated_at = now()
WHERE id = ${order.id} AND status = 'firing'
`;
}
/** Load (and lightly cache) an agent's meta + user for the execution path. */
export async function loadAgent(agentId) {
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;
if (!row) return null;
return { id: row.id, userId: row.user_id, meta: { ...(row.meta || {}) } };
}