Converge

Live AI-vs-AI negotiation — two agents with hidden reservation prices haggle in real time, and the audience watches it happen.

Converge is a live AI negotiation demo. Two hidden reservation values are seeded for a buyer and a seller, two agents negotiate in public, and the app reveals what happened after the fact: whether they reached a deal, where they landed, and how much surplus was left on the table.

It is built as a fast, hackable TypeScript prototype for demos, experiments, and prompt/agent evaluation rather than a production marketplace.

What It Does

• Collects a private maximum price for the buyer and a private minimum price for the seller.
• Runs a turn-based negotiation between two role-specific agents.
• Streams both the agents' private thought text and their public negotiation messages to the browser in real time.
• Detects three terminal outcomes: deal, walk_away, or deadlock.
• Reveals the ZOPA (Zone of Possible Agreement) after the negotiation ends.
• Optionally emits a Base Sepolia settlement transaction hash for the final deal, with a demo fallback when wallet credentials are not configured.

How It Works

1. Seed the reservations. The audience sets the buyer's max and seller's min — either directly in the UI or by scanning QR codes on two separate devices. Neither agent sees the other's number.

2. Watch the agents negotiate. The orchestrator alternates buyer and seller turns for up to 16 turns. Each agent must return a schema-constrained turn (privateThought, publicMessage, proposedPrice, action), and the server streams both the private thoughts and the public transcript via server-sent events.

3. See who got what — or didn't. The orchestrator terminates on deal, walk_away, or deadlock. Converge then reveals the hidden reservations, overlays the ZOPA, and shows surplus capture for each side.

Core loop

1. A buyer reservation and seller reservation are seeded through /seed or the audience seeding UI.
2. POST /negotiation/start creates a conversation and launches the orchestrator in the background.
3. The orchestrator alternates buyer and seller turns for up to 16 turns.
4. Each agent receives the public transcript so far plus its own private reservation value.
5. Each agent must return a schema-constrained turn:
   • privateThought
   • publicMessage
   • proposedPrice
   • action (offer, accept, or walk_away)
6. The server emits server-sent events (SSE) as the turn unfolds:
   • private_chunk
   • public
   • deal
   • walk_away
   • deadlock
   • tx_hash
   • zopa_reveal
7. The browser renders the private streams, public transcript, live offer markers, and the final ZOPA visualization.

Orchestrator safeguards

• Invalid acceptances are coerced back into offers.
• Offers outside a party's own reservation are normalized into an acceptance or walk-away when possible.
• Stagnation across a six-turn window is treated as a deadlock.
• A hard 16-turn cap prevents endless loops.

Architecture

Server

• src/server.ts: Hono server, static asset serving, route registration.
• src/routes/agent.ts: direct /buyer and /seller agent-turn endpoints.
• src/routes/negotiation.ts: negotiation startup plus SSE streaming.
• src/routes/seed.ts: audience seeding pages and reservation capture.

Agents

• src/agents/personas.ts: buyer and seller system prompts.
• src/agents/runAgent.ts: Anthropic Agent SDK integration, tool-based structured turn submission, streamed private thought capture, and turn normalization.
• src/agents/schema.ts: Zod schema for every turn.
• src/agents/stub.ts: deterministic stub agents used by tests.

Negotiation Engine

• src/orchestrator/negotiator.ts: turn loop, deal/walk/deadlock detection, event emission.
• src/orchestrator/events.ts: SSE event shapes.
• src/orchestrator/zopa.ts: ZOPA/surplus calculations.

Payments

• src/payments/x402.ts: optional settlement submission with timeout and demo fallback hashes.
• src/payments/wallet.ts: Base Sepolia wallet client setup via viem.

Frontend

• public/index.html: three-column live board plus ZOPA footer.
• public/app.js: SSE client, animated private thought streaming, transcript rendering, ZOPA visualization.
• public/seed-*.html: audience-facing seeding flows, including a QR page for live demos.

Tech Stack

• Node.js 20+
• TypeScript
• Hono for HTTP routes
• Zod for request and turn validation
• Anthropic Claude Agent SDK for live agent turns
• Viem for Base Sepolia transaction submission
• Plain HTML/CSS/JS frontend with SSE

Quick Start

1. Install dependencies

npm install

2. Start the app

npm run dev

The server runs on http://localhost:3000.

3. Choose a way to use it

Fixture mode, no API keys required:

http://localhost:3000/?fixture

Live mode with seeded audience reservations:

http://localhost:3000/

The default home page waits for both buyer and seller reservations to be seeded, then automatically starts the negotiation.

Environment Variables

Required for live agent turns

Set ANTHROPIC_API_KEY before calling the live buyer/seller endpoints or running live negotiations with the default agents.

Example:

export ANTHROPIC_API_KEY=your_key_here

Without it, the live integration tests are skipped, and the default agents will not be usable for real LLM-backed runs.

Optional for Base Sepolia settlement

Set these only if you want the app to submit a real demo settlement transaction:

export X402_PRIVATE_KEY=0xyour_private_key_here
export X402_RPC_URL=https://sepolia.base.org

If these are missing, Converge still works and returns a demo placeholder transaction hash instead.

See docs/WALLET_SETUP.md for wallet setup details.

Demo Flows

Local audience-seeded demo

1. Run npm run dev
2. Open http://localhost:3000/seed/qr
3. Have one person scan the buyer QR and another scan the seller QR
4. Submit the two hidden reservation values
5. Open http://localhost:3000/ on the display machine and watch the negotiation stream

Public phone-friendly demo via Cloudflare tunnel

npm run demo

This starts the dev server and a Cloudflare quick tunnel, then prints a public /seed/qr URL. cloudflared must already be installed.

API Overview

Agent turn endpoints

• POST /buyer
• POST /seller

Each accepts a conversation history plus private context and returns a single validated turn.

Negotiation endpoints

• POST /negotiation/start
• GET /negotiation/:id/stream

You can either pass reservations directly to /negotiation/start or seed them first through /seed.

Seeding endpoints

• GET /seed/buyer
• GET /seed/seller
• GET /seed/qr
• POST /seed
• GET /seed/status

For the exact request and event shapes, see CONTRACTS.md.

Scripts

• npm run dev: start the local dev server with file watching
• npm run build: compile TypeScript to dist/
• npm run start: run the compiled server
• npm test: run the Vitest suite
• npm run test:outside-in: run outside-in agent behavior specs
• npm run eval: sample repeated negotiations and print outcome/surplus stats
• npm run demo: start the app plus a Cloudflare quick tunnel

Testing

The test suite covers:

• route validation
• reservation seeding behavior
• negotiation orchestration
• deadlock and walk-away behavior
• SSE event shape expectations
• x402 settlement fallback behavior

Some integration tests are only enabled when ANTHROPIC_API_KEY is present.

Repository Status

This project is best understood as a polished prototype:

• the UX is demo-friendly
• the contracts are explicit
• the negotiation engine is deterministic and test-covered
• the live agents depend on external model access
• the settlement path is intentionally lightweight and optional

If you want to extend it, the cleanest seams are the agent prompts, turn normalization rules, event contract, and frontend visualization layer.