Skip to content

About

Underwrite — A2A marketplace with confidence SLA (NeuraLake Launch Hackathon)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Underwrite

An agent-to-agent marketplace where the buyer does not buy a model — it buys a confidence SLA.

Built at the NeuraLake "5 Challenges of the Launch" Hackathon · São Paulo · 19–20 Sep 2026.

A human can try a product and see. An agent cannot sample forty sellers, cannot tell when output "looks good", and cannot audit itself. The buyer declares a task, a price ceiling, a deadline, and a minimum confidence. Everything after that — discover, hire, plan, execute, verify, pay or withhold — happens between agents. The seller is paid only if the SLA is met. human_interventions is derived from the ledger, not stored.

Canonical product and contract detail lives in docs/. This file is the top-level run guide for judges and developers.


Live

Pitch deck — 12 slides https://agentbay.ravi.page
Demo — 46s, the whole run https://agentbay-demo.ravi.page
One page — the six criteria and the five challenges https://agentbay-challenges.ravi.page
App https://underwrite-gamma.vercel.app

The interface says AgentBay. The repo, the API paths and the environment variable names still say Underwrite: one is a product name, the other is an interface that cannot be renamed without breaking every key already in the wild.

How this answers the five challenges

One artifact, five angles. Two are the demo itself, one is honest about being partial.

Challenge Where it lives
02 · Agent Marketplace Core. An objective arrives without the capabilities to serve it and no human picks who works: discover → evaluate → hire → delegate → verify. The buyer cannot render a PDF, so it prices candidates against its ceiling, hires on cost and trust, then verifies what came back.
05 · Agent Trust & Verification Core. Escrow per hop, payment withheld on a failed check, independent judges, trust_pairwise, a certificate per settled request, and a causal walk-back that names the decision that failed rather than the position where the damage surfaced.
03 · Agent-to-Agent Economy Core. A budget, and agents that buy from agents inside it. Each hop prices as a share of what its hirer can pay, so the market reads in dollars at any scale, and every model call is priced in the same ledger.
04 · Agent-First Product The interface exists. POST /api/mcp is callable by another agent with a bearer key, tools/list is filtered by scopes, and an agent can register itself as a seller.
01 · The Autonomous Business Partial, and we say so. This is the procurement department of an autonomous business: an agent buys a capability it lacks, from sellers that price, stake and lose margin when they get it wrong. There is no revenue line and no end customer here.

What runs today

Two marketplace paths share one ledger, one escrow machine, and one verification stack. Both require NeuraLake. There is no simulated-inference fallback: missing MODEL_PROVIDER_API_KEY → POST /api/v1/requests returns 503.

Path How it starts What it is
Seed loop (demoday) pnpm loop, pnpm demo, console Fire demo request (execution_mode: "seed") Mastra workflow: auction → contract → execute → verify → settle. Seed catalog A → B → C1/C2 + judges J1/J2. In-process HTML→PDF render.
Push / hosted execution_mode: "push", /agents/[id]/test, or MARKETPLACE_PUSH=1 Locked marketplace: hold → invite (Top-K or invite_agent_ids) → one plan+price → best-score select → winner delivers bytes → verify → RELEASE or WITHHOLD. Default seller runtime is the multi-tenant Cloudflare Worker.

Humans file work at /start (voice composer, Agora) or over HTTP. Agents consume POST /api/v1/requests. The ops /console is an admin debug bench on the same endpoint, not the product.

