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
/**
* Shared lifecycle rules for recurring on-chain payments.
*
* Two schedule kinds ride the same rails:
* - `agent_subscriptions`: a fixed USDC transfer per period, charged by the
* run-subscriptions cron through /api/permissions/redeem.
* - EVM DCA schedules: a fixed USDC swap per period, executed by the run-dca
* cron through the same relayer. They live in the unified order store
* (`orders` rows on network 'evm', see api/_lib/dca-unified.js); the
* legacy `dca_strategies` table is only read once, to adopt old rows.
*
* Both used to treat every failure identically: pause the schedule and write a
* raw error string. A one-off RPC blip therefore killed a schedule as
* permanently as a revoked delegation, and nothing could set it back to
* 'active'. This module is the single place that decides what a failure means,
* so the crons, the API and the UI all agree on it.
*
* The outcomes:
* fatal the owner has to change something (revoked or expired
* delegation, a scope that no longer covers the charge). Retrying
* is guaranteed to fail, so the schedule pauses immediately.
* retryable nothing about the schedule is wrong; the attempt did not land
* (RPC down, relayer unreachable, wallet short of funds). The
* schedule stays active and the next tick tries again, up to
* MAX_CONSECUTIVE_FAILURES before it pauses.
* ambiguous the request timed out, so the transfer may or may not be
* on-chain. Never retried: the period is consumed and the schedule
* pauses for the owner to look at, because a retry here is the one
* failure mode that can double-charge.
* skipped the schedule deliberately declined to act this period (a DCA
* quote that moved too far between reads). Nothing is wrong, so
* the period is simply given up and the next one runs on time.
*
* One failure is recorded as retryable but handled apart from it: a
* platform-side outage (the relayer switched off, or rejecting our own
* credentials) is nobody's schedule being wrong. Those retry forever without
* counting toward the pause bound, because pausing every schedule on the
* platform over one operator config gap would be a far worse outage than the
* gap itself, and every one of them would then need a manual resume.
*/
/** Consecutive retryable failures a schedule survives before it is paused. */
export const MAX_CONSECUTIVE_FAILURES = 3;
/** Charge attempt outcomes, mirrored by subscription_charges.outcome. */
export const OUTCOME = {
CHARGED: 'charged',
FATAL: 'fatal',
RETRYABLE: 'retryable',
AMBIGUOUS: 'ambiguous',
SKIPPED: 'skipped',
};
// Codes that mean the schedule itself is no longer valid. Sourced from
// api/permissions/[action].js (the redeem handler) plus the cron's own guards.
const FATAL_CODES = new Set([
'chain_not_supported',
'delegation_expired',
'delegation_gone',
'delegation_not_found',
'delegation_revoked',
'scope_exceeded',
'target_not_allowed',
'unsupported_chain',
'validation_error',
]);
// Platform-side outages. Recorded as retryable, but never counted against the
// schedule's pause bound: the owner has nothing to fix and should not have to
// resume by hand once the operator restores the relayer.
const PLATFORM_CODES = new Set(['feature_disabled', 'unauthorized']);
// Codes that mean the attempt never landed and the next tick can try again.
const RETRYABLE_CODES = new Set([
'db_error',
'fetch_error',
'insufficient_balance',
'internal_error',
'no_tx_hash',
'relayer_error',
'rpc_error',
]);
// A reverted ERC-20 transfer surfaces through the relayer as a generic
// rpc_error. The wallet being short of USDC is the single most common cause and
// the only one the owner can fix by topping up, so it gets its own code rather
// than hiding inside "on-chain call failed".
const INSUFFICIENT_BALANCE_PATTERN =
/insufficient (?:funds|balance|allowance)|transfer amount exceeds balance|ERC20InsufficientBalance|exceeds balance/i;
// What the owner should do about each code, in plain language. Rendered
// verbatim in the recurring-payments UI, so it never shows a raw revert string.
const REASONS = {
chain_not_supported: 'This chain is no longer supported for recurring charges.',
delegation_expired: 'The signed permission behind this schedule expired. Grant a new one to restart it.',
delegation_gone: 'The signed permission behind this schedule is gone. Grant a new one to restart it.',
delegation_not_found: 'The signed permission behind this schedule no longer exists. Grant a new one to restart it.',
delegation_revoked: 'The signed permission was revoked. Grant a new one to restart this schedule.',
feature_disabled:
'On-chain relaying is switched off on this deployment, so nothing was charged. The schedule stays active and keeps trying.',
insufficient_balance: 'Your wallet did not hold enough USDC for this charge. Top it up and the next run will retry.',
internal_error: 'The charge failed inside the relayer. The next run will retry.',
no_tx_hash: 'The relayer accepted the charge but returned no transaction. The next run will retry.',
quote_divergence: 'The swap price moved too far between quotes, so the swap was abandoned rather than filled at a bad rate.',
relayer_error: 'The relayer rejected the charge. The next run will retry.',
rpc_error: 'The network could not be reached. The next run will retry.',
scope_exceeded: 'This charge is larger than the permission you signed allows for the period. Grant a wider permission to restart it.',
target_not_allowed: 'The permission you signed does not cover this payment target.',
timeout: 'The charge timed out, so we cannot tell whether it landed. The schedule is paused so it can never double-charge; check the transaction before resuming.',
unauthorized:
'The relayer rejected our own credentials, so nothing was charged. The schedule stays active while we fix it.',
unsupported_chain: 'This chain is no longer supported for recurring charges.',
validation_error: 'The charge was rejected as malformed. Nothing was charged.',
};
/**
* Turn a raw relayer/skill failure into the code, outcome and owner-facing
* reason the rest of the product uses.
*
* @param {{ code?: string|null, message?: string|null }} failure
* @returns {{ code: string, outcome: string, reason: string }}
*/
export function classifyChargeFailure({ code, message } = {}) {
const raw = String(code || '').trim();
const text = String(message || '');
if (raw === 'timeout' || /^timeout\b/i.test(text)) {
return { code: 'timeout', outcome: OUTCOME.AMBIGUOUS, reason: REASONS.timeout };
}
// A quote that moved between reads is the market, not a broken schedule.
// Give up this period only; the next one runs on time and the failure
// counter is untouched.
if (raw === 'quote_divergence') {
return {
code: 'quote_divergence',
outcome: OUTCOME.SKIPPED,
reason: REASONS.quote_divergence,
};
}
// An HTTP status the skill could not name: 4xx is ours to fix, 5xx is theirs
// and worth another tick.
const httpMatch = /^http_(\d{3})$/.exec(raw);
if (httpMatch) {
const status = Number(httpMatch[1]);
if (status >= 500) {
return {
code: 'relayer_error',
outcome: OUTCOME.RETRYABLE,
reason: REASONS.relayer_error,
};
}
return {
code: 'validation_error',
outcome: OUTCOME.FATAL,
reason: REASONS.validation_error,
};
}
if (INSUFFICIENT_BALANCE_PATTERN.test(text)) {
return {
code: 'insufficient_balance',
outcome: OUTCOME.RETRYABLE,
reason: REASONS.insufficient_balance,
};
}
if (PLATFORM_CODES.has(raw)) {
return {
code: raw,
outcome: OUTCOME.RETRYABLE,
platform: true,
reason: REASONS[raw],
};
}
if (FATAL_CODES.has(raw)) {
return { code: raw, outcome: OUTCOME.FATAL, reason: REASONS[raw] };
}
if (RETRYABLE_CODES.has(raw)) {
return { code: raw, outcome: OUTCOME.RETRYABLE, reason: REASONS[raw] };
}
// An unrecognised code is treated as retryable on purpose: the failure
// counter bounds it to MAX_CONSECUTIVE_FAILURES attempts, so an unknown
// transient recovers on its own while an unknown permanent still stops.
return {
code: raw || 'unknown',
outcome: OUTCOME.RETRYABLE,
reason: text ? `The charge failed: ${text}` : 'The charge failed. The next run will retry.',
};
}
/**
* Decide what a classified failure does to the schedule row.
*
* @param {{ outcome: string, consecutiveFailures: number, platform?: boolean }} opts
* consecutiveFailures is the count BEFORE this failure; `platform` marks an
* outage on our side rather than a problem with the schedule.
* @returns {{ pause: boolean, retry: boolean, consecutiveFailures: number }}
* `retry` means release the period claim so the next tick picks the row up
* again; `pause` means stop scheduling it until the owner resumes.
*/
export function applyChargeFailure({ outcome, consecutiveFailures = 0, platform = false }) {
const current = Number(consecutiveFailures) || 0;
// A deliberate skip is not a failure: the counter must not creep toward a
// pause across a volatile week.
if (outcome === OUTCOME.SKIPPED) {
return { pause: false, retry: false, consecutiveFailures: current };
}
// A platform outage retries indefinitely and never counts against the owner.
if (platform) {
return { pause: false, retry: true, consecutiveFailures: current };
}
const next = current + 1;
if (outcome === OUTCOME.FATAL) return { pause: true, retry: false, consecutiveFailures: next };
if (outcome === OUTCOME.AMBIGUOUS) {
return { pause: true, retry: false, consecutiveFailures: next };
}
const exhausted = next >= MAX_CONSECUTIVE_FAILURES;
return { pause: exhausted, retry: !exhausted, consecutiveFailures: next };
}
/** The charge-row status that goes with an outcome. */
export function chargeStatusFor(outcome) {
if (outcome === OUTCOME.CHARGED) return 'success';
if (outcome === OUTCOME.FATAL || outcome === OUTCOME.SKIPPED) return 'aborted';
if (outcome === OUTCOME.AMBIGUOUS) return 'unknown';
return 'failed';
}
// ── Schedule state machine ──────────────────────────────────────────────────
/** Statuses an owner is allowed to move a schedule between. */
const TRANSITIONS = {
pause: { from: ['active'], to: 'paused' },
resume: { from: ['paused'], to: 'active' },
};
/**
* Validate an owner-initiated pause/resume against the row's current status.
*
* Cancel is deliberately not here: it is terminal and each endpoint owns its
* own column names for it (`canceled_at` vs `cancelled_at`).
*
* @param {'pause'|'resume'} action
* @param {string} currentStatus
* @returns {{ ok: true, status: string } | { ok: false, code: string, message: string }}
*/
export function planStatusChange(action, currentStatus) {
const rule = TRANSITIONS[action];
if (!rule) {
return { ok: false, code: 'validation_error', message: `unknown action '${action}'` };
}
if (currentStatus === rule.to) {
return {
ok: false,
code: 'conflict',
message: `schedule is already ${rule.to}`,
};
}
if (!rule.from.includes(currentStatus)) {
return {
ok: false,
code: 'conflict',
message: `cannot ${action} a schedule that is ${currentStatus}`,
};
}
return { ok: true, status: rule.to };
}
// ── Formatting shared by the API responses and the page ─────────────────────
/** Human label for a period length in seconds. */
export function describePeriod(seconds) {
const s = Number(seconds);
if (!Number.isFinite(s) || s <= 0) return 'unknown';
if (s === 86400) return 'daily';
if (s === 604800) return 'weekly';
if (s === 2592000) return 'monthly';
if (s % 604800 === 0) return `every ${s / 604800} weeks`;
if (s % 86400 === 0) return `every ${s / 86400} days`;
if (s % 3600 === 0) return `every ${s / 3600} hours`;
return `every ${Math.round(s / 60)} minutes`;
}
/**
* Render a base-unit integer string as a decimal amount.
* USDC is 6 decimals on every chain these schedules run on.
*/
export function formatUnits(baseUnits, decimals = 6) {
const raw = String(baseUnits ?? '0');
if (!/^\d+$/.test(raw)) return '0';
const padded = raw.padStart(decimals + 1, '0');
const whole = padded.slice(0, padded.length - decimals);
const frac = padded.slice(padded.length - decimals).replace(/0+$/, '');
return frac ? `${whole}.${frac}` : whole;
}
/** Sum an array of base-unit integer strings without losing precision. */
export function sumUnits(values) {
return values
.reduce((acc, v) => acc + (/^\d+$/.test(String(v ?? '')) ? BigInt(v) : 0n), 0n)
.toString();
}