Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(prompts): retire parity order 022 now that safe paid retries, POST-body hashing and the MCP use cases are verified

nirholas0063ca9ff4bd
diff --git a/prompts/finish/022-parity-08-mcp-use-cases-and-safe-retries.md b/prompts/finish/022-parity-08-mcp-use-cases-and-safe-retries.md
deleted file mode 100644
index 71a0ba9d6..000000000
--- a/prompts/finish/022-parity-08-mcp-use-cases-and-safe-retries.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# parity 08: MCP docs as tool-call sequences, and a paid call that never tells a buyer to pay twice
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first, then [_context/parity-00-CONTEXT.md](_context/parity-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write, git push or a production deploy, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. Where this order hits one, it says so, and you batch every such ask into ONE message after everything else is done.
-- Never name Competitor X in anything you commit. If a reference is unavoidable, write "Competitor X".
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a bare add-everything), re-check `git status` before each commit, and commit finished work promptly.
-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
-
-## Why this matters
-
-Two patterns from Competitor X's developer docs that we lack:
-
-1. **Use cases written as the tool calls an agent makes, in order** ("Launch a token: check readiness, launch, get the page URL"). An agent learns a workflow faster from the call sequence than from a tool list. `docs/mcp.md` has no use-case section (its nearest is "Example Claude workflow"), although `api/_mcp/prompts.js` already encodes 17 guided workflows (`get-started`, `create-agent`, `setup-wallet`, `trade`, `launch-token`, `hire-agent`, `sell-a-skill`, `review-costs`, `setup-automations`, `setup-dca`, `explore-marketplace`, `explore-x402`, `earn-yield`, `perps`, `predictions`, `embed-avatar`, `generate-3d`).
-2. **Errors after payment that say the buyer is safe to retry.** Their paid launch returns `retrySafe: true` on any failure after payment and makes the retry idempotent on the payment proof.
-
-What happens on our x402 v2 stack today (`paidEndpoint` in `api/_lib/x402-paid-endpoint.js`, from a code read on 2026-09-30; re-verify):
-
-- Default mode runs the handler before settling, so a handler failure charges nothing. Good.
-- **Streaming mode settles first**, and the spent-payment claim runs inside `settleAndBuildResponse`. If the handler then throws, the buyer gets a generic 500 that does not say they paid, and retrying with the same payment header gets 409 `payment_replayed` telling them to pay again. They were charged and got nothing.
-- If settle succeeds and the SIWX grant write fails, the answer is 502 `siwx_record_failed`, which also does not say the buyer paid.
-- The payment-identifier idempotency hash (`api/_lib/x402/payment-identifier-server.js`) hashes `body: null` because a comment assumes paid routes are GET-only, yet POST paid routes exist (`api/x402/service.js` and others), so two different POST bodies under one payment identifier can collide.
-- `retry_safe` / `retrySafe` appears nowhere in `api/x402` or `api/_lib/x402*`.
-
-## Step 0: re-derive the current state
-
- grep -rn "retry_safe\|retrySafe" api/x402 api/_lib/x402* api/_lib/x402 | head
- grep -n "settleAndBuildResponse\|siwx_record_failed\|payment_replayed\|stream" api/_lib/x402-paid-endpoint.js | head -30
- grep -n "body: null\|GET-only" api/_lib/x402/payment-identifier-server.js api/_lib/x402-paid-endpoint.js
- grep -rln "paidEndpoint(" api/x402 | xargs grep -ln "method.*POST\|methods.*POST" | head
- grep -n "^## " docs/mcp.md
-
-## Tasks
-
-1. **Never ask a paid buyer to pay twice.** In streaming mode, when the handler fails after settlement, record the failure against the spent payment and let the same payment header re-run the handler (once, or a small bounded number of times within a window) instead of answering `payment_replayed`. The error response for any failure after settlement carries `paid: true`, `retry_safe: true`, the settlement transaction and a plain sentence ("You were charged; repeat this exact request with the same payment to get your result"). Apply the same fields to `siwx_record_failed`. Tests: a streaming handler that throws once then succeeds is retried with the same payment and returns the result without a second charge; a completed call replayed still returns 409 as today.
-2. **Hash POST bodies.** Include the request body in the payment-identifier idempotency hash for non-GET routes, fix the misleading comment, and test that two different bodies under one identifier do not share a cached response.
-3. **Document it.** `docs/x402.md` and the API reference's error table (`retry_safe`, `paid`) say what a buyer's client should do.
-4. **Use cases in `docs/mcp.md`.** A "Use cases" section: for each guided prompt in `api/_mcp/prompts.js`, the goal in one line and the ordered tool and resource calls the prompt drives, using the real tool names (derive them from the prompt definitions, not from memory). Mark each step that spends money. Add a check (a test or an extension of an existing MCP audit) that fails when a tool named in the section no longer exists, so the section cannot drift.
-
-## Definition of done
-
-- [ ] The streaming retry test and the replay test pass; a failure after settlement returns `paid: true` and `retry_safe: true` (test).
-- [ ] The POST-body idempotency test passes.
-- [ ] `docs/mcp.md` has a "Use cases" section covering every prompt, and the drift check fails when a named tool is removed (shown by a red run you then revert).
-- [ ] `npm test` passes for the touched suites; `npm run audit:docs` passes; changelog entry added.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| A route relies on the old replay behaviour | Keep 409 for completed calls; only failed-after-settle calls become retryable. Cover the route with a test. |
-| The settle sponsor is dry in production | Irrelevant to this order: everything here is proven under test. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house style: `type(scope): what changed and why a reader cares`).
-3. If every Definition of done line passes, delete this file in that same commit (`git rm prompts/finish/022-parity-08-mcp-use-cases-and-safe-retries.md`) and append a dated entry to [_context/parity-PROGRESS.md](_context/parity-PROGRESS.md) with the commit SHAs. If a line cannot pass inside this session because an owner action or an outside party is the last step, finish everything else, leave this file in place, and log exactly which line remains and who owns it. Never delete this file on a partial.
-4. Final report, in this order: what step 0 measured; what changed (file list with commit SHAs); evidence for each Definition of done line; the single batched owner message, if the order has a gate; one-line judgment calls. No trailing questions.
diff --git a/prompts/finish/_context/parity-00-CONTEXT.md b/prompts/finish/_context/parity-00-CONTEXT.md
index ef7a25cba..a3dcbf308 100644
--- a/prompts/finish/_context/parity-00-CONTEXT.md
+++ b/prompts/finish/_context/parity-00-CONTEXT.md
@@ -53,7 +53,7 @@ Verify in a real browser: `npm run dev` (port 3000; reuse it if another agent is
| 019 (retired 2026-10-08) | `/experiments`: public write-ups of what we tried and what the numbers said | none |
| [020](../020-parity-06-success-stories.md) | `/stories`: opt-in case studies with verifiable on-chain metrics | none |
| [021](../021-parity-07-three-fee-flow.md) | "Where every $100 goes" on `/three-token`, from the live split policies | none |
-| [022](../022-parity-08-mcp-use-cases-and-safe-retries.md) | MCP docs as tool-call sequences; `retry_safe` on every post-payment failure | none |
+| 022 (retired 2026-10-08) | MCP docs as tool-call sequences; `retry_safe` on every post-payment failure | none |
| [919](../919-parity-09-ship-and-publish.md) | Push, deploy, publish the `three-ws` CLI to npm | owner: push, deploy, npm publish |
| [920](../920-parity-10-community-skill-registry.md) | Pull community skills from external GitHub registries | owner: the source list names other projects |
| [921](../921-parity-11-directory-listings.md) | List `skill.md` in the Solana Foundation's awesome-solana-ai | owner: external PR |
diff --git a/prompts/finish/_context/parity-PROGRESS.md b/prompts/finish/_context/parity-PROGRESS.md
index ebba5435e..28c398332 100644
--- a/prompts/finish/_context/parity-PROGRESS.md
+++ b/prompts/finish/_context/parity-PROGRESS.md
@@ -64,3 +64,12 @@ Cross-session handoff for the `parity-` orders ([parity-00-CONTEXT.md](parity-00
- Validator: deleting `spend_usd` from the first entry made `npm run build:pages` exit 1 with `entry 0 (agent-launch-funnel): missing required field "spend_usd"`; restored, validates green, 14/14 unit tests pass.
- Browser (Vite on 3107, Playwright): `/experiments` and both `/docs/experiments-<slug>` pages at 375, 768 and 1440 px in dark and light, zero console errors and no horizontal overflow; each write-up shows all six template headings; the filter syncs `?status=` (running 1, concluded 1, killed shows its empty state with "Show all 2 experiments"); a forced empty index and a forced 500 render their designed states, the error state with a Retry button. The only console output was headless-GPU WebGL driver warnings.
- `npm run audit:links` passed. `npm run audit:docs` failed on 7 findings from other work committed today, fixed so it passes clean: `eaba66bc6` (README for `workers/agent-gateway`; order 045 still owns that worker's deploy files), `b86e0f1c9` (Oracle Desk `.env.example` force-added past the root `.env*` ignore so its README link resolves), `cc1e67273` (`/docs/grok` page entry), `b2a0e19a5` (four IBM Community drafts marked unpublished).
+
+## 2026-10-08: order 022, MCP use cases and safe paid retries (closed)
+
+- Step 0: no `retry_safe` in the wrapper. `api/_lib/x402/spent-payments.js` already carried the retry primitives (`claimPaidRetry`, `markFailedAfterSettle`, `paidFailureFields`; `c2e980f09`, `2a545b58f`) and migration `20260930180000_x402_spent_payments_paid_retry.sql` was applied, but `paidEndpoint()` never called them: a streaming handler failure after settle still answered a bare 500 and the same header then got `409 payment_replayed`; `siwx_record_failed` said nothing about payment; the idempotency hash still used `body: null` under a "GET-only" comment while dozens of paid routes are POST. `docs/mcp.md` had no Use cases section.
+- Shipped: `3c519d528` (wrapper wiring: streaming first attempts claim as running, a failure after settle records the proof as `failed_after_settle` and answers `paid: true`, `retry_safe`, the settlement and the plain sentence; the same header re-runs the exact request with no second verify or settle, bounded by `X402_PAID_RETRY_MAX` in `X402_PAID_RETRY_WINDOW_SECONDS`; a stale run is recoverable after `X402_PAID_RUNNING_STALE_SECONDS`; retries are bound to the payload hash; `siwx_record_failed` carries the same fields; pre-settle handler errors say `paid: false`; POST bodies are hashed and the ASR/TTS routes leave their pre-read bytes on `req.rawBody`), `a4cd24a81` (`docs/x402.md` "Paid endpoint failures and retries", API reference "Paid (x402) errors"), `563529648` (`docs/mcp.md` Use cases for all 17 prompts across the four servers, `tests/mcp-use-cases-doc.test.js`), `f4e6eeb54` (two changelog entries), `6e9ff57d5` (unrelated red suite fixed on the way: `tests/api/x402-pay-routing.test.js` mocked every fs read, so the payments config could not load `data/plans.json`).
+- Verified: 9 new paid-retry tests in `tests/api/x402-spent-payments.test.js` (throws once then succeeds with one verify and one settle; completed replay still 409; exhausted retries answer `409 payment_retries_exhausted` with `paid: true`; SIWX failure then completed retry; stale run recovered, live run in-flight; DB down says the retry could not be saved; retry against a different request refused) all fail on the old wrapper and pass now. POST-body test red with `body: null`, green now (stream and `rawBody` modes). Use-cases check red after renaming `oracle_coin` in `api/_mcp/tools/oracle.js` (reported "trade on mcp: names tool oracle_coin, which mcp does not publish"), reverted, green. 164 x402/siwx/AI suites (1,906 tests) green; `npm run audit:docs` clean; `npm run build:pages` validated the changelog (regenerated feeds not committed, as in 017).
+- Full `vitest run`: 35 files fail identically on the pre-session commit `6f23779a1` (branding, IMU clips, agent guard, `asset-host-liveness` flagging `tests/agent-earnings-board.test.js`, and others); none touch this work. `tests/apns.test.js` failed once under full-suite load and passes alone.
+- Not live until the next deploy (order 919). No migration needed.
+- Judgment calls: the run claim reuses the existing `retrying` outcome value rather than adding a new one, so no schema change; a handler that throws 402 after settle answers 500 with the paid fields, because a 402 would prompt a second payment.