Skip to content

Commit e569ade

Browse files
trilltinotrilltino
committed
Complete payment runtime audit
1 parent d8703d3 commit e569ade

59 files changed

Lines changed: 1400 additions & 161 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,34 @@ jobs:
1919
- run: cd packages/agent-runtime && npm run typecheck
2020
- run: cd packages/agent-runtime && npm test
2121

22+
harness-runtime:
23+
name: Harness runtime (packages/harness-runtime)
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v5
27+
- uses: actions/setup-node@v5
28+
with:
29+
node-version: 20
30+
- name: Build the agent runtime — the adapter SDK's file dep needs its dist
31+
run: cd packages/agent-runtime && npm install && npm run build
32+
- run: cd packages/harness-runtime && npm install
33+
- run: cd packages/harness-runtime && npm run typecheck
34+
- run: cd packages/harness-runtime && npm test
35+
36+
payment-runtime:
37+
name: Payment runtime (packages/payment-runtime)
38+
runs-on: ubuntu-latest
39+
steps:
40+
- uses: actions/checkout@v5
41+
- uses: actions/setup-node@v5
42+
with:
43+
node-version: 20
44+
- name: Build the agent runtime — the rails reuse Solana Pay + the devnet guard from its dist
45+
run: cd packages/agent-runtime && npm install && npm run build
46+
- run: cd packages/payment-runtime && npm install
47+
- run: cd packages/payment-runtime && npm run typecheck
48+
- run: cd packages/payment-runtime && npm test
49+
2250
txodds:
2351
name: TxODDS World Cup Oracle (typecheck + tests)
2452
runs-on: ubuntu-latest
@@ -32,6 +60,89 @@ jobs:
3260
- name: txodds (typecheck + tests)
3361
run: cd examples/txodds && npm install && npm run typecheck && npm test
3462

63+
marketplace:
64+
name: Marketplace (feed tests + visualizer unit + Playwright e2e)
65+
runs-on: ubuntu-latest
66+
steps:
67+
- uses: actions/checkout@v5
68+
- uses: actions/setup-node@v5
69+
with:
70+
node-version: 20
71+
- name: Build the runtime (the feed folds rounds with its parsers)
72+
run: cd packages/agent-runtime && npm install && npm run build
73+
- name: Round launchers (typecheck)
74+
run: cd examples/marketplace && npm install && npm run typecheck
75+
- name: Feed server (typecheck + foldRounds/persist tests against a recorded transcript)
76+
run: cd examples/marketplace/feed && npm install && npm run typecheck && npm test
77+
- name: Visualizer (typecheck + component tests)
78+
run: cd examples/marketplace/web && npm install && npm run typecheck && npm test
79+
- name: Install Playwright browser
80+
run: cd examples/marketplace/web && npx playwright install --with-deps chromium
81+
# The e2e is the marketplace smoke test: Playwright boots the REAL feed server on a recorded
82+
# CoralOS transcript and drives the real React app — no devnet, no Docker, no LLM keys.
83+
- name: Smoke — recorded coral state → feed → UI (Playwright)
84+
run: cd examples/marketplace/web && npm run e2e
85+
86+
agent-economy:
87+
name: Agent economy (typechecks + web build smoke)
88+
runs-on: ubuntu-latest
89+
steps:
90+
- uses: actions/checkout@v5
91+
- uses: actions/setup-node@v5
92+
with:
93+
node-version: 20
94+
- name: Autonomous flow (typecheck)
95+
run: cd examples/agent-economy/autonomous && npm install && npm run typecheck
96+
- name: Quickstart 402 flow (typecheck)
97+
run: cd examples/agent-economy/quickstart && npm install && npm run typecheck
98+
- name: Bridge (typecheck)
99+
run: cd examples/agent-economy/bridge && npm install && npm run typecheck
100+
# The web build is this example's smoke test: `npm run build` = tsc --noEmit + a full vite
101+
# production build of the checkout/autonomous/swarm UI. (bridge/smoke.ts needs a live
102+
# coral-server + a funded devnet wallet, so it stays a local/manual check.)
103+
- name: Smoke — dashboard production build
104+
run: cd examples/agent-economy/web && npm install && npm run build
105+
106+
coral-agents:
107+
name: Coral agents (buyer / seller / verifier / broker)
108+
runs-on: ubuntu-latest
109+
steps:
110+
- uses: actions/checkout@v5
111+
- uses: actions/setup-node@v5
112+
with:
113+
node-version: 20
114+
- name: Build the runtimes (agents need local package dists)
115+
run: |
116+
cd packages/agent-runtime && npm install && npm run build
117+
cd ../harness-runtime && npm install && npm run build
118+
cd ../payment-runtime && npm install && npm run build
119+
- name: Buyer agent (typecheck + tests — policy, guard, reputation, want feed)
120+
run: cd coral-agents/buyer-agent && npm install && npm run typecheck && npm test
121+
- name: Seller agent (typecheck + tests — payment, replay, service)
122+
run: cd coral-agents/seller-agent && npm install && npm run typecheck && npm test
123+
- name: Verifier agent (typecheck + tests)
124+
run: cd coral-agents/verifier-agent && npm install && npm run typecheck && npm test
125+
- name: Broker (typecheck + tests)
126+
run: cd coral-agents/broker && npm install && npm run typecheck && npm test
127+
- name: Echo agent (typecheck)
128+
run: cd coral-agents/echo-agent && npm install && npm run typecheck
129+
130+
agent-desk:
131+
name: Agent desk (UI syntax + config smoke)
132+
runs-on: ubuntu-latest
133+
steps:
134+
- uses: actions/checkout@v5
135+
- uses: actions/setup-node@v5
136+
with:
137+
node-version: 20
138+
# The desk UI is no-build static JS; the Tauri shell needs the full Rust + webkit toolchain,
139+
# so CI checks what's cheap and deterministic: the module parses and the configs are valid.
140+
- name: UI parses + Tauri configs are valid JSON
141+
run: |
142+
cd examples/txodds-agent-desk
143+
node --check ui/app.js
144+
node -e "JSON.parse(require('fs').readFileSync('src-tauri/tauri.conf.json')); JSON.parse(require('fs').readFileSync('src-tauri/capabilities/default.json'))"
145+
35146
escrow:
36147
name: Escrow + arbiter contracts (Rust compile check)
37148
runs-on: ubuntu-latest

