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
fix(economy): name the keep line that blocked a reclaim
nirholas0cfdff53b60b
diff --git a/api/_lib/economy-ledger.js b/api/_lib/economy-ledger.jsindex 96db59b26..7bdc5123c 100644--- a/api/_lib/economy-ledger.js+++ b/api/_lib/economy-ledger.js@@ -579,11 +579,23 @@ export function buildAgentReclaimRows({read_errors: readErrors.length,read_errors_logged: Math.min(readErrors.length, MAX_READ_ERROR_ROWS),skipped: skipped.length,+ // Bucket on the reason CLASS, the text before the first colon. Skip reasons+ // carry their numbers now (`at_or_below_floor:0.0006<0.015`,+ // `below_swap_rent:1253408<1870569`) so an operator can tell a fenced wallet+ // from an empty one; keying the histogram on the whole string would give a+ // fleet-wide run one bucket per wallet balance and destroy the count this+ // field exists to provide.skipped_reasons: skipped.reduce((acc, s) => {- const key = s?.reason || 'unknown';+ const key = String(s?.reason || 'unknown').split(':')[0];acc[key] = (acc[key] || 0) + 1;return acc;}, {}),+ // SOL sitting on skipped wallets that is real but fenced by a floor. Zero+ // means the sources are genuinely empty and only owner capital moves the+ // rail; non-zero means a floor decision would release funds we already own.+ skipped_floor_held_sol: round9(+ skipped.reduce((sum, s) => sum + (Number(s?.heldSol) || 0), 0),+ ),reclaimed_sol: reclaimed,deficit_sol: deficitSol == null ? null : round9(deficitSol),master_sol_before: before,diff --git a/api/_lib/economy-sweepback.js b/api/_lib/economy-sweepback.jsindex 606b79136..206efe3f6 100644--- a/api/_lib/economy-sweepback.js+++ b/api/_lib/economy-sweepback.js@@ -330,12 +330,69 @@ const RECLAIM_EXEMPT_NAMES = new Set(['circulation-treasury']);* @returns {number}*/export function reclaimableSol(currentSol, minSol, minSweep = MIN_SWEEP_SOL) {- const floor = Math.max(0, minSol);- const keepSol = floor + Math.max(0.005, floor * 0.1);- const reclaimable = round(currentSol - keepSol);+ const reclaimable = round(currentSol - reclaimKeepLineSol(minSol));return reclaimable >= minSweep ? reclaimable : 0;}+/**+ * The balance a wallet is left holding: its operating floor PLUS the anti-oscillation+ * buffer. Sizing (`reclaimableSol`) and reporting (`floorBlockedSkip`) both read it,+ * so the number an operator is shown is by construction the number that blocked the+ * sweep, and the two cannot drift apart the way a hand-written message would.+ *+ * @param {number} minSol+ * @returns {number}+ */+export function reclaimKeepLineSol(minSol) {+ const floor = Math.max(0, minSol);+ return round(floor + Math.max(0.005, floor * 0.1));+}++/**+ * Describe a wallet the reclaim leg will not draw from because its balance sits under+ * its own keep line.+ *+ * The bare string `at_or_below_floor` is why this exists. It was the ONLY thing three+ * consecutive triage sessions saw for every reclaim source, and it reads as "this+ * wallet is empty" when it equally means "this wallet holds real SOL behind a floor+ * somebody configured". Those are opposite operator situations: the first needs owner+ * capital, the second needs a floor reviewed, and neither the settle-health hint nor+ * the treasury-topup dry run could tell them apart. The x402 ring treasury held+ * 0.055 SOL against a 0.1 SOL floor inherited from a role its own registry comment+ * records as retired, and it printed exactly like the 110 genuinely-empty agent+ * wallets beside it. Carrying the two numbers in the reason (the `<have><<need>`+ * shape `below_swap_rent` already uses) makes that indistinguishable case impossible.+ *+ * @param {string} name+ * @param {number} currentSol+ * @param {number} minSol+ * @returns {{name:string, reason:string, heldSol:number, keepSol:number, floorSol:number}}+ */+export function floorBlockedSkip(name, currentSol, minSol) {+ const heldSol = round(Math.max(0, currentSol));+ const keepSol = reclaimKeepLineSol(minSol);+ return {+ name,+ reason: `at_or_below_floor:${heldSol}<${keepSol}`,+ heldSol,+ keepSol,+ floorSol: round(Math.max(0, minSol)),+ };+}++/**+ * Total SOL stranded on wallets the reclaim leg skipped for their own floor. A+ * non-zero total is the signal that the fleet is not empty, it is fenced: capital+ * exists on platform wallets and a floor decision, not an owner transfer, is what+ * would release it.+ *+ * @param {Array<{heldSol?:number}>} skipped+ * @returns {number}+ */+export function floorHeldSol(skipped) {+ return round((skipped || []).reduce((sum, s) => sum + (Number(s?.heldSol) || 0), 0));+}+/*** Emergency consolidation: pull IDLE SOL sitting above each engine's true* operating floor (`minSol`, not the topup `refillTo`) back to the master, SOL@@ -405,7 +462,7 @@ export async function reclaimIdleSol({ connection, network = 'mainnet', dryRun =// so the topup never re-funds a reclaimed engine and the two cannot ping-pong.const reclaimable = reclaimableSol(currentSol, w.minSol);if (reclaimable <= 0) {- skipped.push({ name, reason: 'at_or_below_floor' });+ skipped.push({ ...floorBlockedSkip(name, currentSol, w.minSol), pubkey: w.pubkey });continue;}if (dryRun) {@@ -430,6 +487,7 @@ export async function reclaimIdleSol({ connection, network = 'mainnet', dryRun =return {master,reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)),+ floorHeldSol: floorHeldSol(skipped),moves,skipped,failed,@@ -535,7 +593,7 @@ export function planAgentReclaim(candidates, opts = {}) {const floorSol = agentReclaimFloorSol(c.strategy);const reclaimable = reclaimableSol(c.sol, floorSol, minSweep);if (reclaimable <= 0) {- skipped.push({ name: c.name, reason: 'at_or_below_floor' });+ skipped.push(floorBlockedSkip(c.name, c.sol, floorSol));continue;}if (plan.length >= maxWallets) {@@ -545,7 +603,7 @@ export function planAgentReclaim(candidates, opts = {}) {plan.push({ agentId: c.agentId, name: c.name, address: c.address, sol: reclaimable, floorSol });total = round(total + reclaimable);}- return { plan, skipped, totalSol: total };+ return { plan, skipped, totalSol: total, floorHeldSol: floorHeldSol(skipped) };}/**@@ -695,7 +753,7 @@ export async function reclaimIdleAgentSol({ connection, network = 'mainnet', dryfor (const p of plan) {if (await openReclaimWallet(p, { audit: false })) moves.push({ ...p, dryRun: true });}- return { master, reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)), moves, skipped, failed, readErrors };+ return { master, reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)), floorHeldSol: floorHeldSol(skipped), moves, skipped, failed, readErrors };}for (const p of plan) {@@ -719,6 +777,7 @@ export async function reclaimIdleAgentSol({ connection, network = 'mainnet', dryreturn {master,reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)),+ floorHeldSol: floorHeldSol(skipped),moves,skipped,failed,diff --git a/api/_lib/ops/x402-settle-health.js b/api/_lib/ops/x402-settle-health.jsindex c01a7205b..4783d155d 100644--- a/api/_lib/ops/x402-settle-health.js+++ b/api/_lib/ops/x402-settle-health.js@@ -161,7 +161,11 @@ export function diagnoseSettleDrop({ noSolanaAccept, floorSignals, governorSkips'secret does not decrypt is reported at stage `recover` and its SOL is unreachable until ' +'WALLET_ENCRYPTION_KEY (or WALLET_ENCRYPTION_KEY_PREVIOUS) can open it, so no cron run and no ' +'RPC tier will ever move it. Owner SOL is needed when every reclaim source reports ' +- 'at_or_below_floor or secret_undecryptable. See docs/ops/production-log-triage.md.',+ 'at_or_below_floor or secret_undecryptable AND that plan reports ' ++ 'skipped_floor_held_sol 0. A floor skip carries its numbers ' ++ '(at_or_below_floor:<held><<keep>), so a non-zero held total means the SOL exists on a ' ++ 'platform wallet and a floor is fencing it, not that the fleet is empty. ' ++ 'See docs/ops/production-log-triage.md.',};}// Nothing failed and nothing was withdrawn: we are refusing our own settles to@@ -179,8 +183,9 @@ export function diagnoseSettleDrop({ noSolanaAccept, floorSignals, governorSkips'refills. Do NOT debug the facilitator and do NOT lower the sponsor floor. Read the live budget ' +'at GET /api/x402/runway-lab, then fund the fee wallet: POST /api/cron/treasury-topup?dry=1 ' +'(Bearer CRON_SECRET) shows what the free self-heal can reclaim, and owner SOL is needed only ' +- 'when every reclaim source reports at_or_below_floor or an undecryptable secret. ' +- 'See docs/x402-ring-economy.md "The wallet fee governor".',+ 'when every reclaim source reports at_or_below_floor or an undecryptable secret AND that ' ++ 'plan reports skipped_floor_held_sol 0; a non-zero held total is SOL we already own sitting ' ++ 'behind a configured floor. See docs/x402-ring-economy.md "The wallet fee governor".',};}return {diff --git a/tests/economy-sweepback.test.js b/tests/economy-sweepback.test.jsindex 52c2f9c78..30fe62784 100644--- a/tests/economy-sweepback.test.js+++ b/tests/economy-sweepback.test.js@@ -15,6 +15,9 @@ import {isPlatformOwnedAgent,PLATFORM_AGENT_OWNER_EMAIL,agentCandidateFromRow,+ reclaimKeepLineSol,+ floorBlockedSkip,+ floorHeldSol,} from '../api/_lib/economy-sweepback.js';import { MIN_OPERATIONAL_WALLET_SOL } from '../api/_lib/agent-trade-guards.js';import { autoFundTargetSol } from '../api/_lib/agent-funding-policy.js';@@ -316,7 +319,8 @@ test('planAgentReclaim honours the dust guard and the per-run wallet cap', () =>{ agentId: 'a', name: 'Persona', address: 'P1', owner: BOT, sol: 0.0051, strategy: { enabled: false } },]);assert.equal(dust.plan.length, 0);- assert.equal(dust.skipped[0].reason, 'at_or_below_floor');+ assert.match(dust.skipped[0].reason, /^at_or_below_floor:/);+ assert.equal(dust.skipped[0].heldSol, 0.0051);const many = Array.from({ length: 10 }, (_, i) => ({agentId: `a${i}`, name: `Persona ${i}`, address: `P${i}`, owner: BOT, sol: 1, strategy: { enabled: false },@@ -527,3 +531,86 @@ test('agent reclaim: rows chain like every other ledger batch', () => {assert.equal(new Set(hashes).size, rows.length);assert.ok(hashes.every((h) => /^[0-9a-f]{64}$/.test(h)));});++// A floor skip has to say WHICH situation it is. `at_or_below_floor` alone was the+// only thing three consecutive triage sessions saw for every reclaim source, and it+// reads as "this wallet is empty" while equally meaning "this wallet holds real SOL+// behind a floor somebody configured". The first needs owner capital; the second+// needs a floor reviewed. In production the x402 ring treasury held 0.055 SOL against+// a 0.1 SOL floor and printed exactly like the 110 genuinely-empty agent wallets+// beside it, so the operator instruction "owner SOL is needed when every reclaim+// source reports at_or_below_floor" fired while the platform already owned enough SOL+// to restart the rail 45 times over.+test('a floor skip separates a fenced wallet from an empty one, with both numbers', () => {+ const fenced = floorBlockedSkip('x402-treasury', 0.054995, 0.1);+ const empty = floorBlockedSkip('Swarm 2', 0, 0.01);++ // The keep line is the number that actually blocked the sweep, not the bare floor.+ assert.equal(fenced.keepSol, reclaimKeepLineSol(0.1));+ assert.equal(fenced.reason, `at_or_below_floor:0.054995<${reclaimKeepLineSol(0.1)}`);+ assert.equal(fenced.heldSol, 0.054995);+ assert.equal(fenced.floorSol, 0.1);++ assert.equal(empty.heldSol, 0);+ assert.match(empty.reason, /^at_or_below_floor:0</);++ // The two cases are now distinguishable by the field an operator acts on.+ assert.notEqual(fenced.reason, empty.reason);+ assert.ok(fenced.heldSol > 0 && empty.heldSol === 0);+});++// The reason and the sizing must read the same keep line, or the message would+// explain a refusal the code did not make.+test('the reported keep line is the one that made the sweep return nothing', () => {+ for (const [held, floor] of [[0.054995, 0.1], [0.0051, 0.01], [0, 0.05], [1.2, 0.05]]) {+ const skip = floorBlockedSkip('w', held, floor);+ const swept = reclaimableSol(held, floor);+ if (swept === 0) assert.ok(held < skip.keepSol + MIN_SWEEP_SOL, `${held}/${floor}`);+ // Invariant the keep line exists to hold: never leave a wallet under its floor.+ assert.ok(skip.keepSol >= skip.floorSol);+ }+});++test('floorHeldSol totals only the SOL a floor is fencing', () => {+ const skipped = [+ floorBlockedSkip('treasury', 0.054995, 0.1),+ floorBlockedSkip('a2a-payer', 0.0009, 0.05),+ floorBlockedSkip('Swarm 2', 0, 0.01),+ { name: 'circulation-treasury', reason: 'feed_sink_exempt' },+ ];+ assert.equal(floorHeldSol(skipped), 0.055895);+ // Genuinely empty sources total zero, which is the only state that needs owner SOL.+ assert.equal(floorHeldSol([floorBlockedSkip('a', 0, 0.01), floorBlockedSkip('b', 0, 0.01)]), 0);+ assert.equal(floorHeldSol([]), 0);+ assert.equal(floorHeldSol(undefined), 0);+});++// The ledger histogram counts skip CLASSES. Once a floor skip carries its numbers,+// keying that histogram on the whole reason string would give a fleet-wide run one+// bucket per wallet balance (110 buckets of 1 on the production fleet) and destroy+// the count the field exists to provide. Bucketing on the text before the colon is+// what keeps the two changes compatible.+test('ledger skip histogram buckets by class, so numbered reasons do not fragment it', () => {+ const skipped = [+ floorBlockedSkip('bot-one', 0.0009, 0.01),+ floorBlockedSkip('bot-two', 0.0031, 0.01),+ floorBlockedSkip('bot-three', 0, 0.01),+ { name: 'bot-four', reason: 'capital_committed' },+ ];+ // Every floor skip here carries a different number.+ assert.equal(new Set(skipped.slice(0, 3).map((x) => x.reason)).size, 3);++ const rows = buildAgentReclaimRows({+ masterPubkey: ECONOMY_MASTER_ADDRESS,+ masterSolBefore: 0.2,+ deficitSol: 0.4,+ result: { reclaimedSol: 0, moves: [], failed: [], skipped, readErrors: [] },+ solUsd: 100,+ now: 1_700_000_000_000,+ });+ const summary = rows[rows.length - 1];+ assert.deepEqual(summary.detail.skipped_reasons, { at_or_below_floor: 3, capital_committed: 1 });+ // And the fenced total rides along, so "nothing_reclaimable" can be read honestly.+ assert.equal(summary.detail.skipped_floor_held_sol, 0.004);+ assert.equal(summary.reason, 'nothing_reclaimable');+});