savant-code 0.0.19 → 0.0.20

package/coding-standards/x402.md

@@ -1,227 +0,0 @@
-# x402 — Agent Payment Standard
-
-> **Status:** DRAFT v0.1.0
-> **Companion to:** ECHO.md v0.1.0
-> **Applies to:** Any ECHO-compliant agent that makes or receives HTTP requests
-> **Transport:** HTTP-native (no new ports, no extra round trips beyond standard 402 challenge/response)
-
----
-
-## What is x402?
-
-x402 is an open standard for **internet-native payments over HTTP**. A server returns `402 Payment Required` with
-payment instructions, the client signs a payment, the server verifies + settles, then the response goes through. No
-accounts. No subscriptions. No API keys to rotate. Just a payment per request.
-
-The protocol is **network-agnostic** (EVM, SVM/Solana, Stellar), **token-agnostic** (stablecoins, native tokens, future
-fiat), and **scheme-agnostic** (`exact` for fixed amounts, `upto` for capped usage, `batch-settlement` for high-volume
-APIs).
-
----
-
-## Why Agents Need It
-
-Most agent API access today runs on one of three models, all bad:
-
-1. **Flat subscriptions** — pay $X/month regardless of usage
-2. **API keys with prepaid credits** — friction, expiration, manual top-up
-3. **Free tiers with rate limits** — work for testing, die in production
-
-x402 gives the fourth model: **pay per call, in crypto, with no account**. A research agent can call 100 paid endpoints
-in a session and only pay for what it actually used. A skill author can publish a paid skill and receive 95% of every
-call's revenue, settled on-chain.
-
-For a multi-agent system like yours (NOVA + Mya + Vera + Savant swarm), x402 is the missing primitive that lets agents
-*transact* with each other and with the open web.
-
----
-
-## When an Agent Should Use x402
-
-Use x402 when:
-
-- Calling a paid external API (research, market data, image gen, etc.) where the provider supports it
-- Selling agent services (a Vera "DEX arbitrage scanner" skill) to other agents
-- Calling another agent in the swarm that exposes a paid endpoint
-- Routing a request through a *facilitator* that batches and settles
-
-Do **NOT** use x402 for:
-
-- Free public APIs (CoinGecko, Kraken, public EVM RPCs) — pay nothing, no 402
-- Internal agent-to-agent calls inside the same process/host — direct function calls
-- Bulk data transfers where the cost-per-call math doesn't work — negotiate a flat rate instead
-
----
-
-## Flow (the parts an agent cares about)
-
-```text
-1. Client makes HTTP request
-2. Resource server responds 402 with PAYMENT-REQUIRED header (base64 PaymentRequired)
-3. Client selects a PaymentRequirement, signs a PaymentPayload
-4. Client retries with PAYMENT-SIGNATURE header
-5. Server verifies (locally or via facilitator) — settle (on-chain) — responds 200
-6. 200 response includes PAYMENT-RESPONSE header (base64 SettlementResponse)
-```
-
-The agent's job is steps 3-4 (sign + retry) and parsing the headers in step 6. Everything else is the server's concern.
-
----
-
-## Reference Implementation (Python)
-
-The `x402` Python package wraps the OpenAI SDK. Install once per agent venv.
-
-```bash
-pip install x402
-```
-
-### Making a paid call (fetch client)
-
-```python
-from x402.clients.httpx import x402HttpxClient
-import httpx
-
-# Wallet signer — keep the private key in your .env, never in code
-wallet = load_wallet_from_env("AGENT_WALLET_PRIVATE_KEY")
-
-client = x402HttpxClient(account=wallet)
-
-# Make the call — the client handles 402 automatically
-response = client.get("https://paid-api.example.com/weather?city=sf")
-
-# response is the 200 OK, the client already paid
-data = response.json()
-```
-
-The x402HttpxClient transparently:
-
-- Detects 402 responses
-- Parses the PAYMENT-REQUIRED header
-- Signs a PaymentPayload
-- Retries with PAYMENT-SIGNATURE
-- Returns the final 200
-
-### Exposing a paid endpoint (server side)
-
-If you're publishing a paid skill or API:
-
-```python
-from x402.servers.fastapi import X402Middleware
-from fastapi import FastAPI
-
-app = FastAPI()
-app.add_middleware(
-    X402Middleware,
-    pay_to_address="0xYourBaseAddress",
-    network="base-mainnet",
-    routes={
-        "GET /scanner/run": {
-            "price": "$0.05",      # exact scheme, $0.05 USDC per call
-            "description": "DEX arbitrage scanner — top 10 opportunities",
-        },
-        "POST /scanner/scan": {
-            "price": "$0.10",
-            "description": "Custom DEX scan with user-supplied parameters",
-        },
-    },
-)
-
-@app.get("/scanner/run")
-async def run_scanner():
-    # your skill logic here
-    return {"opportunities": [...]}
-```
-
----
-
-## Security Rules (Law 6 / Law 12 extensions)
-
-These extend ECHO Laws 6 (no type safety shortcuts) and 12 (no sensitive data in logs) into the payment domain:
-
-1. **Wallet keys live in `.env` only.** Never in code, never in version control, never in skill prompts. Use the agent's
-   existing secret-management path.
-2. **Never auto-approve payments above a per-call threshold.** Default cap: **$0.50 per call** for autonomous calls.
-   Higher requires explicit user approval (ECHO Level 1/2 behavior).
-3. **Daily spend cap mandatory.** Default: **$5.00/day** total. Track cumulative spend in `logs/payments.log`.
-4. **Receipt verification on every 200.** Parse the `PAYMENT-RESPONSE` header, verify the settlement tx hash, log the
-   receipt. Settlement without a verifiable receipt = treat as failed payment, do not deliver the resource.
-5. **No 402 retry storms.** If a payment fails (insufficient funds, RPC error, signature invalid), back off. Do not
-   auto-retry more than 2 times. Surface the failure to the user.
-6. **Facilitator choice is auditable.** When you settle via a facilitator, log the facilitator URL + tx hash together.
-   The recipient (operator) can verify the chain independently.
-7. **Facilitator = no fund movement without intent.** Per x402 spec: facilitators verify and settle, but cannot move
-   funds beyond what the client's signed payload authorizes. Trust-minimizing by design.
-
----
-
-## Logging (Law 8 / Law 12)
-
-Every x402 transaction must be logged with:
-
-```text
-[timestamp]   direction=out|net
-              scheme=exact|upto|batch
-              network=base-mainnet|solana-mainnet|...
-              amount=<value> <token>
-              resource=<url path>
-              tx_hash=<on-chain hash>
-              facilitator=<url|none>
-              status=ok|failed|<error>
-```
-
-Storage: `logs/payments.log` in the agent's home (NOVA: `~/.hermes/logs/payments.log`, Mya: `~/.openclaw/logs/payments.log`).
-
-Per Law 12: never log the wallet address *and* the tx hash in the same line if you can avoid it. Operators get one or
-the other in plain logs; the linked view lives in a separate `payments-ledger.json` that's treated as PII.
-
----
-
-## Per-Agent Defaults
-
-| Agent | Wallet env var | Per-call cap | Daily cap | Auto-approve below |
-|---|---|---|---|---|
-| **NOVA** (`~/.hermes/`) | `NOVA_WALLET_PRIVATE_KEY` | $0.50 | $5.00 | $0.10 |
-| **Mya** (`~/.openclaw/`) | `MYA_WALLET_PRIVATE_KEY` | $0.50 | $5.00 | $0.10 |
-| **Vera** (CLI) | `VERA_WALLET_PRIVATE_KEY` | $1.00 | $25.00 | $0.50 |
-| **Savant sub-agents** | per-profile | $0.10 | $1.00 | $0.01 |
-
-Override per-call via the user's explicit approval. Defaults exist to prevent runaway spending during autonomous (Level
-3) operation.
-
----
-
-## When NOT to Use x402
-
-This is just as important as when to use it. Skip x402 when:
-
-- **The endpoint doesn't return 402.** x402 clients are designed to fall through to a normal response if 402 is absent,
-  but you should not route paid-looking calls through x402 if the server doesn't actually support it. That's a waste of
-  a signature.
-- **A subscription would be cheaper.** If you're calling the same endpoint > 1000x/day, x402 per-call fees (gas +
-  facilitator) may exceed a flat rate. Negotiate.
-- **The data is sensitive + payment is on-chain.** x402 payments are public on the blockchain. If the resource request
-  itself reveals trade secrets (e.g., a paid oracle for proprietary strategies), the on-chain payment history leaks the
-  pattern. Use private channels.
-- **The agent has no budget.** If a wallet is unfunded, x402 will fail at signature time. Surface "wallet empty" as a
-  clean error, don't retry.
-
----
-
-## Quick Reference
-
-| What | Where |
-|---|---|
-| Python SDK | `pip install x402` |
-| TypeScript SDK | `npm install @x402/core @x402/evm @x402/fetch` |
-| Spec | https://github.com/x402-foundation/x402/tree/main/specs |
-| EVM contracts | `contracts/evm/` in the x402 repo |
-| Facilitators | x402scan.com, Agentic.Market, Pay.sh |
-| Wallets (test) | https://faucet.base.org (Base Sepolia), https://solfaucet.com |
-
----
-
-## Changelog
-
-- **v0.1.0** (draft, 2026-06-15) — Initial standard. Mirrors ECHO.md structure (Laws, Honest Assessment, Audit
-  Checklist). Awaiting first x402-enabled skill before promoting to v1.0.

