Task offer API — agents post work offers with locked XLM reward

[leocagli]

Problem

Agents can only receive tasks from humans via the orchestrator. There is no way for an agent to offload work to another agent and track the result.

API design

POST /api/task-offers
{ "requiredCapability": "run-inference", "payload": {...}, "reward": "0.05 XLM", "deadline": 1750000000 }
? { "offerId": "off_abc", "escrowTx": "..." }

GET /api/task-offers?cap=run-inference   � list open offers
GET /api/task-offers/:id                 � single offer detail
DELETE /api/task-offers/:id              � cancel (refunds escrow, poster only)

Posting an offer locks the reward in the existing Soroban escrow contract. The deadline is enforced server-side: expired unclaimed offers auto-refund.

Schema

interface TaskOffer {
  offerId: string
  postedBy: string           // agentId
  requiredCapability: string
  payload: unknown
  reward: { amount: string; asset: 'XLM' | 'USDC' }
  deadline: number
  status: 'open' | 'claimed' | 'delivered' | 'accepted' | 'disputed' | 'expired'
}

Files to create

• app/api/task-offers/route.ts
• app/api/task-offers/[id]/route.ts
• lib/task-market/offers.ts

Files to touch

• lib/task-offers/store.ts (new)
• lib/task-offers/escrow.ts (new: bloqueo y liberación del reward)
• app/api/task-offers/route.ts (new: POST y GET con filtro por capability)
• __tests__/task-offers/escrow.test.ts (new)
• README.md: documentar el ciclo de vida completo

Relación con #114

Esta issue crea las ofertas y bloquea el reward. #114 las reclama, entrega y libera. Definí acá el estado y las transiciones válidas; #114 las consume. Si las dos issues inventan su propia máquina de estados, se van a contradecir.

Out of scope

• Claim, deliver, accept y dispute. Todo eso es Task offer lifecycle — claim, deliver, accept and dispute endpoints #114.
• Matching automático de ofertas con agentes.
• Ofertas recurrentes.

Acceptance criteria

• Crear una oferta bloquea el reward antes de publicarla. Una oferta visible siempre tiene fondos respaldándola.
• Sin saldo suficiente, la oferta no se crea y no queda nada a medias
• Los estados válidos y sus transiciones están declarados en un solo lugar
• Una oferta vencida no puede reclamarse, y su reward vuelve al emisor
• El filtro por capability no expone ofertas de otros estados
• Dos requests concurrentes con el mismo idempotency key crean una sola oferta
• Los montos se manejan como enteros en la unidad mínima

Tests

Al menos 5: creación bloquea fondos, saldo insuficiente aborta limpio, una oferta vencida libera el reward, doble POST idempotente crea una, y una transición inválida se rechaza.

Seguridad

Acá hay dinero bloqueado. El invariante que no se puede romper: la suma de rewards bloqueados nunca supera lo que realmente hay depositado. Todo camino que cree una oferta sin bloquear, o que libere dos veces, rompe eso.

Evidencia visual (OBLIGATORIA)

El PR tiene que incluir:

1. Creación de una oferta con el reward bloqueado, con el balance antes y después
2. Captura del intento con saldo insuficiente
3. Salida del test de vencimiento devolviendo el reward

Sin las tres, el PR no se evalúa.

Estimación

Complejidad: alta. Unos 5 archivos, ~8 h.

[leocagli]

Self-contained API layer. The escrow integration reuses the existing Soroban escrow client in lib/protocols/escrow.ts — no contract work needed here, just the REST endpoints and DB schema.

[wuleilonghundao-svg]

Hi! I inspected this against the current task-offer follow-ups and saw the maintainer note that #113 should be a self-contained API layer reusing lib/protocols/escrow.ts, with no contract work needed.

I also noticed #156 covers the smaller GET/POST /api/task-offers board-wiring task and is already approved/assigned to @ekwe7, so I do not want to duplicate that narrower scope.

Would you still want a separate PR for #113 focused on the broader API surface and schema, e.g.:

• lib/task-market/offers.ts with the full TaskOffer model, expiry handling, and storage boundary
• GET/POST /api/task-offers
• GET/DELETE /api/task-offers/[id]
• integration through the existing escrow client in lib/protocols/escrow.ts
• focused endpoint tests for create/list/detail/delete/expiry behavior

If #156 is intended to cover the whole backend API surface, I will leave this alone. If #113 is still open as the broader task-offer API work, I can take that route and keep the PR scoped to this issue.

[stmr]

Hi maintainers — I can take #113 if it is still intended as the broader task-offer API beyond assigned #156. I would keep the PR scoped to lib/task-market/offers.ts, GET/POST /api/task-offers, GET/DELETE /api/task-offers/[id], reuse existing escrow boundaries where present, add endpoint tests, and avoid contract work unless requested. Please confirm #113 is still open/assignable under GrantFox before I start.