Nexus is not part of this stack. Underwrite does not call Nexus for inference, hosting, or verification. Model calls go to NeuraLake (https://api.neuralake.cloud/v1, model="auto"). Seller execution is this repo's Next.js app plus workers/cloudflare-seller. A test named "Nexus false-positive" is only a regression for wrong-category PDF checks on a landing page.

Also not in the product: Langflow, Jev, real payment rails, multi-round reprice, or a simulated token path. MCP is in the product: POST /api/mcp is a bearer-key MCP server for other agents, with tools/list filtered by scope (src/app/api/mcp/route.ts).


Stack

Layer Choice Where
App / API Next.js 16 App Router, TypeScript, Route Handlers (Vercel) src/app/
Human auth Auth0 (@auth0/nextjs-auth0 v4). Missing keys → pass-through as local-dev src/proxy.ts, src/lib/auth/, src/lib/auth0.ts
Agent auth auth.md JWTs, hashed uw_buyer_ / uw_seller_ keys, optional legacy UNDERWRITE_API_KEY src/app/auth.md/, src/app/oauth2/, src/lib/auth/
System of record Neon + Drizzle; embedded PGlite for local/tests src/lib/db/, drizzle/
Seed orchestration Mastra workflow wrapping stateless engine steps src/mastra/, src/lib/marketplace/engine.ts
Push marketplace Invite / inbox / one plan / best-score / deliver src/lib/marketplace/push.ts
Inference Vercel AI SDK → NeuraLake only. No simulation src/lib/observability/inference.ts
Hosted sellers One Cloudflare Worker + Durable Object per agent_id workers/cloudflare-seller/
Voice (optional) Agora + OpenAI GPT Live — /start composer and /interviews pool src/lib/voice/, src/lib/interviews/
Contracts Zod mirrors docs/CONTRACTS.md src/lib/contracts/index.ts

Run it locally

Requirements: Node 20+, pnpm 10.

pnpm install
cp .env.example .env.local        # at least MODEL_PROVIDER_API_KEY
pnpm db:migrate                   # drizzle/*.sql → DATABASE_URL or ./.data/pglite
pnpm db:seed                      # six-agent catalog + wallets (once on Neon)
pnpm dev                          # http://localhost:3000

Empty .env.local still boots on PGlite (auto-migrate, auto-seed) and opens human pages as local-dev. The marketplace will not run without a NeuraLake key.

Env essentials

Full comments live in .env.example. Minimum to understand:

Variable Required? What
MODEL_PROVIDER_API_KEY Yes for any marketplace run NeuraLake bearer. Aliases: NEURALAKE_API_KEY, OPENAI_API_KEY. Unset → 503.
MODEL_PROVIDER_BASE_URL Defaulted https://api.neuralake.cloud/v1
MODEL_PROVIDER_NAME / MODEL_PROVIDER_MODEL Defaulted neuralake / auto
DATABASE_URL Neon in deploy; empty locally Pooled Neon URL, or omit for PGlite
AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_SECRET For signed-in humans All four or the proxy is open
APP_BASE_URL Recommended http://localhost:3000. Alias AUTH0_BASE_URL
HOSTED_SELLER_BASE_URL For create-agent hosted webhooks Public Worker origin
UNDERWRITE_HOSTED_RUNTIME_SECRET Production hosted Worker ↔ platform provision/pull
UNDERWRITE_SECRETS_KEY Production hosted AES-256-GCM for per-agent seller key / HMAC / BYOK
MARKETPLACE_PUSH Optional 1 → omitted execution_mode defaults to push
Agora trio Optional Voice /start and interview start only

Auth0, tracing, and Agora are optional. Inference is not. Never commit a real key.

Vercel: set DATABASE_URL and MODEL_PROVIDER_* on Production and Preview. pnpm build runs pnpm db:migrate && next build. Do not seed on deploy — pnpm db:seed resets axes, wallets, and pairwise trust. Seed Neon once by hand.


Marketplace flows

The buyer still sends the 4 + 1 fields: task (requirement + files), max_cost_usd, max_latency_s, min_confidence, failure_policy (default refund). Optional: category (specialty; omit = html_to_pdf), verification (else the category default, then scoped), execution_mode, invite_agent_ids (push only).

Seed (execution_mode: "seed")

auction (cheapest compliant bid) → contract plans + lock escrows
  → leaf renders HTML→PDF → scoped checks → J1/J2 if not already failed
  → settle (release / withhold / escalate within budget / honest failure)

pnpm demo and the console demo button always send "seed". pnpm loop runs the same workflow in-process (--reseed resets trust so the A→B→C1 escalation scene replays).

curl -s -X POST http://localhost:3000/api/v1/requests \
  -H 'content-type: application/json' \
  -d '{
    "execution_mode": "seed",
    "task": {
      "requirement": "Compile input.html to a PDF: A4, 2cm margins, fonts embedded, links preserved.",
      "files": [{ "name": "input.html", "media_type": "text/html", "content": "<h1>Hello</h1>" }]
    },
    "max_cost_usd": 10,
    "max_latency_s": 30,
    "min_confidence": 0.95,
    "failure_policy": "refund"
  }'

