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.

test(marketplace): prove agent-sale settlement resumes to completion when killed at any step

qhqf9a59c837d066
diff --git a/api/_lib/agent-market/escrow.js b/api/_lib/agent-market/escrow.js
index e98c56d90..ccac0270d 100644
--- a/api/_lib/agent-market/escrow.js
+++ b/api/_lib/agent-market/escrow.js
@@ -59,6 +59,7 @@ export async function fundFromAgentWallet({ bid, listing, fundingAgent }) {
fromMeta: fundingAgent.meta,
toAddress: listing.escrow_address,
usdc,
+ amountAtomics: BigInt(String(bid.amount_atomics)),
network: marketNetwork(),
category: 'marketplace_bid',
idempotencyKey: `agent-market-bid:${bid.id}`,
diff --git a/tests/agent-market-settlement.test.js b/tests/agent-market-settlement.test.js
new file mode 100644
index 000000000..23622ae68
--- /dev/null
+++ b/tests/agent-market-settlement.test.js
@@ -0,0 +1,330 @@
+// Whole-agent marketplace settlement (api/_lib/agent-market/*).
+//
+// The acceptance bar for custody rotation is "kill it mid-way and it resumes to
+// completion". These tests drive the real runTransfer state machine against an
+// in-memory store with the same compare-and-set semantics as the database
+// store, kill it at every step in turn, and prove a resume finishes the
+// transfer with each step's effect applied exactly once. They also pin the
+// exactly-once leg reconciliation (a resumed payout can never pay twice), the
+// amount math, the escrow derivation guard, and the MCP financial gate.
+
+import { describe, it, expect, vi } from 'vitest';
+import { Keypair } from '@solana/web3.js';
+
+vi.mock('../api/_lib/db.js', () => ({
+ sql: vi.fn(async () => []),
+ isDbUnavailableError: () => false,
+ isDbCapacityError: () => false,
+}));
+vi.mock('../api/_lib/audit.js', () => ({ logAudit: vi.fn(), logAuditNow: vi.fn() }));
+vi.mock('../api/_lib/notify.js', () => ({ insertNotification: vi.fn() }));
+vi.mock('../api/_lib/rate-limit.js', () => {
+ const allow = async () => ({ success: true, limit: 100, remaining: 99, reset: Date.now() + 60_000 });
+ return { limits: new Proxy({}, { get: () => allow }), clientIp: () => '127.0.0.1' };
+});
+
+const { STEPS, nextStep, runTransfer, transferView } = await import('../api/_lib/agent-market/settlement.js');
+const chain = await import('../api/_lib/agent-market/chain.js');
+
+// ── In-memory store with the database store's semantics ──────────────────────
+
+function memoryStore(initial) {
+ const rows = new Map([[initial.id, { ...initial }]]);
+ let now = 0;
+ return {
+ rows,
+ tick(ms = 1) { now += ms; },
+ async lease(id) {
+ const r = rows.get(id);
+ if (!r || r.status === 'completed') return null;
+ if (r.locked_until != null && r.locked_until > now) return null;
+ Object.assign(r, { locked_until: now + 600_000, attempts: r.attempts + 1, status: 'in_progress' });
+ return { ...r };
+ },
+ async load(id) { return rows.has(id) ? { ...rows.get(id) } : null; },
+ async advance(id, from, to) {
+ const r = rows.get(id);
+ if (r.step !== from) throw new Error(`transfer ${id} left step ${from} under another worker`);
+ Object.assign(r, {
+ step: to, last_error: null, locked_until: now + 600_000,
+ status: to === 'done' ? 'completed' : r.status,
+ });
+ return { ...r };
+ },
+ async fail(id, step, message) {
+ Object.assign(rows.get(id), { status: 'failed', last_error: `${step}: ${message}`, locked_until: null });
+ },
+ async release(id) { rows.get(id).locked_until = null; },
+ };
+}
+
+function newTransfer() {
+ return {
+ id: 't1', listing_id: 'l1', bid_id: 'b1', agent_id: 'a1', buyer_user_id: 'buyer', seller_user_id: 'seller',
+ currency: 'USDC', amount_atomics: '5000000', fee_atomics: '125000', seller_net_atomics: '4875000',
+ step: 'pay_seller', status: 'in_progress', attempts: 0, locked_until: null, last_error: null,
+ rotation: {}, legs: {}, updated_at: new Date().toISOString(),
+ };
+}
+
+// Steps that record their EFFECT idempotently, the way the real steps check
+// on-chain and database state before acting. `killAt` makes a step die after
+// its effect landed but before the runner could advance (the worst case for a
+// resume), or before the effect when `killBeforeEffect` is set.
+function recordingSteps({ killAt = null, killBeforeEffect = false } = {}) {
+ const effects = new Map();
+ const calls = [];
+ let killed = false;
+ const steps = {};
+ for (const step of STEPS) {
+ steps[step] = async () => {
+ calls.push(step);
+ const die = !killed && step === killAt;
+ if (die && killBeforeEffect) {
+ killed = true;
+ throw Object.assign(new Error(`process killed before ${step}`), { code: 'killed' });
+ }
+ if (!effects.has(step)) effects.set(step, 1);
+ if (die) {
+ killed = true;
+ throw Object.assign(new Error(`process killed during ${step}`), { code: 'killed' });
+ }
+ };
+ }
+ return { steps, effects, calls };
+}
+
+const context = async (transfer) => ({ transfer, listing: { id: 'l1' }, agent: { id: 'a1' } });
+
+describe('settlement state machine', () => {
+ it('walks every step in order to done', async () => {
+ const store = memoryStore(newTransfer());
+ const { steps, calls } = recordingSteps();
+ const run = await runTransfer('t1', { store, steps, context, log: false });
+ expect(run.error).toBeUndefined();
+ expect(run.transfer.step).toBe('done');
+ expect(run.transfer.status).toBe('completed');
+ expect(calls).toEqual(STEPS);
+ });
+
+ it.each(STEPS)('killed during %s, resumes to completion with every effect applied once', async (killAt) => {
+ const store = memoryStore(newTransfer());
+ const { steps, effects } = recordingSteps({ killAt });
+
+ const first = await runTransfer('t1', { store, steps, context, log: false });
+ expect(first.error).toMatchObject({ step: killAt, code: 'killed' });
+ expect(first.transfer.status).toBe('failed');
+ expect(first.transfer.step).toBe(killAt);
+ expect(first.transfer.locked_until).toBeNull();
+
+ const resumed = await runTransfer('t1', { store, steps, context, log: false });
+ expect(resumed.error).toBeUndefined();
+ expect(resumed.transfer.status).toBe('completed');
+ for (const step of STEPS) expect(effects.get(step)).toBe(1);
+ });
+
+ it.each(STEPS)('killed before %s ran, resumes and runs it', async (killAt) => {
+ const store = memoryStore(newTransfer());
+ const { steps, effects } = recordingSteps({ killAt, killBeforeEffect: true });
+ await runTransfer('t1', { store, steps, context, log: false });
+ const resumed = await runTransfer('t1', { store, steps, context, log: false });
+ expect(resumed.transfer.status).toBe('completed');
+ for (const step of STEPS) expect(effects.get(step)).toBe(1);
+ });
+
+ it('a live lease keeps a second worker out, an expired one lets it resume', async () => {
+ const store = memoryStore(newTransfer());
+ await store.lease('t1'); // a worker died holding the lease
+ const { steps } = recordingSteps();
+ const blocked = await runTransfer('t1', { store, steps, context, log: false });
+ expect(blocked.busy).toBe(true);
+ store.tick(600_001);
+ const resumed = await runTransfer('t1', { store, steps, context, log: false });
+ expect(resumed.transfer.status).toBe('completed');
+ });
+
+ it('pauses at the deadline and releases the lease for the cron', async () => {
+ const store = memoryStore(newTransfer());
+ const { steps } = recordingSteps();
+ const paused = await runTransfer('t1', { store, steps, context, deadlineMs: -1, log: false });
+ expect(paused.paused).toBe(true);
+ expect(store.rows.get('t1').locked_until).toBeNull();
+ expect(store.rows.get('t1').step).toBe('pay_seller');
+ });
+
+ it('a completed transfer is never re-run', async () => {
+ const store = memoryStore({ ...newTransfer(), step: 'done', status: 'completed' });
+ const { steps, calls } = recordingSteps();
+ const run = await runTransfer('t1', { store, steps, context, log: false });
+ expect(calls).toEqual([]);
+ expect(run.busy).toBe(false);
+ });
+
+ it('nextStep ends at done and rejects unknown steps', () => {
+ expect(nextStep('pay_seller')).toBe('pay_fee');
+ expect(nextStep('finalize')).toBe('done');
+ expect(() => nextStep('nope')).toThrow();
+ });
+
+ it('transferView marks steps done, running and failed, and hides errors from strangers', () => {
+ const t = { ...newTransfer(), step: 'sweep_wallet', status: 'failed', last_error: 'sweep_wallet: rpc down' };
+ const v = transferView(t, { viewerId: 'buyer' });
+ expect(v.viewer_role).toBe('buyer');
+ expect(v.can_resume).toBe(true);
+ expect(v.steps.slice(0, 3).every((s) => s.state === 'done')).toBe(true);
+ expect(v.steps[3]).toMatchObject({ id: 'sweep_wallet', state: 'failed' });
+ expect(v.steps.at(-1).state).toBe('pending');
+ expect(v.seller_net.amount).toBe('4.875');
+ expect(transferView(t, { viewerId: 'stranger' }).last_error).toBeUndefined();
+ });
+});
+
+// ── Exactly-once legs ─────────────────────────────────────────────────────────
+
+function fakeConnection({ status = null, height = 100, landedByReference = null } = {}) {
+ return {
+ sent: 0,
+ async getSignatureStatuses() { return { value: [status] }; },
+ async getBlockHeight() { return height; },
+ async getSignaturesForAddress() { return landedByReference ? [{ signature: landedByReference, err: null }] : []; },
+ async sendRawTransaction() { this.sent++; return 'sig'; },
+ };
+}
+
+describe('exactly-once legs', () => {
+ it('a landed prior attempt is replayed, not resent', async () => {
+ const conn = fakeConnection({ status: { err: null, confirmationStatus: 'confirmed' } });
+ const r = await chain.sendLeg({
+ connection: conn, legId: 'payout:t1', prior: { signature: 'prior', lastValidBlockHeight: 200 },
+ signers: [], build: () => [], onPrepared: async () => { throw new Error('must not prepare'); },
+ });
+ expect(r).toEqual({ signature: 'prior', replayed: true });
+ expect(conn.sent).toBe(0);
+ });
+
+ it('an unknown prior attempt whose blockhash is still valid refuses to resend', async () => {
+ const conn = fakeConnection({ status: null, height: 150 });
+ await expect(chain.sendLeg({
+ connection: conn, legId: 'payout:t1', prior: { signature: 'prior', lastValidBlockHeight: 200 },
+ signers: [], build: () => [], onPrepared: async () => {},
+ })).rejects.toMatchObject({ code: 'leg_in_flight' });
+ expect(conn.sent).toBe(0);
+ });
+
+ it('reconcileLeg classifies landed, failed, in flight and expired', async () => {
+ const prior = { signature: 's', lastValidBlockHeight: 200 };
+ expect(await chain.reconcileLeg(fakeConnection({ status: { err: null, confirmationStatus: 'finalized' } }), prior)).toBe('landed');
+ expect(await chain.reconcileLeg(fakeConnection({ status: { err: { InstructionError: [0, 'x'] } } }), prior)).toBe('failed');
+ expect(await chain.reconcileLeg(fakeConnection({ status: { err: null, confirmationStatus: 'processed' } }), prior)).toBe('in_flight');
+ expect(await chain.reconcileLeg(fakeConnection({ status: null, height: 150 }), prior)).toBe('in_flight');
+ expect(await chain.reconcileLeg(fakeConnection({ status: null, height: 201 }), prior)).toBe('expired');
+ expect(await chain.reconcileLeg(fakeConnection(), null)).toBe('expired');
+ });
+
+ it('a leg whose record was lost is still found by its reference key', async () => {
+ const conn = fakeConnection({ landedByReference: 'found-by-ref' });
+ const r = await chain.sendLeg({
+ connection: conn, legId: 'refund:b1', prior: null, signers: [], build: () => [],
+ onPrepared: async () => { throw new Error('must not prepare'); },
+ });
+ expect(r).toEqual({ signature: 'found-by-ref', replayed: true });
+ });
+
+ it('leg references are deterministic per leg and distinct across legs', () => {
+ expect(chain.legReference('payout:t1').toBase58()).toBe(chain.legReference('payout:t1').toBase58());
+ expect(chain.legReference('payout:t1').toBase58()).not.toBe(chain.legReference('fee:t1').toBase58());
+ });
+});
+
+// ── Amounts and escrow derivation ─────────────────────────────────────────────
+
+describe('amounts and escrow', () => {
+ it('parses decimal amounts without float error and rejects junk', () => {
+ expect(chain.parseAmount('25', 6)).toBe(25_000_000n);
+ expect(chain.parseAmount('0.1', 6)).toBe(100_000n);
+ expect(chain.parseAmount(12.5, 6)).toBe(12_500_000n);
+ expect(() => chain.parseAmount('0', 6)).toThrow();
+ expect(() => chain.parseAmount('-1', 6)).toThrow();
+ expect(() => chain.parseAmount('1.0000001', 6)).toThrow();
+ expect(() => chain.parseAmount('1e3', 6)).toThrow();
+ });
+
+ it('formats atomics exactly', () => {
+ expect(chain.formatAtomics('4875000', 6)).toBe('4.875');
+ expect(chain.formatAtomics(1_000_000n, 6)).toBe('1');
+ expect(chain.formatAtomics('1', 6)).toBe('0.000001');
+ });
+
+ it('derives a stable escrow per listing and refuses to sign on a mismatch', async () => {
+ const prev = process.env.AGENT_MARKET_ESCROW_SECRET;
+ process.env.AGENT_MARKET_ESCROW_SECRET = 'test-escrow-secret-for-derivation';
+ try {
+ const a = chain.escrowAddressFor('listing-a');
+ expect(chain.escrowAddressFor('listing-a')).toBe(a);
+ expect(chain.escrowAddressFor('listing-b')).not.toBe(a);
+ const signed = await chain.withEscrowKeypair({ id: 'listing-a', escrow_address: a }, (kp) => kp.publicKey.toBase58());
+ expect(signed).toBe(a);
+ const other = Keypair.generate().publicKey.toBase58();
+ await expect(chain.withEscrowKeypair({ id: 'listing-a', escrow_address: other }, () => 'signed'))
+ .rejects.toMatchObject({ code: 'escrow_key_mismatch' });
+ } finally {
+ if (prev === undefined) delete process.env.AGENT_MARKET_ESCROW_SECRET;
+ else process.env.AGENT_MARKET_ESCROW_SECRET = prev;
+ }
+ });
+});
+
+// ── MCP financial gate ────────────────────────────────────────────────────────
+
+describe('marketplace MCP tools', () => {
+ const load = () => import('../api/_mcpagent/marketplace-tools.js');
+
+ it('every financial tool names its confirm flag and the preview tool', async () => {
+ const { marketplaceToolDefs } = await load();
+ const financial = marketplaceToolDefs.filter((t) => t.tier === 'financial');
+ expect(financial.map((t) => t.name).sort()).toEqual([
+ 'accept_marketplace_bid', 'buy_now', 'create_marketplace_listing',
+ 'delist_marketplace_listing', 'place_bid', 'withdraw_marketplace_bid',
+ ]);
+ for (const t of financial) {
+ expect(t.confirmFlag).toMatch(/^confirm_/);
+ expect(t.previewTool).toBe('preview_marketplace_action');
+ expect(t.inputSchema.properties[t.confirmFlag]).toBeTruthy();
+ expect(t.inputSchema.properties.preview_id).toBeTruthy();
+ }
+ for (const t of marketplaceToolDefs) {
+ expect(t.group).toBe('marketplace');
+ expect(['read', 'write', 'financial']).toContain(t.tier);
+ }
+ });
+
+ it('refuses a financial call without its confirm flag, naming the preview tool', async () => {
+ const { marketplaceToolDefs } = await load();
+ const accept = marketplaceToolDefs.find((t) => t.name === 'accept_marketplace_bid');
+ const auth = { userId: '00000000-0000-4000-8000-000000000001', scope: 'agents:write wallet:write', rateKey: 'test' };
+ const res = await accept.handler({ bid_id: '00000000-0000-4000-8000-000000000002' }, auth);
+ expect(res.isError).toBe(true);
+ expect(res.structuredContent).toMatchObject({
+ reason: 'confirmation_required', preview_tool: 'preview_marketplace_action', confirm_flag: 'confirm_accept',
+ });
+ });
+
+ it('refuses a confirmed call with no preview id', async () => {
+ const { marketplaceToolDefs } = await load();
+ const bid = marketplaceToolDefs.find((t) => t.name === 'place_bid');
+ const auth = { userId: '00000000-0000-4000-8000-000000000001', scope: 'wallet:write', rateKey: 'test' };
+ const res = await bid.handler({
+ listing_id: '00000000-0000-4000-8000-000000000003', amount_usdc: '5', funding_source: 'agent_wallet', confirm_bid: true,
+ }, auth);
+ expect(res.isError).toBe(true);
+ expect(res.structuredContent.reason).toBe('preview_required');
+ expect(res.content[0].text).toContain('preview_marketplace_action');
+ });
+
+ it('refuses a signed-out caller before anything else', async () => {
+ const { marketplaceToolDefs } = await load();
+ const bid = marketplaceToolDefs.find((t) => t.name === 'place_bid');
+ const res = await bid.handler({ listing_id: '00000000-0000-4000-8000-000000000003', amount_usdc: '5', funding_source: 'agent_wallet' }, { rateKey: 'anon' });
+ expect(res.structuredContent.reason).toBe('auth_required');
+ });
+});