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.

14.0 KB
Raw Blame
// Settlement for the Agent Labor Market (Moonshot 01) — where the $THREE actually
// moves. Shared by the POST /api/labor/settle endpoint and the autonomy driver so
// there is exactly ONE place that verifies a deliverable and releases escrow.
//
// Flow (idempotent by job settle_key — a retry never double-pays):
//   1. Claim the settle atomically (settle_key). A second caller no-ops.
//   2. A neutral verifier scores the deliverable against the spec.
//   3. On a PASS: release escrow on-chain — worker payout + skill-author royalty +
//      any unspent reward refunded to the poster — then record a real agent-
//      invocation receipt (worker invoked the poster's skill) and mark settled.
//   4. On a FAIL: refund the poster in full and mark the job failed (bad work
//      counts against the worker; an inability to perform is recorded as 'refunded'
//      so a network fault never tarnishes a worker's reputation).

import { sql } from './db.js';
import {
	settlementSplit, defaultRoyaltyBps, claimSettle, recordVerdict,
	markJobSettled, markJobFailed, setBountyStatus, releaseSettleClaim, atomicsToThree, _toBig as toBig,
} from './agent-labor.js';
import {
	verifyDeliverable, resolveSkillAuthorPayout, emitReasoning,
	autoBidForBounty, autoAwardIfReady, performJob,
} from './labor-match.js';
import { getBounty, getJobByBounty } from './agent-labor.js';
import { payFromEscrow, ensureEscrowGas } from './labor-escrow.js';
import { recoverSolanaAgentKeypair } from './agent-wallet.js';
import { recordInvocationReceipt } from './agent-invocation-onchain.js';
import { recordCustodyEvent } from './agent-trade-guards.js';
import { recordFromActionLog } from './skill-candidates.js';