‎CLAUDE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,11 @@ is **Venice AI** (free credits; `LLM_PROVIDER` also accepts `openai`/`anthropic`
2929
|-----------|---------|
3030
| `examples/txodds/` | The World Cup Oracle (the headline example). `agent/` (`edge.ts` — the verified-odds→LLM-call transform; `service.ts` — the `deliverService` fork point; `escrow.ts` — the buyer-side escrow client), `server/` (`mint.ts`, `proxy.ts` — the live data + escrow proxy), `web/` (the no-build React app), `research/` (`watcher.ts` + `detect.ts` — the odds-move event watcher feeding the research round; `npm run watch`), `escrow/` (the Anchor escrow + arbiter programs — the settlement spine). |
3131
| `examples/agent-economy/` | **Three front doors** on CoralOS (needs Docker): `autonomous/` (agent→agent purchase), `bridge/` (HTTP bridge + React checkout — the human front door), `quickstart/` (bare 402 pay-per-call, no Docker/CoralOS), `web/` (3-tab dashboard), `config/coral.toml`. Escrow references point at `examples/txodds/escrow/`. |
32+
| `examples/txodds-agent-desk/` | The **operator console**: a Tauri v2 desktop shell (`src-tauri/`, ~10 lines of Rust, no IPC/keys) around a no-build static UI (`ui/`) that consumes the txodds proxy (:8801 — runs, proof receipts, settle, Pay.sh procurement), the marketplace feed (:4000, optional), and the watcher (:4600, optional). Browser mode: `npm run desk` (serves `ui/` on :3030, no Rust toolchain needed); desktop: `npm run desk:app` (needs Rust + WebView2). |
3233
| `examples/marketplace/` | **Competitive bidding market, three rounds** (needs Docker): `start.ts` (classic buyer + persona sellers), `freelancer.ts` (**verifier-gated**: heterogeneous harnesses — `seller-scribe` node-llm vs `seller-claude` Claude Code — bid on a brief; `verifier-agent` gates the release), `research.ts` (**event-driven**: the buyer polls the txodds watcher via `WANT_FEED_URL` — quiet board, no spend; needs the txodds proxy + `npm run watch` there); `feed/` (folds session state into rounds AND persists each round to the **run ledger** `runs/`; serves `/api/runs` + `/api/reputation`; replays a session from disk when coral is down), `web/` (React visualizer + Playwright tests). Settles via the escrow. |
3334
| `packages/agent-runtime/` | The runtime, one folder each under `src/`: the LLM provider shim (`llm/`), Solana Pay + devnet guard (`solana/`), a CoralOS MCP client (`coral/`), the market protocol incl. VERIFY/VERIFIED (`market/`), the **run ledger + reputation** (`ledger/`), and the **policy choke point** (`policy/` — spend caps, payout/award-price binding, verifier gate). Root `src/index.ts` re-exports all of them. |
3435
| `packages/harness-runtime/` | The **harness adapter SDK**: one `HarnessAdapter` interface (`quote`/`run`, hash-bound deliveries, streamed events) so a seller can be a prompt (`node-llm`), headless Claude Code (`claude-code`, Coral MCP config injection), or any CLI (`HARNESS=cli HARNESS_CMD='hermes {prompt}'`). Harness processes never hold keys. Build after agent-runtime. |
36+
| `packages/payment-runtime/` | The **payment rail router**: one `PaymentRail` interface + `PaymentRailRouter` + allowance/merchant/procurement policies. **Honest split** (status table in its README): Solana Pay + escrow are live devnet rails; Pay.sh, x402, USDC, allowance, embedded-wallet, payout are typed scaffolds. First consumers: the txodds Pay.sh procurement demo (`/api/pay-sh-edge`) and the seller-agent's upstream procurement. Build after agent-runtime. |
3537
| `coral-agents/` | The agents coral-server launches per session: `buyer-agent` (policy-enforced, verifier-gated, event-mode capable), `seller-agent` (harness-adapter seller; personas `seller-worldcup`/`seller-scribe`/`seller-claude`/`seller-moves`/`seller-stats` reuse its image), `verifier-agent` (independent delivery checks — release gate), plus `broker/` (swarm — buys upstream, resells at a markup, escrow both legs), `echo-agent/` (minimal test agent), `user_proxy/` (the human's puppet for the bridge). |
3638
| `scripts/` | `txodds.js` (the `npm run dev` launcher — proxy + web + browser) and `setup.js` (devnet wallet generation → `.env`). |
3739

‎CONTRIBUTING.md‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,31 @@ Contributions are welcome. The `main` branch is the integration branch — targe
66

77
| Directory | Language | Typical changes |
88
|-----------|----------|-----------------|
9-
| `packages/agent-runtime/` | TypeScript | The runtime: LLM shim, Solana Pay + devnet guard, CoralOS MCP client, the market protocol |
10-
| `examples/txodds/` | TypeScript | The World Cup Oracle — the edge transform, the proxy, the web app |
11-
| `examples/txodds/escrow/` | Rust (Anchor) | The escrow settlement contract |
9+
| `packages/agent-runtime/` | TypeScript | The runtime: LLM shim, Solana Pay + devnet guard, CoralOS MCP client, the market protocol (incl. VERIFY/VERIFIED), the run ledger + reputation, the policy choke point |
10+
| `packages/harness-runtime/` | TypeScript | The harness adapter SDK (`node-llm` / `claude-code` / any CLI as sellers) |
11+
| `examples/txodds/` | TypeScript | The World Cup Oracle — the edge transform, the proxy (+ run grading), the web app, the research watcher |
12+
| `examples/txodds/escrow/` | Rust (Anchor) | The escrow + arbiter settlement contracts |
13+
| `examples/marketplace/` | TypeScript | The competitive market (3 rounds: classic / freelancer / research), the feed server, the React visualizer |
14+
| `examples/agent-economy/` | TypeScript | The three front doors (autonomous / bridge checkout / quickstart) + dashboard |
15+
| `coral-agents/` | TypeScript | The per-session agents: buyer, seller (+ personas), verifier, broker, echo, user-proxy |
1216

1317
## Prerequisites
1418

1519
- Node.js 20+
16-
- An LLM key + a funded devnet wallet to run the live demo (see the root README). **No Docker needed.**
20+
- An LLM key + a funded devnet wallet to run the live demo (see the root README). **The default demo
21+
needs no Docker**; the multi-agent markets need Docker (coral-server).
1722

1823
## Development Commands
1924

2025
```sh
21-
# build the runtime first — examples/txodds depends on its dist via a file: dep
26+
# build the runtimes first — dependents use their dist via file: deps
2227
cd packages/agent-runtime && npm install && npm run build && npm run typecheck && npm test
28+
cd packages/harness-runtime && npm install && npm run build && npm test # after agent-runtime
2329

24-
# typecheck + test the example
30+
# typecheck + test what you changed, e.g.
2531
cd examples/txodds && npm install && npm run typecheck && npm test
32+
cd examples/marketplace/feed && npm install && npm test
33+
cd examples/marketplace/web && npm install && npm test && npm run e2e # e2e = fixtures, no devnet
2634
```
2735

2836
## PR Workflow

‎README.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ verdict, Explorer-linked txs) and feeds a **reputation score** buyers weigh on t
7272
| **Frontend state** (live rounds/bids/settlement) | [`examples/marketplace/web`](examples/marketplace/web) | build a React app that streams the market |
7373
| **Solana Pay** (reference-bound transfers) | [`packages/agent-runtime/src/solana`](packages/agent-runtime/src/solana) | hand-roll payment URLs + verification |
7474
| **Escrow** (deposit → release / refund) | [`examples/txodds/escrow`](examples/txodds/escrow) | write, audit, and deploy an Anchor program |
75+
| **Payment rails** (one interface; 2 live, 6 scaffolds) | [`packages/payment-runtime`](packages/payment-runtime) | re-plumb payments per provider (see its README's honest status table) |
7576
| **Harness adapters** (Claude Code / any CLI sells) | [`packages/harness-runtime`](packages/harness-runtime) | bridge external agent harnesses yourself |
7677
| **Verifier gate** (release only on a pass) | [`coral-agents/verifier-agent`](coral-agents/verifier-agent) | build independent delivery checks |
7778
| **Policy choke point** (caps, bindings, gates) | [`packages/agent-runtime/src/policy`](packages/agent-runtime/src/policy) | scatter ad-hoc safety checks |
@@ -158,10 +159,13 @@ One `npm run` per example, from the repo root. **Each command installs that exam
158159
| `npm run agent-economy:quickstart` | the **bare 402** pay-per-call seller (no Docker, no CoralOS) | LLM key + funded wallet |
159160
| `npm run agent-economy:quickstart:buyer` | the quickstart **buyer** (run in a 2nd terminal) | the quickstart server running |
160161
| `npm run agent-economy:web` | the agent-economy **3-tab dashboard** | — (talks to the bridge) |
162+
| `npm run desk` | **TxODDS Agent Desk** in a browser (:3030) - run ledger, proof receipts, board actions | the txodds proxy (`npm run dev` or `npm --prefix examples/txodds run proxy`) |
163+
| `npm run desk:app` | the same desk as a **Tauri desktop app** | Rust/Tauri prerequisites + the txodds proxy |
161164

162165
> **Docker ones** (`marketplace`, `demo:coral`, `agent-economy`, `:bridge`) coordinate over coral-server,
163166
> so start it first: `docker compose up -d coral`, and `bash build-agents.sh` to build the agent images.
164-
> **No-Docker ones** (`dev`, `agent-economy:quickstart`, `:web`, `marketplace:web`) run straight from Node.
167+
> **No-Docker ones** (`dev`, `agent-economy:quickstart`, `:web`, `marketplace:web`, `desk`) run straight
168+
> from Node; `desk:app` adds the Tauri/Rust shell.
165169
166170
## Make it yours
167171

@@ -194,7 +198,8 @@ one per concern:
194198
- **`market/`** — the WANT/BID/AWARD wire format (now incl. **VERIFY/VERIFIED**): the negotiation
195199
protocol, pure and testable.
196200
- **`ledger/`** — the **run ledger**: one folder per paid round (bids, award reasoning, sha256-bound
197-
delivery, verifier verdict, Explorer-linked txs, the raw transcript) + **reputation** derived from it.
201+
delivery, verifier verdict, payment proof receipts, Explorer-linked txs, the raw transcript) +
202+
**reputation** derived from it.
198203
"What did the agent actually do for the money?" — open the run.
199204
- **`policy/`** — [`enforce()`](packages/agent-runtime/src/policy/policy.ts), the choke point every
200205
deposit/release passes: spend caps, service allowlist, payout binding, award-price binding
@@ -233,10 +238,12 @@ deployed ids with no local build. **Devnet only** — never put a funded mainnet
233238
| `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), `research/` (the odds-move **event watcher** feeding the research round), `escrow/` (the two Anchor programs) |
234239
| `examples/marketplace/` | **the full market** — a buyer + competing sellers in one CoralOS session, in three rounds: `start.ts` (classic), `freelancer.ts` (harness sellers + **verifier-gated** release), `research.ts` (event-driven — odds moves trigger the WANTs); `feed/` (rounds + the **run ledger** `runs/`, `/api/runs`, `/api/reputation`, disk replay), `web/` (React visualizer). Needs Docker |
235240
| `examples/agent-economy/` | **three front doors** on CoralOS — autonomous (agent→agent), a human checkout bridge, and a bare 402 pay-per-call quickstart |
241+
| `examples/txodds-agent-desk/` | the **operator console** — a Tauri desktop shell over the proxy + run ledger + proof receipts (`npm run desk` for the browser version, no Rust needed) |
236242
| `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` |
237243
| `packages/agent-runtime/` | the runtime —`llm/`, `solana/`, `coral/`, `market/`, `ledger/`, `policy/` |
238244
| `packages/harness-runtime/` | the **harness adapter SDK** — `node-llm` / `claude-code` / any CLI as market sellers |
239-
| `scripts/` | `txodds.js` (`npm run dev`), `setup.js` (devnet wallets) |
245+
| `packages/payment-runtime/` | the **payment rail router** — Solana Pay + escrow live; Pay.sh / x402 / USDC / allowance / embedded / payout as typed scaffolds (status table in its README) |
246+
| `scripts/` | `txodds.js` (`npm run dev`), `setup.js` (devnet wallets), `provision-swarm.js` (broker + seller wallets for the swarm demo) |
240247
| `docker-compose.yml` | coral-server (the MCP coordinator) for the market |
241248

242249
## The LLM: Venice AI

0 commit comments

Comments
 (0)