package/common/README.md

@@ -1,41 +0,0 @@
-<!-- markdownlint-disable MD041 -->
-<img src="../assets/banner.png" alt="@savant-code/common — Shared types, tool definitions, utilities" width="650" />
-
-# @savant-code/common
-
-Shared types, tool definitions, and utilities used across the Savant runtime (Zod schemas, MCP client, AI SDK helpers,
-auth, billing/Postgres).
-
-[![License](https://img.shields.io/badge/License-Apache_2.0-%23000000?style=flat-square&logo=apache&logoColor=%2300fbff)](../LICENSE)[![ECHO](https://img.shields.io/badge/ECHO-v0.2.0-%23000000?style=flat-square&logo=github&logoColor=%2300fbff)](../ECHO.md)[![Status](https://img.shields.io/badge/Status-internal-%23ff9500?style=flat-square&logo=github&logoColor=%2300fbff)](../README.md)
-
-## Purpose
-
-`@savant-code/common` is the **cross-workspace source of truth** for shared types and tool wiring (per ECHO Law 13).
-Contains tool schemas for `read_files`, `write_file`, `str_replace`, `run_terminal_command`, `web_search`,
-`code_search`, MCP client, AI SDK integrations, and the analytics/billing/Postgres adapters. No agent imports anything
-from another workspace without going through `@savant-code/common`.
-
-## Quick Start
-
-```bash
-# From the repo root
-bun install
-
-# Type-check common
-bun --cwd common typecheck
-```
-
-For full Quick Start including how the CLI runtime consumes `common/`, see the [root README](../README.md#repo-map).
-
-## License
-
-[Apache-2.0](../LICENSE) — see [LICENSE](../LICENSE) for full text.
-
----
-
-<div align="center">
-
-_Part of the [savant-code/savant-code monorepo](https://github.com/savant0x/savant-code), governed by the [ECHO Protocol v0.2.0](../ECHO.md)._
-
-**Savant** • 2026
-</div>

package/common/common_exit

@@ -1 +0,0 @@
-0

package/common/package.json

@@ -1,45 +0,0 @@
-{
-  "name": "@savant-code/common",
-  "version": "0.0.1",
-  "description": "Common utilities for Savant-Code",
-  "private": true,
-  "type": "module",
-  "exports": {
-    "./*": {
-      "bun": "./src/*.ts",
-      "import": "./src/*.ts",
-      "types": "./src/*.ts",
-      "default": "./src/*.ts"
-    }
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit -p .",
-    "test": "bun test"
-  },
-  "sideEffects": false,
-  "engines": {
-    "bun": "1.3.11"
-  },
-  "dependencies": {
-    "@auth/drizzle-adapter": "^1.8.0",
-    "@modelcontextprotocol/sdk": "^1.18.2",
-    "@types/pg": "^8.11.10",
-    "@types/readable-stream": "^4.0.18",
-    "@types/seedrandom": "^3.0.8",
-    "ai": "^5.0.52",
-    "ignore": "5.3.2",
-    "lodash": "4.17.23",
-    "next-auth": "^4.24.11",
-    "partial-json": "^0.1.7",
-    "pg": "^8.14.1",
-    "posthog-node": "^5.8.0",
-    "readable-stream": "^4.7.0",
-    "seedrandom": "^3.0.5",
-    "stripe": "^16.11.0",
-    "zod": "^4.2.1",
-    "zod-from-json-schema": "0.4.2"
-  },
-  "devDependencies": {
-    "@types/parse-path": "^7.1.0"
-  }
-}