async function loadAgentWallet(agentId) {
	const [row] = await sql`
		SELECT id, user_id, name, meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;
	return row || null;
}

/**
 * Verify + settle a delivered job. Returns a result describing the on-chain
 * outcome. Safe to call more than once for the same job: only the first call that
 * wins the settle_key claim moves funds.
 *
 * @param {{ job: object, bounty: object, verdict?: object }} args
 */
export async function runSettlement({ job, bounty, verdict: providedVerdict = null }) {
	if (!job || !bounty) throw new Error('runSettlement: job and bounty required');

	const settleKey = `settle:${job.id}`;
	const claimed = await claimSettle(job.id, settleKey);
	if (!claimed) {
		// Already owned by a prior settle. Return the current terminal state.
		const [cur] = await sql`SELECT * FROM agent_jobs WHERE id = ${job.id}`;
		return { idempotent: true, status: cur?.status || job.status, job: cur || job };
	}

	// Both terminal paths below release SOL-paying transfers from escrow (payout or
	// refund). Top the escrow's gas buffer up first so a settlement never stalls on a
	// drained fee balance. Best-effort — never throws.
	await ensureEscrowGas().catch((e) => console.warn('[labor-settle] gas ensure failed', e?.message));

	// ── Verify ───────────────────────────────────────────────────────────────
	const verdict = providedVerdict || (await verifyDeliverable({ bounty, deliverable: claimed.deliverable }));
	await recordVerdict(job.id, verdict);

	const reward = toBig(bounty.reward_atomics);
	const awarded = toBig(job.price_atomics);

	// ── Failure path: refund poster (no release) ──────────────────────────────
	// A verifier rejection is the worker's fault → mark the job 'failed' (counts
	// against reputation). A moderator-administered refund is NOT the worker's
	// fault → mark it 'refunded' so a dispute resolution never tarnishes a worker.
	if (!verdict.pass) {
		const moderated = !!verdict.moderator || !!verdict.neutral;
		const failStatus = moderated ? 'refunded' : 'failed';
		let refundSig = null;
		const refundError = null;
		try {
			const poster = await loadAgentWallet(bounty.poster_agent_id);
			if (poster?.meta?.solana_address) {
				refundSig = await payFromEscrow({ toAddress: poster.meta.solana_address, amountAtomics: reward });
			}
		} catch (e) {
			// The refund did not land, so the reward is still in escrow. Marking the
			// job failed now would strand it; hand the claim back and let the caller
			// retry instead.
			console.error('[labor-settle] refund failed', e?.message);
			await releaseSettleClaim(job.id);
			throw e;
		}
		const reason = moderated ? `refund: ${verdict.reason}` : `verification failed: ${verdict.reason}`;
		await markJobFailed(job.id, { reason, refundSig, status: failStatus });
		await setBountyStatus(bounty.id, failStatus, { refundSig });
		emitReasoning({
			agentId: bounty.poster_agent_id, kind: moderated ? 'labor.moderator_refund' : 'labor.refund',
			summary: moderated ? `Moderator refunded "${bounty.title}"` : `Refunded "${bounty.title}" — work rejected`,
			detail: { bounty_id: bounty.id, job_id: job.id, verdict, refund_sig: refundSig, refund_error: refundError },
		});
		return { settled: false, status: failStatus, verdict, refund_sig: refundSig, refund_error: refundError };
	}

	// ── Pass path: resolve royalty + split ───────────────────────────────────
	const author = await resolveSkillAuthorPayout(bounty.required_skill, { excludeAgentId: job.worker_agent_id });
	const split = settlementSplit({
		rewardAtomics: reward, awardedAtomics: awarded,
		royaltyBps: defaultRoyaltyBps(), hasAuthor: !!author,
	});

	const worker = await loadAgentWallet(job.worker_agent_id);
	const poster = await loadAgentWallet(bounty.poster_agent_id);
	if (!worker?.meta?.solana_address) {
		// Cannot pay a worker with no wallet — refund and fail without penalizing the
		// worker's reputation (provisioning issue, not bad work).
		let refundSig = null;
		try {
			if (poster?.meta?.solana_address) refundSig = await payFromEscrow({ toAddress: poster.meta.solana_address, amountAtomics: reward });
		} catch (e) {
			console.error('[labor-settle] refund (no worker wallet) failed', e?.message);
			await releaseSettleClaim(job.id);
			throw e;
		}
		await markJobFailed(job.id, { reason: 'worker has no wallet to receive payout', refundSig, status: 'refunded' });
		await setBountyStatus(bounty.id, 'refunded', { refundSig });
		return { settled: false, status: 'refunded', reason: 'worker_no_wallet', refund_sig: refundSig };
	}

	// ── Release escrow on-chain (worker payout is the critical leg) ───────────
	let settlementSig;
	try {
		settlementSig = await payFromEscrow({ toAddress: worker.meta.solana_address, amountAtomics: split.workerAtomics });
	} catch (e) {
		// The transfer did not land (payFromEscrow throws on a revert), so nothing
		// moved. Free the claim: left set, every later settle would see "already
		// owned" and no-op, stranding the job and the escrow behind it.
		await releaseSettleClaim(job.id);
		throw e;
	}

	// Royalty + poster refund are best-effort: a failure here leaves the residue in
	// escrow (sweepable) but must not undo the worker's confirmed payout.
	let royaltySig = null;
	if (author && split.royaltyAtomics > 0n) {
		try {
			royaltySig = await payFromEscrow({ toAddress: author.payoutAddress, amountAtomics: split.royaltyAtomics });
		} catch (e) { console.error('[labor-settle] royalty payout failed', e?.message); }
	}
	let posterRefundSig = null;
	if (split.posterRefundAtomics > 0n && poster?.meta?.solana_address) {
		try {
			posterRefundSig = await payFromEscrow({ toAddress: poster.meta.solana_address, amountAtomics: split.posterRefundAtomics });
		} catch (e) { console.error('[labor-settle] poster refund (auction surplus) failed', e?.message); }
	}

	// ── Record the real on-chain invocation receipt (non-fatal) ──────────────
	let invocationSig = null;
	let invocationError = null;
	try {
		if (!worker.meta?.encrypted_solana_secret) throw new Error('worker wallet not recoverable for receipt');
		if (!poster?.meta?.solana_address) throw new Error('poster has no Solana authority to record against');
		const invokerKeypair = await recoverSolanaAgentKeypair(worker.meta.encrypted_solana_secret, {
			agentId: job.worker_agent_id, userId: worker.user_id, reason: 'labor_invocation_receipt',
		});
		const receipt = await recordInvocationReceipt({
			invokerKeypair,
			targetAuthority: poster.meta.solana_address,
			skillName: bounty.required_skill || bounty.title,
			parameters: JSON.stringify({ bounty: bounty.id, job: job.id, three: atomicsToThree(split.workerAtomics) }).slice(0, 480),
		});
		invocationSig = receipt.signature;
	} catch (e) {
		invocationError = e?.message || String(e);
		console.error('[labor-settle] invocation receipt failed', invocationError);
	}

	await markJobSettled(job.id, {
		settlementSig, royaltySig, invocationSig,
		royaltyAtomics: split.royaltyAtomics, workerPayoutAtomics: split.workerAtomics,
		royaltyAuthorId: author?.authorAgentId || null,
		refundSig: posterRefundSig,
	});
	await setBountyStatus(bounty.id, 'settled');

	// A passed, settled job is a verified success: keep the procedure as a
	// skill candidate the worker's owner can review (never installs by itself).
	recordFromActionLog({
		agentId: job.worker_agent_id, userId: worker.user_id, signal: 'labor_escrow_passed',
		sourceRef: `labor:${job.id}`, goal: bounty.title, verdict,
		since: job.created_at ? new Date(job.created_at).toISOString() : undefined,
		outcome: { bounty_id: bounty.id, job_id: job.id },
	});

	// Cross-wire: surface the worker's income in the custody ledger so it shows up
	// on the wallet HUD / live money pulse as real earnings.
	recordCustodyEvent({
		agentId: job.worker_agent_id, userId: null, eventType: 'tip', category: null,
		network: 'mainnet', asset: 'THREE', amountRaw: String(split.workerAtomics),
		signature: settlementSig, status: 'confirmed',
		meta: { source: 'labor_market', bounty_id: bounty.id, job_id: job.id, skill: bounty.required_skill || null },
	}).catch((e) => console.error('[labor-settle] worker income record failed', e?.message));

	emitReasoning({
		agentId: job.worker_agent_id, kind: 'labor.settle',
		summary: `Settled "${bounty.title}" — earned ${atomicsToThree(split.workerAtomics)} $THREE`,
		detail: {
			bounty_id: bounty.id, job_id: job.id, settlement_sig: settlementSig,
			worker_atomics: String(split.workerAtomics), royalty_atomics: String(split.royaltyAtomics),
			royalty_sig: royaltySig, invocation_sig: invocationSig,
		},
	});

	return {
		settled: true, status: 'settled', verdict,
		settlement_sig: settlementSig, royalty_sig: royaltySig,
		poster_refund_sig: posterRefundSig, invocation_sig: invocationSig, invocation_error: invocationError,
		worker_payout_atomics: String(split.workerAtomics),
		worker_payout_three: atomicsToThree(split.workerAtomics),
		royalty_atomics: String(split.royaltyAtomics),
		royalty_three: atomicsToThree(split.royaltyAtomics),
		explorer: settlementSig ? `https://solscan.io/tx/${settlementSig}` : null,
	};
}

