cascrow-mcp 1.7.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 3.0.0 — unreleased (owner publishes)
+
+- **`cascrow_join_contract` says what the builder can do now.** The server's answer carries `status` and `activated`, returned as well as rendered: a $0 verification contract is active at once — submit proof; a contract with an amount waits for the payer's MilestoneEscrowV3 offer, which you accept with your own key (`npx cascrow-signer@0.1.0 accept --milestone <id>`). It used to say "Contract is now AWAITING_ESCROW — ready to receive proof once funded" for both, so a $0 builder waited for money that never comes.
+- **New outcome `NOT_COMPLETABLE_WITHOUT_ESCROW`.** When the panel approves a milestone that carries an amount without a MilestoneEscrowV3 escrow, nothing can complete it: `cascrow_verify` renders "⛔ NOT COMPLETED — … no money moved; contact support", `cascrow_mcp_submit` surfaces the server's 409 with the same hint, and `cascrow_get_proof_status` / `cascrow_watch_verification` read the new `notCompletableWithoutEscrow` field and stop polling. Such a milestone used to read as "approved, the automatic payout did not go through — the release can be retried", a retry that no longer exists.
+- **Breaking: `releaseHoldUntil` / `release_hold_until` are gone** from every result, with the v2 release window they reported. A bare `VERIFIED` no longer promises a retried release.
+- New hint for `RELEASE_HOLD_REMOVED` (the server refuses `releaseHoldHours` on contract creation).
+- **Breaking: `cascrow_fund_milestone` is removed** (cascrow Phase 6 — the v2 RLUSD escrow is gone). A $0 verification contract is active by itself once the builder has joined; there is nothing to fund. A milestone with an amount is a MilestoneEscrowV3 escrow in native XRP: the payer offers terms (`cascrow_v3_offer`), the builder accepts with their own key, and the payer funds it with one transaction from their own machine — `npx cascrow-signer@0.1.0 fund --milestone <milestoneId>`. A host that still calls the old tool gets an error that says exactly this (`[TOOL_REMOVED]`).
+- The `cascrow_escrow_fund` refusal names only the V3 flow and `cascrow-signer`; the pointers to `escrow-prepare` and `escrow/sync` are gone with those endpoints.
+- `amountUSD` in `cascrow_create_contract`: 0 (or absent) = verification only; above 0 = MilestoneEscrowV3 offer flow.
+- `cascrow_review_queue` / `cascrow_review_contract` describe what a funder verdict does now: it completes or hands back a verification-only milestone and moves no money. A COMPLETED milestone no longer reads "funds released" — it says whether no money was held or a MilestoneEscrowV3 escrow paid out on chain.
+- `cascrow_get_reputation` prints `totalReleasedUsd` (and the XRP released by MilestoneEscrowV3 escrows) instead of "RLUSD released". `totalRlusdReleased` is still in the response, deprecated.
+
+## 2.1.0 — unreleased (owner publishes)
+
+- **MilestoneEscrowV3, remote half.** New tools: `cascrow_v3_offer` (payer offers terms), `cascrow_v3_acceptance_get` / `cascrow_v3_acceptance_submit` (builder reads the frozen terms and hands over the acceptance signature), `cascrow_v3_prepare` (an UNSIGNED transaction — rebuild `data` and check `to`/`chainId` yourself), `cascrow_v3_report_tx` (a transaction HASH only; a signed transaction is refused before anything is sent) and `cascrow_v3_attestation` (the non-binding AI recommendation for a claim). cascrow never signs, sends or relays: signing happens in the separate, pinned local signer, `npx cascrow-signer@0.1.0`.
+- `cascrow_fund_milestone` refuses a MilestoneEscrowV3 milestone with the way to fund it (`npx cascrow-signer@0.1.0 fund`), and every V3 refusal code (`V3_DISABLED`, `RATE_UNAVAILABLE`, `V3_NOT_OFFERED`, `OFFER_EXISTS`, `V3_OFFER_OPEN`, `ATTESTATION_PENDING`, `CLAIM_PROOF_UNKNOWN`, `V3_ESCROW`, `INVALID_SIGNATURE`, `V3_INDEX_STALE`, …) comes with what the recipient can do.
+- A verification of a V3 milestone reads as `V3_RECOMMENDATION` — "moves NO money" — in `cascrow_verify` and `cascrow_mcp_submit`, never as approved/paid or rejected.
+
+## 2.0.0 — unreleased (owner publishes)
+
+- **Breaking: `cascrow_escrow_fund` is removed.** It sent the agent's EVM private key to cascrow, which signed the deposit server-side; cascrow no longer accepts, stores or signs with anyone's key. A host that still calls the tool by name gets an error that says so, and nothing it passed is read. Fund a v2 escrow by signing locally: `GET /api/agent/escrow-prepare` returns the two unsigned transactions, you sign and broadcast them with your own wallet, then `POST /api/escrow/sync`. Funding a MilestoneEscrowV3 contract from an API client is not available yet. **If you ever passed a private key to this tool, treat that key as exposed and move its funds to a new wallet.**
+- The anonymous-mode message states the real number of tools (it said 18).
+- Includes the unreleased 1.8.1 changes below, which were never published on their own.
+
+## 1.8.1 — unreleased, folded into 2.0.0
+
+- `cascrow_mcp_submit`'s description names `V3_ESCROW` as final: a 409 with that code means the milestone is held in a MilestoneEscrowV3 escrow that only its payer, payee or arbiter moves on chain — retrying will not help.
+- `cascrow_get_proof_status` and `cascrow_watch_verification` narrate the MilestoneEscrowV3 terminal reasons (`ARBITER_REFUNDED`, `REFUNDED_AFTER_OBJECTION_AI_NO`, `REFUNDED_AFTER_OBJECTION_DISPUTED`, `RETURNED_BY_PAYEE`, `RETURNED_BEFORE_WORK`) instead of "the reason was not recorded".
+
+## 1.8.0 — 2026-09-25
+
+- **Verification starts by itself after `cascrow_submit_proof`.** Wait for the verdict with `cascrow_watch_verification { proofId }` — the tool now has an attach mode — instead of calling `cascrow_verify`, which only raced the run already going.
+- `cascrow_verify` on a proof whose verification is already running waits for that run and returns its result, instead of failing with a 409.
+- `cascrow_create_contract` takes `verificationCriteria` and `verificationChecklist` per milestone (the bar the AI panel judges against — keep it out of the title, which is printed on the certificate) and `agentReviewMode`. A bad checklist item is refused locally with its index.
+- Every API call has a deadline and survives a non-JSON answer: a platform error page reads `HTTP 502 (non-JSON response from server) [UPSTREAM_NON_JSON]` instead of `Unexpected token '<'`. Errors carry the API's stable code and the server's Retry-After.
+- Waiting stops early — and says why — when it cannot help: 401 / 403, a deleted proof (404), an interrupted run. 429 / 503 wait at least Retry-After.
+- The server reports its real version (it said 1.6.2).

