Skip to content

Commit b31e5be

Browse files
trilltinoclaude
trilltino
and
claude
committed
Sync READMEs and root scripts with the agent-commerce layer
Doc audit: the root README, examples/ and coral-agents/ indexes, and CORAL.md predated the harness/verifier/ledger/policy work. Bring them in line with what ships and is validated live on devnet: - README: verifier step in the loop diagram + the live-validation proof (release tx link), prebuilt rows for harness adapters / verifier gate / policy choke point / run ledger, freelancer + research in the examples table and repo layout, runtime section now covers ledger/, policy/, and packages/harness-runtime - examples/README: freelancer + research entries (five views, not three) - coral-agents/README: full agent table (verifier-agent, broker, echo, user_proxy) + the five personas and the claude image build - CORAL.md: layer diagram + file map gain the new launchers, the verifier, harness-runtime, and CORAL-IMPLEMENTATION.md cross-link - package.json: npm run freelancer / research / research:watch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent bdc9de3 commit b31e5be

5 files changed

Lines changed: 100 additions & 30 deletions

File tree

‎CORAL.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,15 @@ the kit does**. If you want the LLM equivalent of this doc, see [LLM.md](LLM.md)
3737
│ coral.toml registry scan of /agents/*, auth, docker host │
3838
│ examples/txodds/coral/round.ts POST /api/v1/local/session (agent graph)│
3939
│ examples/marketplace/start.ts " (buyer + persona sellers) │
40+
│ examples/freelancer/start.ts " (harness sellers + the verifier gate) │
41+
│ examples/research/start.ts " (event-mode buyer + specialists) │
4042
│ examples/agent-economy/bridge " + the puppet API (human → agent) │
4143
└──────────────────────────────────────────────────────────────────────────────┘
4244
│ spawns, injects CORAL_CONNECTION_URL
4345
▼
4446
┌─ Layer 2 — the agents (coral-agents/*) ─────────────────────────────────────┐
45-
│ buyer-agent seller-agent (+seller-worldcup) broker echo-agent user_proxy│
47+
│ buyer-agent seller-agent (+ personas: worldcup/scribe/claude/moves/stats) │
48+
│ verifier-agent broker echo-agent user_proxy │
4649
│ each: a coral-agent.toml manifest + a container image, an MCP participant │
4750
└──────────────────────────────────────────────────────────────────────────────┘
4851
│ import { startCoralAgent, … }
@@ -366,11 +369,17 @@ the doc page that shows you how.
366369
| [examples/txodds/coral/coral.toml](examples/txodds/coral/coral.toml) | coral-server config: registry scan, auth, docker host (no wallet) |
367370
| [examples/txodds/coral/round.ts](examples/txodds/coral/round.ts) | Launches the TxODDS round via `POST /api/v1/local/session` |
368371
| [examples/marketplace/start.ts](examples/marketplace/start.ts) | Launches the competitive market (buyer + persona sellers) |
372+
| [examples/freelancer/start.ts](examples/freelancer/start.ts) | Launches the freelancer market (harness sellers + the verifier release gate) |
373+
| [examples/research/start.ts](examples/research/start.ts) | Launches the research market (event-mode buyer; the watcher queues WANTs) |
374+
| [coral-agents/verifier-agent/](coral-agents/verifier-agent/README.md) | Independent delivery verifier — `VERIFY` in, `VERIFIED pass\|fail` out |
375+
| [packages/harness-runtime/](packages/harness-runtime/README.md) | Harness adapter SDK — Claude Code / any CLI as a market seller |
369376
| [examples/agent-economy/bridge/server.ts](examples/agent-economy/bridge/server.ts) | Human → agent bridge: the puppet API + extended-state reads |
370377

371378
See also: [coral-agents/buyer-agent/README.md](coral-agents/buyer-agent/README.md),
372379
[coral-agents/seller-agent/README.md](coral-agents/seller-agent/README.md),
373-
[coral-agents/broker/README.md](coral-agents/broker/README.md), and the round walkthrough in
380+
[coral-agents/verifier-agent/README.md](coral-agents/verifier-agent/README.md),
381+
[coral-agents/broker/README.md](coral-agents/broker/README.md), the implementation walkthrough in
382+
[CORAL-IMPLEMENTATION.md](CORAL-IMPLEMENTATION.md), and the round walkthrough in
374383
[examples/txodds/coral/README.md](examples/txodds/coral/README.md).
375384

376385
---

‎README.md‎

Lines changed: 48 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,11 @@ Some things agents can sell on these exact rails:
3434
| **Oracle agent** | a verified fact / a checked output | trust in a number |
3535
| **Reseller agent** | packages other agents' services into one | a bundle, one payment |
3636

37+
The first two already ship as working markets: [`examples/freelancer`](examples/freelancer/README.md)
38+
(heterogeneous harnesses — a plain LLM vs headless **Claude Code** — bid on a brief, an independent
39+
verifier gates the release) and [`examples/research`](examples/research/README.md) (live odds moves
40+
trigger the WANT — quiet board, no spend). Fork those instead of starting blank.
41+
3742
> **The World Cup oracle is only the default demo — not the product.** It sells a verified, de-margined
3843
> betting line to prove the rails work end-to-end. The invitation isn't "here's a repo about sports
3944
> odds"; it's **"here are the rails for autonomous services with on-chain settlement — fork one function,
@@ -44,14 +49,21 @@ Some things agents can sell on these exact rails:
4449
The competitive market runs one round as a chain of on-chain-anchored steps. All of it ships working:
4550

4651
```
47-
WANT ─▶ BID ─▶ AWARD ─▶ DEPOSITED ─▶ DELIVERED ─▶ RELEASED
48-
│ │ │ │ │ │
49-
buyer sellers buyer funds lock seller escrow pays
50-
asks compete picks in escrow delivers the winner
51-
best (devnet) the service (or REFUNDED
52-
value on a no-show)
52+
WANT ─▶ BID ─▶ AWARD ─▶ DEPOSITED ─▶ DELIVERED ─▶ (VERIFIED) ─▶ RELEASED
53+
│ │ │ │ │ │ │
54+
buyer sellers buyer funds lock seller independent escrow pays
55+
asks compete picks in escrow delivers verifier the winner
56+
best (devnet) the service gates the (or REFUNDED
57+
value (hash-bound) release on a no-show)
5358
```
5459

60+
**Validated live on devnet, both ways.** A seller that delivered a broken payload got its release
61+
**refused** (verifier fail → policy gate → funds stayed refundable), and a good delivery settled
62+
through the neutral arbiter —
63+
[see the release tx](https://explorer.solana.com/tx/3MEWxbYUPVGV4QXN3VH4J7Rripz4vbrFKCbBNAbXtYAhXG3NecAkFZkQmYmqBuykJZkHhkiMruXkbnYDCN1BpbM8?cluster=devnet).
64+
Every round leaves a **run ledger** folder (bids, award reasoning, hash-bound delivery, verifier
65+
verdict, Explorer-linked txs) and feeds a **reputation score** buyers weigh on the next award.
66+
5567
| You get, prebuilt | Where | So you don't have to |
5668
| ------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------ |
5769
| **LLM brain** (Venice AI) | [`packages/agent-runtime/src/llm`](packages/agent-runtime/src/llm) | wire an LLM SDK, prompts, JSON-guarding |
@@ -60,6 +72,10 @@ WANT ─▶ BID ─▶ AWARD ─▶ DEPOSITED ─▶ DELIVERED ─▶ RELEASED
6072
| **Frontend state** (live rounds/bids/settlement) | [`examples/marketplace/web`](examples/marketplace/web) | build a React app that streams the market |
6173
| **Solana Pay** (reference-bound transfers) | [`packages/agent-runtime/src/solana`](packages/agent-runtime/src/solana) | hand-roll payment URLs + verification |
6274
| **Escrow** (deposit → release / refund) | [`examples/txodds/escrow`](examples/txodds/escrow) | write, audit, and deploy an Anchor program |
75+
| **Harness adapters** (Claude Code / any CLI sells) | [`packages/harness-runtime`](packages/harness-runtime) | bridge external agent harnesses yourself |
76+
| **Verifier gate** (release only on a pass) | [`coral-agents/verifier-agent`](coral-agents/verifier-agent) | build independent delivery checks |
77+
| **Policy choke point** (caps, bindings, gates) | [`packages/agent-runtime/src/policy`](packages/agent-runtime/src/policy) | scatter ad-hoc safety checks |
78+
| **Run ledger + reputation** (auditable rounds) | [`packages/agent-runtime/src/ledger`](packages/agent-runtime/src/ledger) | build an audit trail + track record |
6379

6480
## Prerequisites
6581

@@ -134,6 +150,9 @@ One `npm run` per example, from the repo root. **Each command installs that exam
134150
| `npm run demo:coral` | the same oracle as a **multi-agent CoralOS round** (buyer + competing sellers) | Docker + `docker compose up -d coral` + a TxLINE token (`npm --prefix examples/txodds run mint`) |
135151
| `npm run marketplace` | **the full market** — a buyer + LLM sellers bidding in one session | Docker + `docker compose up -d coral` + `bash build-agents.sh` |
136152
| `npm run marketplace:web` | the market **visualizer** — live rounds, bids, settlement badges (:5173) | the marketplace feed running |
153+
| `npm run freelancer` | **the freelancer market** — heterogeneous harnesses bid on a brief; an independent verifier gates the escrow release | Docker + coral + `bash build-agents.sh` (add `CLAUDE_SELLER=1` after `bash build-agents.sh claude`) |
154+
| `npm run research` | **the research market** — live odds moves trigger paid research rounds (quiet board = no spend) | Docker + coral + the txodds proxy + `npm run research:watch` |
155+
| `npm run research:watch` | the research **event watcher** — diffs the live board, queues WANTs (:4600) | the txodds proxy (`npm run dev` or `npm --prefix examples/txodds run proxy`) |
137156
| `npm run agent-economy` | **autonomous** agent→agent purchase | Docker + `docker compose up -d coral` |
138157
| `npm run agent-economy:bridge` | the **human checkout** bridge (HTTP + React) | Docker + `docker compose up -d coral` |
139158
| `npm run agent-economy:quickstart` | the **bare 402** pay-per-call seller (no Docker, no CoralOS) | LLM key + funded wallet |
@@ -159,7 +178,7 @@ build?"** — the rails don't care what you sell.
159178

160179
## Under the hood — the runtime
161180

162-
Agents import [`packages/agent-runtime`](packages/agent-runtime) and write only behaviour. Four modules,
181+
Agents import [`packages/agent-runtime`](packages/agent-runtime) and write only behaviour. Six modules,
163182
one per concern:
164183

165184
- **`llm/`** — [`complete()`](packages/agent-runtime/src/llm/complete.ts), one provider-agnostic call
@@ -170,9 +189,23 @@ one per concern:
170189
the **devnet guard** that throws on a mainnet RPC unless `ALLOW_MAINNET=1`, so it applies everywhere
171190
value moves.
172191
- **`coral/`** — a CoralOS (MCP) client + agent entrypoint: the coordination fabric the sellers and
173-
buyer meet on. Deep dive, source → example: **[CORAL.md](CORAL.md)**; official docs:
192+
buyer meet on. Deep dive, source → example: **[CORAL.md](CORAL.md)** (implementation walkthrough:
193+
[CORAL-IMPLEMENTATION.md](CORAL-IMPLEMENTATION.md)); official docs:
174194
[docs.coralos.ai](https://docs.coralos.ai/welcome).
175-
- **`market/`** — the WANT/BID/AWARD wire format: the negotiation protocol, pure and testable.
195+
- **`market/`** — the WANT/BID/AWARD wire format (now incl. **VERIFY/VERIFIED**): the negotiation
196+
protocol, pure and testable.
197+
- **`ledger/`** — the **run ledger**: one folder per paid round (bids, award reasoning, sha256-bound
198+
delivery, verifier verdict, Explorer-linked txs, the raw transcript) + **reputation** derived from it.
199+
"What did the agent actually do for the money?" — open the run.
200+
- **`policy/`** — [`enforce()`](packages/agent-runtime/src/policy/policy.ts), the choke point every
201+
deposit/release passes: spend caps, service allowlist, payout binding, award-price binding
202+
(a seller can't inflate the escrow after winning), verifier gate.
203+
204+
And one more package: [`packages/harness-runtime`](packages/harness-runtime) — the **harness adapter
205+
SDK**. One interface (`quote`/`run`) so a seller can be a prompt (`node-llm`), **headless Claude Code**
206+
(`claude-code`, with Coral MCP config injection), or any CLI (`HARNESS=cli HARNESS_CMD='hermes {prompt}'`).
207+
The agent keeps the wallet and the escrow checks; the harness only produces hash-bound artifacts —
208+
**harness processes never hold keys**.
176209

177210
### The escrow contract — the settlement spine
178211

@@ -199,10 +232,13 @@ deployed ids with no local build. **Devnet only** — never put a funded mainnet
199232
| Directory | Purpose |
200233
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
201234
| `examples/txodds/` | **the default demo** — the World Cup oracle. `agent/` (`service.ts` = the `deliverService()` fork point; `edge.ts` = its transform; escrow/arbiter clients), `server/` (proxy + mint), `web/` (React board), `escrow/` (the two Anchor programs) |
202-
| `examples/marketplace/` | **the full market** — a buyer + competing sellers in one CoralOS session; `feed/` (SSE feed → rounds), `web/` (React visualizer). Needs Docker |
235+
| `examples/marketplace/` | **the full market** — a buyer + competing sellers in one CoralOS session; `feed/` (rounds + the **run ledger** `runs/`, `/api/runs`, `/api/reputation`, disk replay), `web/` (React visualizer). Needs Docker |
236+
| `examples/freelancer/` | **the freelancer market** — heterogeneous harnesses (plain LLM vs **Claude Code**) bid on a brief; the **verifier** gates the arbiter release. Needs Docker |
237+
| `examples/research/` | **the research market** — live odds moves trigger paid research WANTs (event watcher + event-mode buyer; quiet board = no spend). Needs Docker + the txodds proxy |
203238
| `examples/agent-economy/` | **three front doors** on CoralOS — autonomous (agent→agent), a human checkout bridge, and a bare 402 pay-per-call quickstart |
204-
| `coral-agents/` | the agents coral-server launches per session —`buyer-agent`, `seller-agent` (+ personas), `broker` (swarm reseller), `echo-agent`, `user_proxy` |
205-
| `packages/agent-runtime/` | the runtime —`llm/`, `solana/`, `coral/`, `market/` |
239+
| `coral-agents/` | the agents coral-server launches per session —`buyer-agent`, `seller-agent` (+ personas incl. `seller-claude`), `verifier-agent` (the release gate), `broker` (swarm reseller), `echo-agent`, `user_proxy` |
240+
| `packages/agent-runtime/` | the runtime —`llm/`, `solana/`, `coral/`, `market/`, `ledger/`, `policy/` |
241+
| `packages/harness-runtime/` | the **harness adapter SDK** — `node-llm` / `claude-code` / any CLI as market sellers |
206242
| `scripts/` | `txodds.js` (`npm run dev`), `setup.js` (devnet wallets) |
207243
| `docker-compose.yml` | coral-server (the MCP coordinator) for the market |
208244

0 commit comments

Comments
 (0)