/**
 * Drive a bounty as far as its participants' policies allow, autonomously: collect
 * auto-bids, auto-award if the poster opted in, then have an autonomous worker
 * perform the task and settle it on-chain. Each step is guarded — a failure in one
 * never throws out of the driver (the bounty just stops at a resumable state that
 * the manual endpoints or the /tick cron can pick up). Safe to call repeatedly.
 *
 * `settled` is the job's status after the attempt; `settledNow` is true only when
 * THIS call won the settle claim and released escrow. They differ when another
 * caller (a concurrent /settle, an earlier tick) already settled the job: the
 * status is 'settled' but no money moved here, so a counter that reports work
 * done must read `settledNow`.
 *
 * @returns {Promise<{ bids: number, awarded: boolean, settled: string|null, settledNow: boolean }>}
 */
export async function runAutopilot(bountyId) {
	const out = { bids: 0, awarded: false, settled: null, settledNow: false };
	try {
		let bounty = await getBounty(bountyId);
		if (!bounty) return out;

		if (bounty.status === 'open') {
			out.bids = await autoBidForBounty(bounty).catch((e) => {
				console.warn('[labor-autopilot] auto-bid failed', e?.message);
				return 0;
			});
			const awarded = await autoAwardIfReady(bountyId).catch((e) => {
				console.warn('[labor-autopilot] auto-award failed', e?.message);
				return null;
			});
			if (!awarded) return out;
			out.awarded = true;
			bounty = awarded.bounty || (await getBounty(bountyId));
		}

		// Drive an awarded job to delivery + settlement only when the worker is
		// autonomous (its policy enabled it to bid). A manual worker delivers via the
		// /deliver endpoint instead, so we never act on their behalf without consent.
		if (bounty?.status === 'working') {
			const job = await getJobByBounty(bountyId);
			if (!job) return out;
			const { isAutonomousWorker } = await import('./agent-labor.js')
				.then((m) => m.getLaborPolicy(job.worker_agent_id))
				.then((p) => ({ isAutonomousWorker: !!p?.worker_enabled }))
				.catch(() => ({ isAutonomousWorker: false }));
			if (!isAutonomousWorker) return out;

			let working = job;
			if (job.status === 'working') {
				const performed = await performJob({ job, bounty, workerUserId: job.worker_user_id }).catch((e) => {
					console.warn('[labor-autopilot] perform failed', e?.message);
					return null;
				});
				if (!performed) return out;
				working = performed.job;
			}
			if (working.status === 'delivered' || working.status === 'verifying') {
				// Delivery enters independent evaluation; the payout lands when the
				// verdict's dispute window closes, so nothing settles inside this call.
				const { intakeDelivery } = await import('./labor-evaluation.js');
				const entered = await intakeDelivery({ bounty, job: working }).catch((e) => {
					console.error('[labor-autopilot] evaluation intake failed', e?.message);
					return null;
				});
				out.settled = entered?.state || null;
			}
		}
	} catch (e) {
		console.error('[labor-autopilot] driver error', e?.message);
	}
	return out;
}