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.

fix(economy): name the keep line that blocked a reclaim

nirholas0cfdff53b60b
diff --git a/api/_lib/economy-ledger.js b/api/_lib/economy-ledger.js
index 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.js
index 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', dry
for (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', dry
return {
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.js
index 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.js
index 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');
+});