@oobe-protocol-labs/sap-mcp-server 0.9.2 → 0.9.3

package/docs/18_PREMIUM_PLUGIN_RUNTIME.md

@@ -0,0 +1,108 @@
+# SAP MCP Premium Plugin Runtime
+
+SAP MCP includes a typed premium plugin contract for paid streams, webhooks, and enterprise capabilities. The goal is to let agents discover paid real-time capabilities, validate schemas before spending, and bind future x402/pay.sh receipts to a clear session id without exposing private provider code or user key material.
+
+This layer is deliberately strict:
+
+- no fake stream data
+- no implicit provider claims
+- no execution of plugin code from user input
+- no keypair bytes or provider secrets in public metadata
+- no x402 charge for invalid catalog/session planning requests
+
+## What Ships In The Open Server
+
+The public MCP server exposes free discovery and planning tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `sap_premium_plugin_catalog` | Lists premium plugin manifests, schemas, pricing contracts, provider readiness, and private plugin loader guidance. |
+| `sap_stream_catalog` | Lists stream capability contracts such as quote deltas, price ticks, registry events, and x402 ledger events. |
+| `sap_webhook_catalog` | Lists webhook delivery contracts and signed callback event types. |
+| `sap_premium_validate_plugin_manifest` | Validates a manifest before publication or enterprise loading. |
+| `sap_premium_plugin_template` | Builds a strict data-only manifest template for custom stream, webhook, or premium tool contracts. |
+| `sap_premium_session_start` | Creates an unpaid, bounded session plan for a premium capability. |
+| `sap_premium_session_status` | Reads in-memory premium session planning status. |
+
+Planning is free because it prevents wasted x402 attempts. Live premium delivery should be charged by the delivery rail once the provider is configured and the session is activation-ready.
+
+## Public HTTP Discovery
+
+The hosted server also exposes the same premium contracts as public, machine-readable JSON:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `/premium/catalog.json` | Full premium plugin catalog with provider readiness, pricing contracts, stream/webhook/tool capability ids, and private loader guidance. |
+| `/premium/streams.json` | Stream-only discovery for price ticks, quote deltas, registry events, and x402 ledger streams. |
+| `/premium/webhooks.json` | Webhook-only discovery for signed callback subscriptions and event delivery contracts. |
+
+These endpoints are discovery-only. They do not activate paid streams, execute private plugins, expose provider secrets, or return live provider data while readiness is false.
+
+## Provider Readiness
+
+Capabilities that depend on external streaming or webhook infrastructure include explicit provider env vars. If a required env var is missing, the capability returns:
+
+```txt
+status: requires-provider
+```
+
+Agents must not attempt paid activation when provider readiness is false. They should tell the user that the capability is contract-ready but not live on this deployment.
+
+## Built-In Premium Contracts
+
+The open catalog currently defines contract-level manifests for:
+
+| Plugin | Capability Examples |
+| --- | --- |
+| `sap-premium-market-data` | Jupiter quote deltas, Pyth price ticks, price threshold webhooks. |
+| `sap-premium-trading-streams` | Cross-DEX arbitrage scanning, volatility breakout detection, MEV-protected route optimization. |
+| `sap-premium-meme-radar` | New listing alerts, social sentiment, rugpull risk, DEX volume anomalies. |
+| `sap-premium-tech-fundamentals` | GitHub activity spikes, TVL changes, tokenomics analysis. |
+
+These are not mock feeds. They are typed contracts that become live only when the corresponding provider env is configured.
+
+## Private Enterprise Plugins
+
+Enterprise/private plugin code should live outside the public repository. The public server exposes the contract and validation path only.
+
+Supported loader env contract:
+
+```txt
+SAP_MCP_ENABLE_PREMIUM_PLUGINS=true
+SAP_MCP_PLUGIN_DIR=/secure/path/to/private/plugins
+SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY=false
+```
+
+Private plugins must provide manifests that pass:
+
+```txt
+sap_premium_validate_plugin_manifest
+```
+
+The runtime loads private manifests as data only from the configured directory.
+It does not execute plugin code supplied through MCP tool input. Private and
+enterprise manifests are not exposed in public catalog responses unless
+`SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY=true` is set deliberately, which
+should be reserved for authenticated or explicitly shared deployments.
+
+Use `sap_premium_plugin_template` to generate a starter manifest, then store the
+reviewed JSON in the private plugin subrepo under `manifests/`. Plugging and
+unplugging a private capability is a file/deploy operation: add or remove the
+manifest, validate it, and restart the hosted server with the intended env.
+
+## Agent Flow
+
+Recommended agent behavior:
+
+1. Call `sap_premium_plugin_catalog` with `includeSchemas:true`.
+2. Use `sap_stream_catalog` or `sap_webhook_catalog` to pick an exact capability id.
+3. Check `providerStatus` and the capability-level `providerReady` boolean.
+4. Call `sap_premium_session_start` to get a bounded session plan and estimated price.
+5. Activate only through the future paid delivery rail when provider readiness is true.
+6. Bind x402/pay.sh receipt, session id, plugin id, capability id, and event ids in the audit output.
+
+If the provider is not ready, stop cleanly and do not request payment.
+
+## Why This Matters
+
+Agent commerce needs more than one-shot tools. Trading agents, research agents, protocol monitors, and marketplace agents need fast event access with clear payment boundaries. SAP MCP premium plugins create the contract layer for that: typed schemas, bounded sessions, x402/pay.sh pricing, signed delivery, and enterprise provider isolation.