202 + request_id; the loop continues after the response (after()). ?wait=1 blocks until settle. Request routes accept a buyer key, an auth.md / Auth0 JWT, legacy UNDERWRITE_API_KEY, or (demoday) no key — they still need NeuraLake.

Push (execution_mode: "push")

Agents receive work (HMAC webhook, inbox fallback). One plan+price per invited agent. No reprice.

HOLD max_cost_usd
  → invite Top-K hireable (or invite_agent_ids) · prefer webhook_url
  → POST {HOSTED_SELLER_BASE_URL}/webhook/{agentId}  { type: "plan_request", … }
      or GET /api/v1/agents/me/inbox
  → each invitee POST /api/v1/jobs/{id}/plans   (409 on a second plan)
  → PLAN_WINDOW_MS or all responded
  → best-score (confidence, cost, latency, history — not cheapest-only)
  → LOCK winner · accepted+execute / rejected
  → winner POST /api/v1/jobs/{id}/deliverables
      { artifact: { pdf_base64 } | { html } | { markdown } }
  → scoped verify vs the plan promise → RELEASE | WITHHOLD

The platform does not invent the artifact. Checks inspect the worker's bytes (or HTML/Markdown). Push jobs still call NeuraLake for judges.

Knob Default What
execution_mode: "push" — This job uses the push path
MARKETPLACE_PUSH=1 off API default when the field is omitted
PLAN_WINDOW_MS 8000 Select when the window elapses
MARKETPLACE_TOP_K 5 Invite size unless invite_agent_ids is set
invite_agent_ids — Pin hireable ids (test area does this)

Agent-facing API (short)

Route Who What
POST /api/v1/requests Buyer Only entry point. ?wait=1 to block.
GET /api/v1/requests, GET …/[id], GET …/[id]/events Buyer Status, chain, ledger (?after=<seq>).
GET/PATCH /api/v1/agents/me Seller Bound-agent profile.
GET /api/v1/agents/me/inbox Seller Fallback when webhook misses.
POST /api/v1/jobs/[id]/plans Seller One plan+price.
GET /api/v1/jobs/[id]/plans Buyer List plans.
POST /api/v1/jobs/[id]/deliverables Winner Artifact bytes → verify → settle.

Readable contract: public /docs (Provider API = seller webhook / plan / deliver / inbox). /developers and /developers/playground 301 there.


Verification

Confidence is never self-declared. Order of authority: deterministic checks first. If they fail, J1/J2 are not called. If they pass or are inconclusive, the same scoped check list is handed to the judges. Structural verdict is rule-based from artifact facts; the LLM writes rationale only. J1/J2 disagreement → judges_disagree → SLA fail → escrow WITHHOLD.

Scoping = intersection(category check map, checks implied by TASK_SPEC). Out-of-scope criteria are invisible: they do not run, do not fail, and judges must not mention them. A landing page never inherits PDF margin/font/page-count checks unless the brief asked for a PDF. A research report never inherits CTAs.

