Thinking Agent — Stage 6: True Cosine CRAG & Bidirectional x402 Monetization

Stage 6 replaces Stage 4's keyword-scored CRAG with true cosine-similarity retrieval, adds an Algorithmic FinOps governance layer that halts runaway multi-step LLM chains before they exceed a budget ceiling, and wires bidirectional x402 stablecoin monetization into both the MCP server (paywalled tools) and the agent client (a reciprocal shield for its own LLM cycles).

This README reflects what actually worked, end to end, after a long empirical debugging pass against the live Xpay Staging Gateway — not just the intended design. Where the real facilitator's behavior differed from its own documentation, that's called out explicitly, because it mattered.

1. Prerequisites

• Everything from Stage 5 (Supabase, Redis, uv) still applies and is unchanged.

• A fresh, disposable testnet-only wallet — see §3.

• Test USDC on Base Sepolia from the Circle faucet — see §3.

• eth-account and httpx installed in agent_client; httpx in mcp_server; redis in mcp_server (new in this stage, for cross-process FinOps telemetry — previously mcp_server had zero Redis/DB dependency by design, since it holds no LLM or cache of its own).

uv add --package agent-client eth-account httpx
uv add --package mcp-server httpx redis
uv lock
uv sync

Related MCP server: FinClaw

2. Apply the code changes

This delivery is a set of new modules plus precise patches against the existing Stage 5 files — see INTEGRATION_STAGE6.md for the exact diffs against server.py, client.py, and app.py. New standalone files (drop in as-is):

mcp_server/src/mcp_server/x402_middleware.py
mcp_server/src/mcp_server/cosine_crag.py
mcp_server/src/mcp_server/finops_governance.py
agent_client/src/agent_client/wallet.py
agent_client/src/agent_client/x402_client.py
agent_client/src/agent_client/finops_governance.py
analysis_dashboard/src/analysis_dashboard/finops_tools.py

3. Generate and fund a wallet

A wallet is not something any service issues you — it's a private/public key pair you generate locally, with no signup required:

uv run --package agent-client python -c "from eth_account import Account; a = Account.create(); print('WALLET_PRIVATE_KEY=' + a.key.hex()); print('WALLET_ADDRESS=' + a.address)"

Paste both lines into .env. Then fund the address (never the private key — nobody but you should ever see that) at https://faucet.circle.com/, selecting Base Sepolia. Confirm it landed at https://sepolia.basescan.org/address/<your address> before running anything — every x402 error this stage's debugging log walks through, right up until the very last one, turned out to be a real, fixable bug; the wallet needing funds was the one genuinely external precondition.

4. Configure .env

Append everything in .env.stage6.additions to your existing .env. Fields worth understanding rather than blindly copying:

5. Run (same three terminals as before)

# Terminal 1
uv run --package mcp-server start-server

# Terminal 2
uv run --package agent-client start-agent

# Terminal 3
uv run --package analysis-dashboard streamlit run analysis_dashboard/src/analysis_dashboard/app.py

6. What a fully working run looks like

[X402][LEDGER] challenge_received | ...
[X402] Signed transferWithAuthorization | from=0x... to=0x...
[X402][LEDGER] facilitator_verify | verified: True
[SERVER] Reflection tool invoked...
[SERVER] Running CRITIC pass 1/2 ...
[CLIENT] MCP Sampling request | request_id=0
[CLIENT] [CACHE][TIER1] semantic_cache_miss | ... LLM call executed
[SERVER] Critic evaluation complete — is_sufficient=False | N problem(s) found.

The signal that everything is actually working — not just verifying — is that the server's own Critic/Corrector log lines appear with real content, not a JSON 402 blob. If corrected_answer in the final tool output is itself a stringified 402_payment_required challenge, the reciprocal sampling shield is enabled and firing against your own server — check X402_SHIELD_SAMPLING_ENABLED.

7. Known limitations of this delivery

• No live network access existed in the sandbox this was built in, so nothing here was tested against a real facilitator by me directly — every fix in this stage came from iterating against your live logs, turn by turn, against the real https://facilitator.xpay.sh.

• finops_compliance_audit.json is written automatically at the end of each agent_client run (export_x402_ledger()); regenerate it after a fully successful settlement for a submission-ready, genuinely live-captured trace rather than the placeholder originally shipped.

• No screenshots are included — capture the dashboard's 💵 FinOps tab (wallet balance, spend velocity, chronological x402 audit stream) after a real successful run, with a visible system clock, per the task's requirement.

• The reciprocal sampling shield (X402_SHIELD_SAMPLING_ENABLED=true) is implemented and correct in isolation but will cause every sampling call in the reflection loop to fail with a 402 in this single-server demo, since the server has no code path to pay a second, nested challenge — see REFLECTION_STAGE6.md and the settings docstring for the full reasoning. It's a real, working capability that simply isn't the right thing to enable against your own trusted server.