package/docs/BRANCH_AND_CI.md

@@ -0,0 +1,67 @@
+# Branch & CI/CD Strategy
+
+## Branch model
+
+```
+main          ← production-ready, tagged releases only
+develop       ← integration branch, PRs merge here first
+release/*     ← optional release prep branches (release/0.9.21)
+feature/*     ← short-lived feature branches → PR to develop
+hotfix/*      ← urgent fixes → PR to main + cherry-pick to develop
+```
+
+### Flow
+
+1. **Feature work**: branch from `develop` → PR back to `develop`
+2. **Release prep**: branch `release/<version>` from `develop` → bump version, CHANGELOG → merge to `main` + tag
+3. **Hotfix**: branch from `main` → fix → PR to `main` + tag → cherry-pick to `develop`
+4. **Desktop builds**: triggered automatically on tag push, binary artifacts published to GitHub Release
+
+## CI/CD workflows
+
+| Workflow | File | Triggers | Purpose |
+|---|---|---|---|
+| **CI** | `ci.yml` | push to main/develop, PR to main/develop | typecheck, lint, test, build, audit |
+| **CodeQL** | GitHub default setup | push, PR, weekly cron | security analysis (JS/TS + Actions) — configured in repo Settings → Security → Code security |
+| **Desktop Release** | `desktop-release.yml` | tag push, workflow_dispatch | build desktop binaries, publish to GitHub Release |
+
+### CI (`ci.yml`)
+
+- Runs on: Ubuntu (full test suite) + Windows (typecheck + lint + build only — Unix path tests skip)
+- Audit: `pnpm audit --audit-level high --prod` (production deps only)
+- Concurrency group cancels stale runs on same ref
+
+### Desktop Release (`desktop-release.yml`)
+
+- Triggers on: tag push (`*`) or manual dispatch
+- Matrix: macOS 15, Windows 2025, Ubuntu 24.04
+- Verify gates: typecheck + lint + test (Unix only) + build
+- Audit: production deps only, high severity
+- Publish job: downloads all 3 OS artifacts, generates SHA256 checksums, attaches to GitHub Release
+- Signing: optional (uses secrets if available, warns if unsigned)
+
+## Secrets management
+
+The `.gitignore` excludes:
+- `.env`, `.env.local`, `.env.*.local`
+- `*.pem`, `*.key`, `*.p8`, `*.p12`, `*.secret`
+- `*keypair*.json`, `*wallet*.json`, `id.json`
+- `keypairs/`, `wallets/`
+- `sap-mcp-premium-private/` (separate private repo)
+- `PRIVATE_VPS_DOCS/`, `*.private.md`
+
+GitHub Actions secrets (configured in repo settings):
+- `MACOS_CSC_LINK`, `MACOS_CSC_KEY_PASSWORD` — macOS code signing
+- `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID` — notarization
+- `WINDOWS_CSC_LINK`, `WINDOWS_CSC_KEY_PASSWORD` — Windows code signing
+
+## Tag convention
+
+Tags are plain version numbers: `0.9.21` (NOT `v0.9.21`).
+
+## Binary artifacts
+
+Desktop binaries are built by CI and published to GitHub Releases only.
+They are never committed to the repo. The `release/` directory is gitignored.
+
+Local builds: `pnpm run desktop:build` outputs to `release/desktop/`.