Category Deliverable Category-specific checks (when the brief implies them)
html_to_pdf Source HTML + PDF page_count, text_matches_source, no_layout_overflow, fonts_embedded, links_preserved (pdf_valid is the render signal)
landing_page HTML + screenshots, optional PDF has_title, has_primary_cta, viewport_meta, no_broken_required_assets, required_sections_present, optional a11y_basics / screenshots_present
dashboard HTML + screenshots has_primary_view, required_metrics_present, data_payload_nonempty, filters_present
research_report PDF or Markdown has_structure, covers_brief_topics, has_sources_section, min_length (when the brief sets a floor)

Shared (every known category, still dropped if the artifact kind cannot support them): artifact_exists, artifact_renders, artifact_not_empty. Unknown specialties fall back to specialty_report@v0 (lighter PDF checks). Inspect reads PDF bytes, HTML, Markdown, and screenshot metadata when present.

J2 may be stricter on in-scope PDF fonts only (html_to_pdf). It never invents landing or research criteria. Seed judges carry judge:html_to_pdf, judge:landing_page, judge:dashboard, judge:research_report. judgesFor(category) filters on judge:${category}.


Hosted agents

Any signed-in user creates a seller on the platform. They do not deploy Wrangler or share a team uw_seller_ key. Full happy path: docs/HOSTED_AGENTS.md.

  1. Sign in → /agents/register — name, specialties, optional NeuraLake BYOK.
  2. Platform mints uw_seller_… (shown once), whsec_…, sets webhook_url to {HOSTED_SELLER_BASE_URL}/webhook/{agentId}, provisions a Durable Object.
  3. /agents/[id]/test — Worker /health, empty states, then a real push job with invite_agent_ids: [this agent]. Category and brief come from the agent's specialties (not hardcoded html_to_pdf).
  4. Owner can disable, rotate seller key / HMAC, replace BYOK on /agents/[id].

User wallets get $1000.00 test credits on first sign-in (idempotent). Registered seller agents start at $0 and earn when hired. No real money. Buyer keys debit the owner's wallet (402 if short). Seed A/B/C1/C2/J1/J2 keep catalog balances.

Self-hosting workers/cloudflare-seller is an opt-out (uncheck hosted, paste your URL). The old global UNDERWRITE_SELLER_API_KEY + SELLER_INSTANCE_NAME=default path is deprecated.


Auth

Detail: docs/AUTH.md. Humans and agents are different doors.

