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
feat(human-tasks): add the task state machine and the escrow settlement bookkeeping migration
nirholas50b40bf708bc
diff --git a/api/_lib/human-tasks/state.js b/api/_lib/human-tasks/state.jsnew file mode 100644index 000000000..9e89baba5--- /dev/null+++ b/api/_lib/human-tasks/state.js@@ -0,0 +1,125 @@+// The human-task state machine. Pure: no database, no chain. The service and+// the sweep move a task only along an edge listed here, and every write that+// changes status is a compare-and-set on the status it read, so two actors can+// never both win the same edge.+//+// funding -> open -> accepted -> submitted -> approved -> paid+// \ \ \-> disputed -> approved -> paid+// \ \ \-> cancelled (refund)+// \ \-> open (worker unclaimed before the deadline)+// \ \-> expired (deadline passed without proof: refund)+// \-> cancelled (poster cancelled before anyone accepted: refund)+// \-> expired (deadline passed unclaimed: refund)+// funding -> cancelled (the escrow transfer was refused or failed: nothing moved)++export const STATUSES = Object.freeze([+ 'funding', 'open', 'accepted', 'submitted', 'approved', 'disputed', 'paid', 'cancelled', 'expired',+]);++export const TRANSITIONS = Object.freeze({+ funding: Object.freeze(['open', 'cancelled']),+ open: Object.freeze(['accepted', 'cancelled', 'expired']),+ accepted: Object.freeze(['submitted', 'open', 'expired']),+ submitted: Object.freeze(['approved', 'disputed']),+ disputed: Object.freeze(['approved', 'cancelled']),+ approved: Object.freeze(['paid']),+ paid: Object.freeze([]),+ cancelled: Object.freeze([]),+ expired: Object.freeze([]),+});++export const TERMINAL = Object.freeze(new Set(['paid', 'cancelled', 'expired']));++export const STATUS_LABELS = Object.freeze({+ funding: 'Funding escrow',+ open: 'Open',+ accepted: 'In progress',+ submitted: 'Proof submitted',+ approved: 'Approved, paying out',+ disputed: 'In dispute',+ paid: 'Paid',+ cancelled: 'Cancelled',+ expired: 'Expired',+});++export class TransitionError extends Error {+ constructor(from, to) {+ super(`A task that is ${STATUS_LABELS[from] || from} cannot move to ${STATUS_LABELS[to] || to}.`);+ this.name = 'TransitionError';+ this.status = 409;+ this.code = 'invalid_transition';+ this.expose = true;+ this.from = from;+ this.to = to;+ }+}++export function canTransition(from, to) {+ return Boolean(TRANSITIONS[from]?.includes(to));+}++export function assertTransition(from, to) {+ if (!canTransition(from, to)) throw new TransitionError(from, to);+}++/** Was USDC ever locked in this task's escrow? */+export function wasFunded(task) {+ return Boolean(task?.funded_at || task?.escrow_signature);+}++/**+ * Does the escrow owe the poster its money back? Only a funded task that ended+ * without paying anyone (cancelled before acceptance, expired, or a dispute+ * decided for the poster).+ */+export function refundOwed(task) {+ return wasFunded(task) && (task.status === 'cancelled' || task.status === 'expired');+}++/**+ * The actions the poster (the agent's current owner) can take right now.+ * @param {object} task+ * @param {Date} [now]+ */+export function posterActions(task, now = new Date()) {+ const out = [];+ if (task.status === 'open') out.push('cancel');+ if (task.status === 'submitted') {+ out.push('approve');+ if (!task.review_due_at || new Date(task.review_due_at) > now) out.push('dispute');+ }+ if (canReview(task, 'poster')) out.push('review');+ return out;+}++/**+ * The actions the worker holding the live claim can take right now.+ * @param {object} task+ * @param {object|null} claim the viewer's claim on this task+ * @param {Date} [now]+ */+export function workerActions(task, claim, now = new Date()) {+ const out = [];+ if (!claim) return out;+ const beforeDeadline = new Date(task.deadline_at) > now;+ if (task.status === 'accepted' && claim.status === 'active') {+ if (beforeDeadline) out.push('submit');+ out.push('unclaim');+ }+ if (task.status === 'disputed' && claim.status === 'submitted') out.push('respond');+ if (canReview(task, 'worker')) out.push('review');+ return out;+}++/** A task can be rated once it paid out, or once a dispute was decided. */+export function canReview(task, role) {+ if (!task?.accepted_claim_id) return false;+ if (task.status === 'paid') return !task.reviewed?.[role];+ if (task.status === 'cancelled' && task.cancel_reason === 'dispute_resolved_for_poster') return !task.reviewed?.[role];+ return false;+}++/** Can someone browsing the board accept this task right now? */+export function isAcceptable(task, now = new Date()) {+ return task.status === 'open' && new Date(task.deadline_at) > now;+}diff --git a/api/_lib/migrations/20260925200000_human_tasks_settlement.sql b/api/_lib/migrations/20260925200000_human_tasks_settlement.sqlnew file mode 100644index 000000000..03ab15755--- /dev/null+++ b/api/_lib/migrations/20260925200000_human_tasks_settlement.sql@@ -0,0 +1,49 @@+-- Human tasks: settlement bookkeeping the first migration did not carry.+-- Apply: npm run db:status, then npm run db:migrate. Idempotent and additive.+--+-- human_tasks.escrow_closed_at / escrow_close_signature+-- When a finished task's empty escrow token account was closed and its+-- rent returned to the poster agent's wallet (the agent paid that rent+-- when it funded the escrow). The sweep closes an escrow once, after+-- every leg it owed (payout, fee or refund) has landed.+--+-- human_task_disputes.resolve_preview_*+-- The preview an admin must quote back to resolve a dispute. A+-- resolution moves escrowed USDC (to the worker, or back to the poster+-- agent), so it follows the same preview then confirm rule as every+-- other fund-moving action: the preview names recipient, amount, token+-- and chain, and expires after ten minutes.+--+-- human_task_uploads.bytes+-- The verified object size, read back from storage when the proof is+-- submitted, so a submission records what was actually stored.++begin;++alter table human_tasks add column if not exists escrow_closed_at timestamptz;+alter table human_tasks add column if not exists escrow_close_signature text;++create index if not exists human_tasks_escrow_close_due+ on human_tasks (updated_at)+ where escrow_closed_at is null and status in ('paid', 'cancelled', 'expired');++alter table human_task_disputes add column if not exists resolve_preview_id text;+alter table human_task_disputes add column if not exists resolve_preview_outcome text;+alter table human_task_disputes add column if not exists resolve_preview_by uuid;+alter table human_task_disputes add column if not exists resolve_preview_expires_at timestamptz;++do $$+begin+ if not exists (select 1 from pg_constraint where conname = 'human_task_disputes_outcome_chk') then+ alter table human_task_disputes add constraint human_task_disputes_outcome_chk+ check (outcome is null or outcome in ('worker', 'poster'));+ end if;+ if not exists (select 1 from pg_constraint where conname = 'human_task_disputes_status_chk') then+ alter table human_task_disputes add constraint human_task_disputes_status_chk+ check (status in ('open', 'resolved'));+ end if;+end $$;++alter table human_task_uploads add column if not exists bytes integer;++commit;