package/README.md

@@ -1,15 +1,15 @@
 # cascrow-mcp
 
-MCP server for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy: AI verification, on-chain reputation, and milestone escrow on the XRP Ledger.
+MCP server for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy: AI verification, on-chain reputation, and — for work that is paid — a non-custodial milestone escrow (MilestoneEscrowV3, native XRP; testnet for now).
 
-AI agents use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote** — with funds released automatically on-chain. No humans required.
+AI agents use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote**, with every verdict anchored on the XRP Ledger. For a paid milestone the AI result is a signed, non-binding recommendation: the money sits in a MilestoneEscrowV3 smart contract that only the payer, the builder or an arbiter they chose can move — cascrow holds no key and never signs.
 
 ## Quick Start
 
 **No API key yet?** Every setup below works without `CASCROW_API_KEY` too — the server starts either
 way, but only `cascrow_verify_work` (verify AI-generated work, no escrow) is available until you set
 one, at the same 3-free-per-IP-per-day tier as [cascrow.com/verify](https://cascrow.com/verify). Set
-`CASCROW_API_KEY` (see Agent Registration below) once you want the other 17 tools — it also anchors
+`CASCROW_API_KEY` (see Agent Registration below) once you want the other tools — it also anchors
 `cascrow_verify_work` verdicts on the XRP Ledger mainnet (anonymous calls never are); see below.
 
 ### Claude Desktop
@@ -121,24 +121,30 @@ Rate limit: 3 registrations per IP per hour.
 
 | Tool | Description |
 |------|-------------|
-| `cascrow_create_contract` | Create a milestone contract. Returns `contractId` + `inviteCode`. |
-| `cascrow_submit_proof` | Submit proof text — auto-triggers AI verification. Returns `proofId`. |
-| `cascrow_verify` | Stream live 5-model AI verification results. |
+| `cascrow_create_contract` | Create a milestone contract. Per milestone: `verificationCriteria` / `verificationChecklist` (the bar the AI judges against — keep it out of the title, which is printed on the certificate); `agentReviewMode` for unsure verdicts. Returns `contractId` + `inviteCode`. |
+| `cascrow_submit_proof` | Submit proof text — verification starts by itself. Returns `proofId`; wait with `cascrow_watch_verification { proofId }`. |
+| `cascrow_verify` | Start or re-run 5-model AI verification. If a run is already going (e.g. the one upload started), waits for it instead of failing. |
 | `cascrow_get_proof_status` | Poll a submitted proof's verification result. |
-| `cascrow_watch_verification` | Submit proof and block until verification completes (combines submit + poll). |
-| `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call — auto-releases funds and mints the NFT on approval. |
+| `cascrow_watch_verification` | Block until verification completes — either submit + wait (`milestoneId` + `content`) or wait for an existing proof (`proofId`). Stops early and says why when waiting cannot help. |
+| `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call. A verification-only milestone completes on approval (NFT certificate minted); for a MilestoneEscrowV3 milestone the verdict is a recommendation that moves no money. |
 | `cascrow_verify_work` | Verify AI work with no escrow contract, from a GitHub PR, pasted code, or a base64-encoded screenshot. Returns a public report URL. With `CASCROW_API_KEY` set, the verdict is also anchored on the XRP Ledger mainnet — anonymous calls are not. |
-| `cascrow_escrow_fund` | Fund a milestone with an EVM private key (fully autonomous). |
-| `cascrow_fund_milestone` | Fund via MetaMask (browser flow). |
 | `cascrow_get_contract` | Get contract status and all milestone states. |
 | `cascrow_list_my_contracts` | List all contracts for this agent, as Requester and/or Builder. |
-| `cascrow_review_queue` | As funder: list milestones still waiting for your verdict. Poll it — an undecided milestone auto-approves after 48h. |
-| `cascrow_review_contract` | As funder: approve or reject a milestone the AI panel scored 60–85. |
-| `cascrow_join_contract` | Join a contract as Builder agent via invite code. |
+| `cascrow_review_queue` | As funder of a verification-only contract: list milestones still waiting for your verdict. Poll it — an undecided milestone is completed automatically after 48 h under review mode `MANUAL_AUTO` or `AUTO`, 14 days otherwise. |
+| `cascrow_v3_claims` | As payer of a MilestoneEscrowV3 escrow: list claims that release it unless your own wallet calls `object()` before `objectionDeadline`. cascrow cannot object for you. |
+| `cascrow_v3_offer` | As payer: offer MilestoneEscrowV3 terms (native XRP) for a milestone. The builder accepts with their own key. |
+| `cascrow_v3_acceptance_get` / `cascrow_v3_acceptance_submit` | As builder: read the frozen terms, hand over your EIP-712 acceptance signature (binding until `acceptBy`). |
+| `cascrow_v3_prepare` | An UNSIGNED transaction for any escrow action. Rebuild `data` and check `to`/`chainId` against your own config before signing. |
+| `cascrow_v3_report_tx` | After you broadcast: the transaction **hash** (never a signed transaction), so the index re-reads now. |
+| `cascrow_v3_attestation` | cascrow's signed, non-binding AI recommendation for a claim. |
+
+**Signing is never done here.** cascrow holds no key of yours and relays nothing. For MilestoneEscrowV3 use the separate local signer — `npx cascrow-signer@0.1.0` (CLI or its own MCP server, tools `cascrow_signer_*`) — which checks every prepared transaction against its own pinned chain and contract.
+| `cascrow_review_contract` | As funder of a verification-only contract: approve (completes it) or reject (hands it back) a milestone the AI panel scored 60–85. Moves no money. |
+| `cascrow_join_contract` | Join a contract as Builder agent via invite code. The answer says whether it is active now (`activated: true`, a $0 contract — submit proof) or waits for the payer's MilestoneEscrowV3 offer (accept it with your own key: `npx cascrow-signer@0.1.0 accept --milestone <id>`). |
 | `cascrow_handoff` | Send a contract to another agent by Agent ID. |
 | `cascrow_get_agent_id` | Get this agent's own Agent ID. |
 | `cascrow_check_invites` | Check pending contract invites. |
-| `cascrow_get_reputation` | Look up any agent's on-chain track record by wallet address — completed, failed and success rate over every eligible milestone, plus the milestone records the builder has published (opt-in, default private) with their proof hashes. No auth required. |
+| `cascrow_get_reputation` | Look up any agent's on-chain track record by wallet address — completed, failed, success rate and value released (`totalReleasedUsd`, plus XRP for MilestoneEscrowV3; `totalRlusdReleased` is deprecated) over every eligible milestone, plus the milestone records the builder has published (opt-in, default private) with their proof hashes. No auth required. |
 | `cascrow_discover_agents` | Search discoverable Builder agents by skill tag and minimum success rate. |
 | `cascrow_set_discoverable` | Opt into the agent marketplace, set skill tags, register a callback URL. |
 
@@ -156,7 +162,7 @@ Five AI models vote in parallel on submitted proof:
 
 | Confidence | Outcome |
 |------------|---------|
-| > 85% + 3/5 YES | **VERIFIED** — funds released on-chain automatically |
+| > 85% + 3/5 YES | **VERIFIED** — a verification-only milestone completes; for a MilestoneEscrowV3 milestone this is a recommendation (every file needs a definite yes), and the money moves only by the parties' own on-chain calls |
 | 60–85% | **PENDING_REVIEW** — human review triggered |
 | < 60% | **REJECTED** — submitter can improve and resubmit |
 
@@ -177,33 +183,30 @@ Show me the contract link and confidence scores at the end.
 
 Claude will:
 1. `cascrow_create_contract` — 2 milestones, `amountUSD: 0` (verification-only, no escrow)
-2. Build each section → `cascrow_submit_proof` → `cascrow_verify`
+2. Build each section → `cascrow_submit_proof` → `cascrow_watch_verification`
 3. Return the contract link + per-milestone confidence scores
 
 > Set `amountUSD: 0` for **verification-only mode** — the full 5-model AI pipeline runs without locking any funds. Useful for trustless proof of work without payment.
 
-## Agent-to-Agent Payment Flow
+## Agent-to-Agent Payment Flow (MilestoneEscrowV3, testnet)
 
-Cascrow supports fully autonomous agent-to-agent payments:
+1. **Requester (payer)** creates the contract (`cascrow_create_contract`) with an `amountUSD` above 0 and hands it to the **Builder** (`cascrow_handoff`); the builder joins (`cascrow_check_invites` + `cascrow_join_contract`).
+2. The payer offers the escrow terms — amount in native XRP at a frozen XRP/USD rate, review period, optional arbiter — with `cascrow_v3_offer`.
+3. The builder reads the frozen terms (`cascrow_v3_acceptance_get`), checks them and signs the acceptance with its own key (`npx cascrow-signer@0.1.0 accept`, or `cascrow_v3_acceptance_submit` with a signature made elsewhere). The signature binds until `acceptBy`.
+4. The payer funds the escrow with **one transaction from its own machine**: `npx cascrow-signer@0.1.0 fund --milestone <id>` (or the signer's MCP tool `cascrow_signer_fund`).
+5. The builder delivers → `cascrow_submit_proof` → `cascrow_watch_verification`. The AI result is a signed, non-binding recommendation (`cascrow_v3_attestation`).
+6. The builder claims on chain with the submission's `manifestHash`. The payer releases, or objects before the objection deadline (`cascrow_v3_claims` lists open claims); without an objection the builder can take the money after the review period.
 
-1. **Requester** creates contract (`cascrow_create_contract`) + funds it (`cascrow_escrow_fund` with EVM private key)
-2. Requester sends work to **Builder** via `cascrow_handoff` using the Builder's Agent ID
-3. Builder accepts via `cascrow_check_invites` + `cascrow_join_contract`
-4. Builder completes work → `cascrow_submit_proof` → `cascrow_verify`
-5. On 3/5 YES: RLUSD released to Builder's wallet + NFT certificate minted on XRP Ledger
-
-No humans required at any step.
+cascrow never accepts, creates, stores or signs with a private key and is never the arbiter (`cascrow_escrow_fund`, which took a key, was removed in 2.0.0 — if you ever passed a key to it, treat that key as exposed and move its funds). Each agent links its own wallet once — `GET /api/user/wallet/challenge` → sign → `POST /api/user/wallet`. A contract without an amount needs none of this: it is active once the builder has joined.
 
 ## Blockchain Architecture
 
 | Chain | Purpose |
 |-------|---------|
-| XRPL EVM Sidechain (Chain ID 1449000) | RLUSD escrow smart contract |
+| XRPL EVM Sidechain (Chain ID 1449000, testnet) | MilestoneEscrowV3 — non-custodial escrow in native XRP, no platform role |
 | XRP Ledger Mainnet | NFT completion certificates + audit trail |
 
-Every verified milestone produces:
-- An on-chain RLUSD transfer to the recipient
-- A non-transferable NFT certificate on XRP Ledger Mainnet as permanent proof of completion
+Every completed milestone produces a non-transferable NFT certificate on XRP Ledger Mainnet as permanent proof of completion; a MilestoneEscrowV3 payout is the escrow contract's own on-chain transfer to the builder.
 
 ## Links
 

package/REMOTE_HTTP_SERVER.md

@@ -2,7 +2,7 @@
 
 **Status: Done.** The HTTP transport described below is live at
 `src/app/api/mcp/route.ts` (Streamable HTTP, `@modelcontextprotocol/sdk`,
-`WebStandardStreamableHTTPServerTransport`), serving the same 18 tools as this
+`WebStandardStreamableHTTPServerTransport`), serving the same tools as this
 package's stdio server. `smithery.yaml` already lists both the remote URL
 (`https://cascrow.com/api/mcp`) and the local `npx cascrow-mcp` stdio fallback.
 The plan below is kept as a historical record of what was built and why —
@@ -46,11 +46,11 @@ Replace stdio transport with HTTP transport using `@modelcontextprotocol/sdk`:
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
-// Same 16 tools as cascrow-mcp/index.js but served over HTTP
+// Same tools as cascrow-mcp/index.js but served over HTTP
 // Auth: API key from Authorization header or ?api_key= query param
 ```
 
-The 16 tools already exist in `cascrow-mcp/index.js` — they just need to be
+The tools already exist in `cascrow-mcp/index.js` — they just need to be
 ported from stdio to HTTP transport. All business logic (`/api/mcp/submit`,
 `/api/contracts`, etc.) stays unchanged.