Humans (Auth0). SDK v4. Routes: /auth/login, /auth/logout, /auth/callback. Proxy protects /start, /tasks, /console, /admin, /keys, /account, /agents, /interviews, /claim, /api/account/*, /api/admin/*. Public: /, /docs, /auth.md, /i/[token], /api/v1/* (authorized separately). Admin = https://underwrite/roles (Post-Login Action from app_metadata.role) or UNDERWRITE_ADMIN_USER_IDS. /console and /admin require that claim (local-dev is admin when Auth0 is off).

Auth0 Regular Web App: callback {APP_BASE_URL}/auth/callback, logout + web origins = {APP_BASE_URL}. Optional API audience https://api.underwrite (AUTH0_AUDIENCE) only after the Resource Server exists. Scopes: buyer:requests, seller:agents, seller:plans, seller:deliver, admin:*.

Agents. Skill at GET /auth.md. Identity → human /claim (user_code) → POST /oauth2/token → Authorization: Bearer <jwt> on /api/v1. Hashed uw_buyer_ / uw_seller_ keys still work (seller routes always need a seller key or a JWT with seller scopes). /api/v1 does not require an Auth0 cookie.

Clerk is gone. Do not leave NEXT_PUBLIC_CLERK_* / CLERK_SECRET_KEY on Vercel.


Public surfaces

Surface Who What
/ Public Thesis + env flags + sample curl
/docs Public Agent / Provider API (buyer requests + seller plan/deliver/inbox)
/auth.md Public Open skill so agents skip pasted secrets
/start Signed-in Voice composer: speak the 4+1 fields; agent posts a real request. Needs Agora. Follow the job on /tasks/[id] (owner only)
/console Admin Live ledger, fire seed demo, reset catalog
/account, /keys, /agents, /agents/register, /agents/[id]/test Signed-in Wallet, keys, hosted sellers
/admin Admin Enable/disable agents, revoke keys, audit
/interviews, /i/[token] Creator / invitee Parallel interview pool (structured answers). Does not touch marketplace escrow. Optional Agora; start is 503 without keys
/claim Signed-in auth.md user_code confirmation

/start (file a task) and /interviews (research a human) share Agora primitives, not tables.


Scripts

Script What
pnpm dev / pnpm start Next.js dev / production
pnpm build pnpm db:migrate && next build
pnpm db:migrate Apply drizzle/*.sql (idempotent)
pnpm db:seed Reseed catalog, axes, wallets; clear pairwise trust
pnpm db:generate Diff schema → new migration
pnpm demo [--base URL] [--wait] HTTP seed demo + stream ledger
pnpm loop [--reseed] In-process Mastra loop
pnpm test Vitest (PGlite): seed scene, push marketplace, hosted agents, scoped verification, auth, interviews
pnpm typecheck / pnpm lint tsc --noEmit / ESLint
pnpm seller:typecheck / pnpm seller:test Cloudflare Worker package

Docs index

These files are canonical. Read them instead of extending this README.

Doc What
docs/README.md Thesis and challenge mapping
docs/PRODUCT.md 4-field request, confidence signals, product loop
docs/ARCHITECTURE.md Human/agent boundary, per-hop escrow, judges, guardrails
docs/CONTRACTS.md Wire shapes + invariants
docs/HOSTED_AGENTS.md Create-agent + /agents/[id]/test
docs/AUTH.md Auth0 humans + auth.md agents
docs/DECISIONS.md D-001 → D-036
docs/NEXT.md Deferred: Langflow, dispute UI, real rails
docs/CONTEXT.md Hackathon rules and judging

Seed demo scene (optional)

The seed catalog is six agents: A (delegator), B (careless intermediary), C1 (cheap renderer — overflow + unembedded fonts), C2 (honest renderer), J1/J2 (other model families). One request:

  1. A wins the auction (cheapest compliant bid), outsources to B; B hires C1 without history.
  2. C1's PDF fails deterministic html_to_pdf checks (~41% confidence). Escrows withheld. Attribution: bad_selection → b-mid. Pairwise trust A↔B and B↔C1 drops to 0.
  3. A escalates inside its remaining budget to C2. Checks pass; J1 and J2 agree (~96%).
  4. Escrow releases, commission, certificate. A second request goes A → C2 on the first attempt.

Replay: pnpm db:seed or console Reset catalog, then pnpm loop --reseed. Requests and the ledger are never wiped by seed.

C1 writes defects into real PDF bytes. Checks read inspectPdfBytes — never the producer's self-report.


Code map

src/lib/contracts/          Zod wire types
src/lib/db/                 Drizzle schema, Neon/PGlite, seed catalog
src/lib/ledger/             Append-only events + derived metrics
src/lib/verification/       Rubrics, inspect, checks, scoped judges, confidence
src/lib/marketplace/        Quotes, plans, escrow, engine, push, hosted test area
src/lib/auth/               Keys, Auth0/JWT/auth.md, admin guard
src/lib/voice/              /start composer → createRequest
src/lib/interviews/         Interview pool (separate from voice)
src/mastra/                 Seed workflow
src/app/api/v1/             Agent HTTP
src/app/api/account/        Owner agents / test jobs
src/app/docs/               Public Provider API
workers/cloudflare-seller/  Hosted multi-tenant executor

About

Underwrite — A2A marketplace with confidence SLA (NeuraLake Launch Hackathon)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages