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.

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.js
new file mode 100644
index 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.sql
new file mode 100644
index 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;