package/docs/README.md

@@ -64,6 +64,8 @@ For paid/write hosted tools, also configure the local `sap_payments` bridge. The
 - [Client Configs](user/04_CLIENT_CONFIGS.md)
 - [Payments: x402 And pay.sh](user/03_PAYMENTS_X402_PAYSH.md)
 - [Smithery And MCP Marketplaces](user/07_SMITHERY_AND_MARKETPLACES.md)
+- [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
+- [Premium Plugin Runtime](18_PREMIUM_PLUGIN_RUNTIME.md)
 
 ## What The Hosted Server Provides
 
@@ -91,8 +93,11 @@ Hosted paid tools use x402 and pay.sh:
 - value flows: fixed or percentage pricing only where it is operationally appropriate
 
 For agents that cannot replay x402 challenges natively, configure the local
-`sap_payments` MCP bridge and call `sap_payments_call_paid_tool`. The standalone
-helper remains available as a terminal/custom-wrapper fallback:
+`sap_payments` MCP bridge and call `sap_payments_call_paid_tool`. If a hosted
+builder returns an unsigned transaction, finalize it with
+`sap_payments_finalize_transaction` so the local signer previews, signs, and
+optionally submits without exposing keypair bytes. The standalone helper remains
+available as a terminal/custom-wrapper fallback:
 
 ```bash
 npx --yes --package @oobe-protocol-labs/sap-mcp-server sap-mcp-x402-paid-call \
@@ -113,6 +118,8 @@ Read these first:
 5. [Desktop GUI Wizard](user/06_DESKTOP_GUI_WIZARD.md)
 6. [Configuration And Wizard](03_CONFIGURATION_AND_WIZARD.md)
 7. [Endpoints And Clients](07_ENDPOINTS_AND_CLIENTS.md)
+8. [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
+9. [Premium Plugin Runtime](18_PREMIUM_PLUGIN_RUNTIME.md)
 
 ## Public Endpoints
 
@@ -122,6 +129,16 @@ Read these first:
 | `GET /docs` | This documentation site. |
 | `POST /mcp` | Streamable HTTP MCP endpoint for agents. |
 | `GET /server.json` | Public, secret-free machine-readable server metadata. |
+| `GET /premium/catalog.json` | Public premium plugin contracts, pricing models, schemas, and provider readiness. |
+| `GET /premium/streams.json` | Public premium stream contracts for future x402/pay.sh real-time delivery rails. |
+| `GET /premium/webhooks.json` | Public premium webhook contracts with signed delivery expectations. |
+
+Premium plugin authors can use `sap_premium_plugin_template` and
+`sap_premium_validate_plugin_manifest` to build strict data-only contracts,
+then deploy reviewed manifests from a private plugin directory. The public
+server never executes plugin code supplied through MCP input and does not expose
+private/enterprise manifests unless the operator explicitly enables private
+discovery.
 | `GET /smithery.config.schema.json` | Optional Smithery setup schema for free discovery, native x402 clients, and local `sap_payments` bridge users. |
 | `GET /.well-known/agent-card.json` | A2A-style agent card. |
 | `GET /.well-known/sap-mcp-wizard.json` | Wizard install descriptor for agents that cannot see local config. |

package/docs/magicblock-tools.md

@@ -24,21 +24,34 @@ additional configuration needed.
 
 ## Pricing
 
-Two tiers, priced in USDC base units (6 decimals):
+Hosted pricing is resolved centrally by `src/payments/pricing.ts` and returned
+as an x402/pay.sh challenge before the paid tool executes.
 
-| Tier | Price | Count | Tools |
-|------|-------|-------|-------|
-| READ | $0.01 | 14 | ER Router queries, health, auth, balances, swap quotes, mint checks, VRF result |
-| WRITE | $0.05 | 6 | deposit, transfer, withdraw, swap, initializeMint, VRF request |
+| Tier | Tools |
+|------|-------|
+| Free/readiness | MCP discovery, SAP skill bootstrap, payment readiness, transaction decode/preview |
+| Read-premium | ER Router queries, balances, swap quotes, mint checks, VRF result |
+| Builder | Deposit, transfer, withdraw, initialize mint, VRF request transaction builders |
+| Value-action | Public/private swap transaction builders and other value-moving actions |
 
-Every tool description includes its price. Every successful response
-includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
+Do not hard-code MagicBlock prices in agents. Call `sap_x402_estimate_cost` or
+the local `sap_payments_call_paid_tool` helper and enforce the user profile's
+`maxPriceUsd` / spend policy.
+
+Successful MagicBlock tool payloads intentionally do not report their own
+price. Hosted cost is authoritative only in the SAP MCP x402 challenge and the
+payment receipt returned by `sap_payments_call_paid_tool`.
+
+When a hosted MagicBlock builder returns an unsigned transaction, hosted SAP MCP
+remains non-custodial. Finalize the returned `transactionBase64` with the local
+`sap_payments_finalize_transaction` bridge. Do not call hosted
+`sap_sign_transaction`, create temporary signing scripts, or read keypair JSON.
 
 ---
 
 ## Tools (20 total)
 
-### ER Router (6 read-only — $0.01)
+### ER Router (6 read-only)
 
 | Tool | Description |
 |------|-------------|
@@ -49,7 +62,7 @@ includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
 | `magicblock_getBlockhashForAccounts` | Get a blockhash for a batch of accounts (max 100) |
 | `magicblock_getSignatureStatuses` | Check transaction confirmation status |
 
-### Private Payments — Meta & Auth (3 — $0.01)
+### Private Payments — Meta & Auth (3)
 
 | Tool | Description |
 |------|-------------|
@@ -57,14 +70,14 @@ includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
 | `magicblock_challenge` | Generate a challenge string for wallet auth |
 | `magicblock_login` | Exchange signed challenge for bearer token |
 
-### Private Payments — Balance (2 — $0.01)
+### Private Payments — Balance (2)
 
 | Tool | Description |
 |------|-------------|
 | `magicblock_balance` | Read base-chain SPL token balance |
 | `magicblock_privateBalance` | Read ephemeral-rollup SPL balance (requires auth) |
 
-### Private Payments — SPL Token Flows (3 — $0.05)
+### Private Payments — SPL Token Flows (3)
 
 | Tool | Description |
 |------|-------------|
@@ -74,24 +87,24 @@ includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
 
 ### Private Payments — Swap (2)
 
-| Tool | Price | Description |
-|------|-------|-------------|
-| `magicblock_swapQuote` | $0.01 | Get a swap quote between two SPL mints |
-| `magicblock_swap` | $0.05 | Build unsigned swap tx (public or private) |
+| Tool | Description |
+|------|-------------|
+| `magicblock_swapQuote` | Get a swap quote between two SPL mints |
+| `magicblock_swap` | Build unsigned swap tx (public or private) |
 
 ### Private Payments — Mint Init (2)
 
-| Tool | Price | Description |
-|------|-------|-------------|
-| `magicblock_initializeMint` | $0.05 | Build unsigned mint transfer queue init tx |
-| `magicblock_isMintInitialized` | $0.01 | Check if a mint's transfer queue exists |
+| Tool | Description |
+|------|-------------|
+| `magicblock_initializeMint` | Build unsigned mint transfer queue init tx |
+| `magicblock_isMintInitialized` | Check if a mint's transfer queue exists |
 
 ### VRF (2 — on-chain via @solana/web3.js)
 
-| Tool | Price | Description |
-|------|-------|-------------|
-| `magicblock_requestRandomness` | $0.05 | Build unsigned tx invoking request_randomness on the VRF program (Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz) |
-| `magicblock_getRandomnessResult` | $0.01 | Read the RandomnessRequest account on-chain to check fulfillment and retrieve random bytes |
+| Tool | Description |
+|------|-------------|
+| `magicblock_requestRandomness` | Build unsigned tx invoking request_randomness on the VRF program (Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz) |
+| `magicblock_getRandomnessResult` | Read the RandomnessRequest account on-chain to check fulfillment and retrieve random bytes |
 
 ---
 
@@ -126,21 +139,49 @@ Write tools return an unsigned transaction:
 Expected flow:
 
 1. Call the MagicBlock tool (e.g. `magicblock_deposit`) → get `transactionBase64`
-2. Sign with `sap_sign_transaction`
-3. Submit with `sap_submit_signed_transaction` to the RPC indicated by `sendTo`
+2. If the transaction came from hosted SAP MCP, call local
+   `sap_payments_finalize_transaction` with `confirm: true` and `submit: false`
+   for preview/sign, or `submit: true` after user approval.
+3. If the transaction came from local stdio SAP MCP, use
+   `sap_preview_transaction` → `sap_sign_transaction` →
+   `sap_submit_signed_transaction`.
+4. Record the signed transaction or submitted signature in the audit trail.
+
+Agents must not create temporary JavaScript signing scripts, read keypair JSON,
+or sign raw message bytes outside SAP MCP transaction tools.
+
+## Safety Guardrails
+
+SAP MCP fails closed for MagicBlock flows that live testing has shown to be
+unsafe:
+
+- `magicblock_swap` with `visibility: "private"` requires a valid
+  `destination`. The server rejects the request before contacting MagicBlock if
+  the destination is missing or invalid.
+- `magicblock_swap` with `visibility: "private"` and
+  `quoteResponse.outputMint = So11111111111111111111111111111111111111112`
+  is blocked. Mainnet testing found that private swaps outputting wSOL can leave
+  funds stuck in the Hydra mixer pool when shuttle delivery fails. Use
+  `visibility: "public"` for SOL output, or swap privately into a non-SOL SPL
+  token until MagicBlock provides shuttle delivery recovery.
+- `magicblock_transfer` requires `from`, `to`, `mint`, `amount`,
+  `visibility`, `fromBalance`, and `toBalance`. `amount` must be a positive
+  JavaScript-safe integer in token base units because the upstream API expects a
+  JSON number, not a string.
+- Private transfers require a bearer token from `magicblock_challenge` and
+  `magicblock_login`. Private SOL transfers may deliver wSOL, not native SOL;
+  agents should say that clearly before asking for confirmation.
 
 ---
 
 ## Response Format
 
-Every successful response is wrapped with pricing metadata:
+Successful tool responses are wrapped by SAP MCP:
 
 ```json
 {
   "success": true,
   "tool": "magicblock_deposit",
-  "priceUsd": "$0.05",
-  "priceBaseUnits": "50000",
   "data": { ... }
 }
 ```
@@ -163,4 +204,4 @@ Error responses:
 | `src/tools/magicblock-tools.ts` | 20 tool registrations with HTTP client |
 | `src/tools/__tests__/magicblock-tools.test.ts` | 10 smoke tests |
 | `src/tools/index.ts` | Barrel export |
-| `src/tools/register-tools.ts` | Registration call during server init |
+| `src/tools/register-tools.ts` | Registration call during server init |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "mcpName": "ai.oobeprotocol.sap.mcp/sap-mcp",
   "description": "Official MCP gateway for OOBE Protocol SAP — AI agents can interact with SAP identity, registry, reputation, tools, memory, payments, settlement, and proof-of-execution on Solana",
   "type": "module",
@@ -93,9 +93,11 @@
     "@solana/kit": "^5.5.1",
     "@solana/sysvars": "^5.5.1",
     "@solana/web3.js": "^1.95.0",
+    "@types/better-sqlite3": "^7.6.13",
     "@x402/core": "^2.17.0",
     "@x402/express": "^2.17.0",
     "@x402/svm": "^2.17.0",
+    "better-sqlite3": "^13.0.1",
     "bn.js": "^5.2.1",
     "bs58": "^6.0.0",
     "cli-spinners": "^3.4.0",
@@ -145,13 +147,15 @@
   "engines": {
     "node": ">=22.12.0"
   },
-  "packageManager": "pnpm@11.7.0",
   "overrides": {
-    "bigint-buffer": "file:vendor/bigint-buffer",
-    "esbuild": "^0.28.1",
+    "@hono/node-server": "2.0.10",
+    "body-parser": "1.20.6",
+    "fast-uri": "3.1.4",
+    "hono": "4.12.27",
     "langsmith": "^0.6.0",
+    "postcss": "8.5.18",
     "uuid": "^11.1.1",
-    "vite": "8.1.0",
     "ws": "^8.21.0"
-  }
+  },
+  "packageManager": "pnpm@11.7.0"
 }

package/server.json

@@ -3,7 +3,7 @@
   "name": "ai.oobeprotocol.sap.mcp/sap-mcp",
   "title": "SAP MCP Server | OOBE Protocol",
   "description": "Solana-native MCP gateway for SAP tools, DeFi, SNS identity, x402/pay.sh, and agent operations.",
-  "version": "0.9.2",
+  "version": "0.9.21",
   "websiteUrl": "https://mcp.sap.oobeprotocol.ai/",
   "repository": {
     "url": "https://github.com/OOBE-PROTOCOL/sap-mcp",
@@ -29,7 +29,7 @@
     {
       "registryType": "npm",
       "identifier": "@oobe-protocol-labs/sap-mcp-server",
-      "version": "0.9.2",
+      "version": "0.9.21",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.2"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.21"
         },
         {
           "type": "positional",

package/skills/README.md

@@ -55,10 +55,20 @@ or wants to compare this bundled MCP skill pack with the source SDK skills:
 ## Agent Behavior
 
 - Answer in the same natural language as the user's latest request.
-- Use `sap_list_all_agents` for current global SAP ecosystem agent lists.
-- Use `sap_discover_agents` only for protocol/capability-filtered discovery.
+- Use free exact/base SAP reads before paid discovery when possible:
+  `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
+  `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
+  compact `sap_list_agents` pages with `limit <= 20`.
+- Use `sap_discover_agents` for targeted hosted agent search by query, wallet,
+  PDA, protocol, capability, capability list, or x402 endpoint presence.
+- Use `sap_list_all_agents` for current global SAP ecosystem agent lists only
+  when the user needs more than the free compact orientation page, and continue
+  with `pagination.nextCursor` when more pages are needed.
 - Treat `mcp_sap_<tool>` as a client display prefix; the callable MCP tool name
   inside this server is the suffix, for example `jupiter_getQuote`.
+- Call `sap_agent_next_action` before retrying after `payment_required`,
+  `hosted_local_signer_required`, transient Solana RPC errors, a missing local
+  bridge, or a submitted signature that has not confirmed.
 - Use `skills/sap-mcp/TOOL_REFERENCE.md` and `USER_DOCS/05_SKILLS_AND_TOOLS.md`
   as the bundled routing maps when deciding which SAP MCP tool or skill domain
   applies to a user request.

package/skills/sap-agent-registry/SKILL.md

@@ -6,12 +6,31 @@ state, global directory listing, and agent profile inspection.
 ## First Steps
 
 1. Call `sap_profile_current`.
-2. Call `sap_get_network_overview` for ecosystem counters when needed.
-3. Use `sap_list_all_agents` for global current agent lists.
+2. Call `sap_protocol_invariants` before registry writes when treasury, fee,
+   hosted/local routing, or lifecycle-complete rules are unclear.
+3. For registration, profile-image updates, Metaplex identity, SNS linking, or
+   full identity setup, call `sap_agent_identity_plan` before any write. It is
+   free and returns normalized fields, local-signer routing, metadata contract,
+   forbidden actions, and verification checklist.
+4. Use free exact/base reads before paid discovery: `sap_agent_context`,
+   `sap_get_agent`,
+   `sap_get_agent_profile`, `sap_get_agent_stats`, `sap_is_agent_active`,
+   `sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
+   `view: "compact"`, and `includeProtocolIndexes: false`.
+5. Call `sap_get_network_overview` for ecosystem counters when needed.
+6. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
+   `capability` for targeted paid hosted directory reads when free exact/base
+   reads are not enough.
+7. Use `sap_list_all_agents` for global current agent lists and follow
+   `pagination.nextCursor` for additional pages.
 
 ## Tools
 
 - `sap_register_agent`
+- `sap_protocol_invariants`
+- `sap_agent_identity_plan`
+- `sap_agent_context`
+- `sap_agent_next_action`
 - `sap_update_agent`
 - `sap_deactivate_agent`
 - `sap_reactivate_agent`
@@ -21,6 +40,7 @@ state, global directory listing, and agent profile inspection.
 - `sap_get_agent_stats`
 - `sap_get_global_state`
 - `sap_get_network_overview`
+- `sap_list_agents`
 - `sap_list_all_agents`
 - `sap_is_agent_active`
 - `sap_report_calls`
@@ -28,7 +48,52 @@ state, global directory listing, and agent profile inspection.
 
 ## Routing
 
-- "List all agents" means `sap_list_all_agents`.
+- Hosted accountless SAP MCP cannot sign user-owned registry writes. If
+  `sap_register_agent`, `sap_update_agent`, or another registry write returns
+  `hosted_local_signer_required`, no x402 payment was charged. For agent
+  registration, call the local `sap_payments.sap_payments_register_agent`
+  bridge with the same fields and `confirm: true`; it signs locally with the
+  active SAP MCP profile. For agent profile, image, metadata, capability,
+  protocol, pricing, or x402 endpoint updates, call local
+  `sap_payments.sap_payments_update_agent` with the same update fields and
+  `confirm: true`. For other registry writes, run the write on the local SAP
+  MCP profile or use a production unsigned builder/finalizer flow when
+  available.
+- Before any retry after `payment_required`, `hosted_local_signer_required`,
+  `BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted
+  signature that did not confirm, call `sap_agent_next_action`. Follow its
+  `safeToRetryNow`, `nextTool`, and `forbiddenActions` fields.
+- Agent pictures must be public metadata, not desktop file paths. Upload the
+  image or metadata JSON to IPFS, Arweave, Kommodo, or HTTPS, then set
+  `agentUri`/`metadataUri` with `sap_payments_update_agent`.
+- After `sap_payments_register_agent`, do not stop at a Solscan link. Verify
+  `success`, `agentRegistered`, `agentPda`, `confirmationStatus`,
+  `protocolComplete`, and `protocolFee.status`. A complete registration should
+  show the expected protocol fee credited to treasury
+  `J7PyZAGKvprCz4SQ5DKBLAHstJxgVqZcz6kguUoWpP7P`. If `success` is false but
+  `agentRegistered` is true, the account may exist but SAP registration is not
+  protocol-complete. Report the integrity issue and do not retry automatically.
+- After `sap_payments_update_agent`, fetch the agent profile again and verify
+  the changed fields. For image/profile updates, `agentUri` or `metadataUri`
+  must resolve to public metadata containing the image URL.
+- If `sap_payments_update_agent` returns Anchor 3012, `AccountNotInitialized`,
+  or mentions `pricing_menu`, do not run runtime repair and do not retry the
+  same write. This means the write reached the SAP on-chain program but a
+  required registry lifecycle PDA is missing or stale. Call
+  `sap_agent_next_action` and `sap_protocol_invariants`, then upgrade the
+  SDK/server or use the initializer path before retrying.
+- For full agent identity setup, follow
+  `docs/16_SAP_AGENT_IDENTITY_PIPELINE.md`: SAP registration first, optional
+  Metaplex/MPL Core identity, optional SNS domain and records, then a final SAP
+  update that points `metadataUri` at the public metadata document.
+- "Find XONA Agent" or "find an agent by name" means `sap_discover_agents` with
+  `query`.
+- "Find x402 agents" means `sap_discover_agents` with
+  `hasX402Endpoint: true`.
+- "List all agents" means first call free `sap_list_agents` with
+  `limit <= 20`, `view: "compact"`, and `includeProtocolIndexes: false`; then
+  use paid `sap_list_all_agents` with `pagination.nextCursor` if the user wants
+  more, full rows, or ecosystem-scale enumeration.
 - "Agent by wallet" means `sap_get_agent` or `sap_get_agent_profile`.
 - "Is this agent live?" means `sap_is_agent_active`.
 - "Network totals" means `sap_get_network_overview`.
@@ -36,4 +101,34 @@ state, global directory listing, and agent profile inspection.
 ## Safety
 
 Registration and update tools are write operations. Explain the action, read
-policy context, and never inspect keypair files.
+policy context, require explicit confirmation, and never inspect keypair files.
+For registrations, distinguish `agent account exists` from `protocol lifecycle
+complete`; the latter requires confirmation plus a non-failing protocol fee
+audit.
+
+## Canonical Register Fields
+
+Use these exact fields for `sap_payments_register_agent` and local
+`sap_register_agent`:
+
+- `name`: public display name.
+- `description`: public purpose, capabilities, and trust boundary.
+- `capabilities`: array of strings or objects. Prefer object form:
+  `{ "id": "jupiter:swap", "description": "...", "protocolId": "jupiter", "version": "1.0.0" }`.
+- `pricing`: array of pricing tiers. For x402/pay.sh use
+  `{ "pricePerCall": "1000", "tokenType": "usdc", "settlementMode": "x402", "tokenDecimals": 6 }`;
+  USDC amounts are micro-USDC.
+- `protocols`: array such as `["sap", "mcp", "jupiter", "pyth", "metaplex"]`.
+- `agentId`: stable lowercase id, for example `solking`.
+- `agentUri` or `metadataUri`: public metadata/profile URL. Never a local path.
+- `x402Endpoint`: optional `https://host/.well-known/x402`.
+- `confirm`: required `true` on the local `sap_payments` bridge.
+- `protocolFee`: returned output audit for registration; verify it before
+  announcing completion.
+
+## Canonical Update Fields
+
+`sap_payments_update_agent` accepts the same profile fields as registration,
+but every field is optional. Omitted fields stay unchanged. Array fields
+replace the full on-chain list, so fetch the current agent first before adding
+only one capability, protocol, or pricing tier.

package/skills/sap-defi/SKILL.md

@@ -40,12 +40,16 @@ staking protocols.
 ## Flow
 
 1. Use quote/read tools first.
-2. For swaps, prefer `jupiter_getQuote` then `jupiter_smartSwap` or
-   `jupiter_swapInstructions`.
+2. In hosted mode, prefer quote/read tools and unsigned builders such as
+   `jupiter_getOrder`, `jupiter_swapInstructions`, or supported private swap
+   builders. Direct signer tools such as `jupiter_swap`, `jupiter_smartSwap`,
+   and `jupiter_executeOrder` require a local SAP MCP profile or external
+   signer and are rejected before x402 payment on hosted accountless servers.
 3. Explain slippage, route, token mints, amount units, and expected output.
 4. Preview and policy-check before signing.
-5. For any unsigned or partially signed transaction returned by Jupiter, use
-   `sap_preview_transaction`, `sap_sign_transaction`, and
+5. For any unsigned or partially signed transaction returned by hosted SAP MCP,
+   use `sap_payments_finalize_transaction`. For local SAP MCP stdio builders,
+   use `sap_preview_transaction`, `sap_sign_transaction`, and
    `sap_submit_signed_transaction`. Do not write ad-hoc signing scripts.
 
 ## Safety