@oobe-protocol-labs/sap-mcp-server 0.9.16 → 0.9.21

package/dist/tui/wizard-save.js

@@ -1,10 +1,31 @@
+/**
+ * @name tui/wizard-save
+ * @description TUI wizard configuration persistence — saves profiles, generates keypairs, and writes config files.
+ *
+ * @flow
+ *   1. `saveTuiWizardConfig` takes wizard input, normalizes the profile name, and optionally
+ *      generates a new Solana keypair (saved to disk with restrictive permissions).
+ *   2. Writes the full SAP MCP config JSON to the profile config path.
+ *   3. Sets the active profile marker file.
+ *   4. Returns the config path, wallet path, and agent public key.
+ *
+ * @module tui/wizard-save
+ */
 import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { Keypair } from '@solana/web3.js';
+/** @description Regex pattern validating normalized profile names (lowercase alphanumeric with hyphens). */
 const PROFILE_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
- * Executes the preferred config dir operation.
+ * @name preferredConfigDir
+ * @description Returns the preferred configuration directory for SAP MCP profiles.
+ *
+ * Respects `XDG_CONFIG_HOME` on Linux, `%APPDATA%` on Windows, and `~/.config` on macOS.
+ *
+ * @returns Absolute path to the config directory.
+ *
+ * @usedBy `saveTuiWizardConfig`, `defaultWalletPath`, `profileConfigPath`.
  */
 export function preferredConfigDir() {
     if (process.env.XDG_CONFIG_HOME) {
@@ -16,20 +37,41 @@ export function preferredConfigDir() {
     return join(homedir(), '.config', 'mcp-sap');
 }
 /**
- * Executes the default wallet path operation.
+ * @name defaultWalletPath
+ * @description Returns the default keypair file path for a given profile name.
+ *
+ * @param profileName — Normalized profile name.
+ * @returns Absolute path to the keypair JSON file.
+ *
+ * @usedBy `saveTuiWizardConfig`.
  */
 export function defaultWalletPath(profileName) {
     return join(preferredConfigDir(), 'keypairs', `${normalizeProfileName(profileName)}-keypair.json`);
 }
 /**
- * Resolves the config file path for a profile name.
+ * @name profileConfigPath
+ * @description Resolves the config file path for a normalized profile name.
+ *
+ * @param profileName — Profile name to resolve (will be normalized).
+ * @returns Absolute path to the profile config JSON file.
+ *
+ * @usedBy `saveTuiWizardConfig`.
  */
 export function profileConfigPath(profileName) {
     const normalized = normalizeProfileName(profileName);
     return join(preferredConfigDir(), `config-${normalized}.json`);
 }
 /**
- * Normalizes profile names accepted by the TUI wizard.
+ * @name normalizeProfileName
+ * @description Normalizes a profile name to lowercase alphanumeric with single hyphens.
+ *
+ * Trims, lowercases, replaces non-alphanumeric sequences with hyphens, and strips
+ * leading/trailing hyphens.
+ *
+ * @param value — Raw profile name string from user input.
+ * @returns Normalized profile name string.
+ *
+ * @usedBy `defaultWalletPath`, `profileConfigPath`, `saveTuiWizardConfig`.
  */
 export function normalizeProfileName(value) {
     return value
@@ -39,13 +81,27 @@ export function normalizeProfileName(value) {
         .replace(/^-+|-+$/g, '');
 }
 /**
- * Returns true when a normalized profile name is safe for config and wallet paths.
+ * @name isValidProfileName
+ * @description Returns `true` when a normalized profile name is safe for config and wallet paths.
+ *
+ * Rejects empty names, names that don't match the profile pattern, and the reserved name `default`.
+ *
+ * @param value — Normalized profile name to validate.
+ * @returns `true` if the name is valid, `false` otherwise.
+ *
+ * @usedBy `saveTuiWizardConfig`.
  */
 export function isValidProfileName(value) {
     return PROFILE_NAME_PATTERN.test(value) && value !== 'default';
 }
 /**
- * Expands home-relative paths entered in the TUI wizard.
+ * @name normalizeTuiPath
+ * @description Expands home-relative paths (`~` and `~/`) entered in the TUI wizard.
+ *
+ * @param value — Raw path string from user input.
+ * @returns Expanded absolute path, or `undefined` if input was empty.
+ *
+ * @internal
  */
 function normalizeTuiPath(value) {
     if (!value) {
@@ -60,7 +116,13 @@ function normalizeTuiPath(value) {
     return value;
 }
 /**
- * Reads the public key from a local Solana keypair file.
+ * @name readAgentPubkey
+ * @description Reads the public key from a local Solana keypair file.
+ *
+ * @param walletPath — Optional path to the keypair JSON file.
+ * @returns Base58-encoded public key string, or `undefined` if the file doesn't exist or is invalid.
+ *
+ * @internal
  */
 function readAgentPubkey(walletPath) {
     if (!walletPath || !existsSync(walletPath)) {
@@ -73,7 +135,14 @@ function readAgentPubkey(walletPath) {
     return Keypair.fromSecretKey(Uint8Array.from(parsed)).publicKey.toBase58();
 }
 /**
- * Executes the save tui wizard config operation.
+ * @name saveTuiWizardConfig
+ * @description Saves a TUI wizard configuration to disk, optionally generating a new keypair.
+ *
+ * @param config — TUI wizard configuration data from user input.
+ * @returns Result containing the config path, wallet path, whether a wallet was created, and agent public key.
+ * @throws If the profile name is invalid or if file I/O fails.
+ *
+ * @usedBy TUI wizard save flow.
  */
 export function saveTuiWizardConfig(config) {
     const configDir = preferredConfigDir();

package/dist/tui/wizard-save.js.map

@@ -1 +1 @@
-{"version":3,"file":"wizard-save.js","sourceRoot":"","sources":["../../src/tui/wizard-save.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wizard-save.js","sourceRoot":"","sources":["../../src/tui/wizard-save.ts"],"names":[],"mappings":"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"}

package/docs/06_PAYMENTS_X402_AND_PAYSH.md

@@ -11,9 +11,9 @@ The server does not charge for connecting. Payment is evaluated per MCP request,
 | Tier | Examples | Price |
 | --- | --- | --- |
 | Free | `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`, `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`, `sap_agent_next_action`, exact SAP agent/profile reads, compact `sap_list_agents` orientation pages with `limit <= 20` | Free |
-| Premium read | `sap_discover_agents`, `sap_list_all_agents`, full/enriched/large `sap_list_agents` pages, enriched network stats, indexed discovery, market/oracle/DAS reads | `$0.007` to `$0.01` |
-| Builder or batch | complex builders, SNS/domain batch checks, enriched analytics | `$0.01` to `$0.10` |
-| Value action | settlement-like or value-linked operations where appropriate | fixed `$0.20` plus optional `0.5%` |
+| Premium read | `sap_discover_agents`, `sap_list_all_agents`, full/enriched/large `sap_list_agents` pages, market/oracle/DAS reads | `$0.001` default |
+| Builder or batch | complex builders, SNS/domain batch checks, unsigned transaction builders, routing preparation | `$0.008` default, batch = sum of paid calls |
+| Value action | settlement-like or value-linked operations where appropriate | `$0.09` standard, `$0.15` for selected heavy execution paths |
 
 Do not apply percentage fees blindly to swaps or financial routing. Those workflows may create compliance, custody, and routing implications.
 

package/docs/07_ENDPOINTS_AND_CLIENTS.md

@@ -10,6 +10,9 @@
 | `GET` | `/server.json` | Machine-readable public server metadata. | Public. |
 | `GET` | `/pricing.json` | Machine-readable x402/pay.sh pricing catalog generated from the hosted pricing registry. | Public. |
 | `GET` | `/openapi.json` | OpenAPI 3.1 discovery document for the hosted MCP endpoint, x402 metadata, and pay.sh catalog link. | Public. |
+| `GET` | `/premium/catalog.json` | Secret-free premium plugin contracts, schemas, pricing models, and provider readiness. | Public. |
+| `GET` | `/premium/streams.json` | Secret-free premium stream contracts for future x402/pay.sh real-time delivery rails. | Public. |
+| `GET` | `/premium/webhooks.json` | Secret-free premium webhook contracts with signed delivery expectations. | Public. |
 | `GET` | `/.well-known/x402` | x402 discovery document for paid hosted MCP resources. | Public. |
 | `GET` | `/pay/provider.yml` | Secret-free pay.sh provider YAML for the hosted SAP MCP catalog/proxy workflow. | Public. |
 | `GET` | `/favicon.png` | SAP MCP favicon/social preview asset. | Public. |
@@ -132,7 +135,7 @@ Codex supports Streamable HTTP MCP servers with URL-based TOML entries. Use loca
 ```toml
 [mcp_servers.sap]
 command = "npx"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.16", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.21", "sap-mcp-server"]
 
 [mcp_servers.sap.env]
 SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"

package/docs/14_DESKTOP_WIZARD_RELEASE.md

@@ -66,7 +66,7 @@ url = "https://mcp.sap.oobeprotocol.ai/mcp"
 ```toml
 [mcp_servers.sap_payments]
 command = "npx"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.16", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.21", "sap-mcp-server"]
 startup_timeout_sec = 300
 tool_timeout_sec = 300
 
@@ -279,8 +279,8 @@ npm pack --dry-run --cache ./.npm-cache
 The current local macOS arm64 build produces:
 
 ```txt
-SAP-MCP-Wizard-0.9.16-arm64.dmg
-SAP-MCP-Wizard-0.9.16-arm64.zip
+SAP-MCP-Wizard-0.9.21-arm64.dmg
+SAP-MCP-Wizard-0.9.21-arm64.zip
 ```
 
 Windows EXE and Linux artifacts are produced by the GitHub Actions matrix.

package/docs/16_SAP_AGENT_IDENTITY_PIPELINE.md

@@ -235,6 +235,12 @@ Then call:
   confirms the agent account and reports a non-failing `protocolFee` audit.
 - Do not call profile/image update complete until `sap_payments_update_agent`
   confirms and a fresh `sap_get_agent_profile` read shows the intended fields.
+- If an update returns Anchor 3012, `AccountNotInitialized`, or a
+  `pricing_menu` error, do not classify it as missing `sap_payments` and do not
+  ask the user to repair/restart the runtime. The local signer route worked; the
+  SAP registry account lifecycle is missing a required on-chain PDA. Call
+  `sap_agent_next_action` and `sap_protocol_invariants`, then use the current
+  SDK/server initializer path before retrying the update.
 - Do not create temporary signing scripts.
 - Do not read keypair JSON.
 - Do not pay x402 for writes that the hosted server says require local signer.

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

@@ -65,6 +65,7 @@ For paid/write hosted tools, also configure the local `sap_payments` bridge. The
 - [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
 
@@ -118,6 +119,7 @@ Read these first:
 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
 
@@ -127,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.9.16",
+  "version": "0.9.21",
   "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",
@@ -145,16 +145,15 @@
   "engines": {
     "node": ">=22.12.0"
   },
-  "packageManager": "pnpm@11.7.0",
   "overrides": {
-    "bigint-buffer": "file:vendor/bigint-buffer",
-    "brace-expansion@<1.1.16": "1.1.16",
-    "brace-expansion@>=2.0.0 <2.1.2": "2.1.2",
-    "esbuild": "^0.28.1",
-    "js-yaml@>=4.0.0 <4.3.0": "4.3.0",
+    "@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.16",
+  "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.16",
+      "version": "0.9.21",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.16"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.21"
         },
         {
           "type": "positional",

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

@@ -76,6 +76,12 @@ state, global directory listing, and agent profile inspection.
 - 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

package/skills/sap-mcp/SKILL.md

@@ -12,6 +12,12 @@ available, then call `sap_agent_runtime_status` with the closest intent and
 `sap_skills_bundle` with `includeContents: true`. Load the returned SAP MCP
 skill contents into context before selecting advanced tools.
 
+If the MCP runtime exposes prompts, use `sap-agent-intent-router` as the compact
+decision prompt before paid calls, registry writes, escrow flows, identity
+updates, or after SAP/x402/MCP errors. It routes the user intent to hosted
+reads, `sap_payments_*`, unsigned builders, transaction finalization, or repair
+without requiring a long pasted prompt from the user.
+
 Always inspect runtime context through MCP tools, not by reading config files:
 
 1. `sap_agent_start`
@@ -47,6 +53,10 @@ and error strings unchanged.
 
 ## Discovery Rules
 
+- Treat SAP registry, balances, SNS ownership, quotes, settlement status, and
+  agent profile reads as fresh data. Do not rely on old chat memory when the
+  user asks for current state; use exact lightweight reads first, then paid
+  discovery only when enrichment or broad search is needed.
 - Use free exact/base reads first when the wallet, PDA, or a small orientation
   page is enough: `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
   `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
@@ -175,10 +185,19 @@ Use `sap_payments.sap_payments_profile_current` only as a narrower compatibility
 profile check.
 
 Basic wallet reads are free on hosted SAP MCP. Call `sol_get_balance`,
-`spl-token_getBalance`, and `spl-token_getTokenAccounts` directly on the hosted
-server. Do not send these balance checks through `sap_payments_call_paid_tool`,
-and do not summarize a balance read as a facilitator `BlockhashNotFound`
-problem unless a paid tool actually returned that error.
+`spl-token_getBalance`, `spl-token_getTokenAccounts`, and `magicblock_balance`
+directly on the hosted server. Do not send these balance checks through
+`sap_payments_call_paid_tool`, and do not summarize a balance read as a
+facilitator `BlockhashNotFound` problem unless a paid tool actually returned
+that error. Use `jupiter_getHoldings` only when the user needs enriched paid
+portfolio context.
+
+Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
+get the exact pricing tier, estimated USD cost, and recommended `maxPriceUsd`.
+This prevents silent cap aborts and failed x402 attempts on local-signer-only
+tools. For local-signer-only tools (e.g. `sap_register_agent`), the estimate
+will say `tier: "local-signer-only"` and tell you to use the local
+`sap_payments_*` equivalent instead of `sap_payments_call_paid_tool`.
 
 If a hosted paid tool returns `BlockhashNotFound`,
 `transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is
@@ -220,6 +239,10 @@ and protocol fee invariant were verified. If `success` is false while
 protocol registration lifecycle is not complete. After
 `sap_payments_update_agent`, fetch the agent again and confirm the changed
 fields before saying an image, metadata, pricing, or capability update is done.
+If an update returns Anchor 3012, `AccountNotInitialized`, or `pricing_menu`, do
+not call runtime repair or retry the same write. Route it through
+`sap_agent_next_action` and `sap_protocol_invariants`; it is an SAP on-chain
+registry lifecycle issue, not a missing local bridge.
 
 Before any write-like operation, use this routing order:
 

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -201,7 +201,10 @@ Protocol routing shortcuts:
 
 | User intent | Most specific tools |
 | --- | --- |
-| SOL or SPL balance | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts` |
+| SOL or SPL balance (free) | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance` |
+| Enriched holdings (paid read-premium) | `jupiter_getHoldings` |
+| Pre-call cost estimate (free) | `sap_estimate_tool_cost` |
+| Pricing catalog (free) | `sap_pricing_catalog` |
 | SOL or SPL transfer | `spl-token_transferSol`, `spl-token_transfer` |
 | Token launch/mint/burn | `spl-token_deployToken`, `spl-token_mintTo`, `spl-token_burn` |
 | Jupiter quote/swap | `jupiter_getQuote`, `jupiter_smartSwap`, `jupiter_swap`, `jupiter_swapInstructions` |

package/skills/sap-payments-x402/SKILL.md

@@ -46,9 +46,13 @@ or external signer.
 
 - Free: `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`,
   `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
-  `sap_agent_next_action`, exact SAP agent/profile reads, compact
-  `sap_list_agents` pages with `limit <= 20`, `sap_get_network_overview`, `sol_get_balance`,
-  `spl-token_getBalance`, and `spl-token_getTokenAccounts`.
+  `sap_agent_next_action`, `sap_estimate_tool_cost`, `sap_pricing_catalog`,
+  exact SAP agent/profile reads, compact `sap_list_agents` pages with
+  `limit <= 20`, `sap_get_network_overview`, core balance checks
+  (`sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`,
+  `spl-token_getMint`, `spl-token_getSupply`, `magicblock_balance`,
+  `sap_x402_get_balance`). Enriched holdings such as `jupiter_getHoldings`
+  are paid read-premium.
 - Read premium: `sap_discover_agents`, `sap_list_all_agents`, full/enriched or
   large `sap_list_agents` pages, indexed discovery, network stats,
   protocol/capability indexes.
@@ -73,16 +77,26 @@ For fast x402 execution:
    change, but the tool name and arguments must match the challenge.
 3. Use `PAYMENT-SIGNATURE` first; use `X-PAYMENT` only for clients that require
    the alternate header.
-4. Cache free `tools/list`, `prompts/list`, and `resources/list` locally rather
-   than paying or re-fetching repeatedly.
+4. Cache only static MCP surface metadata such as `tools/list`, `prompts/list`,
+   and `resources/list` inside the runtime when useful. Do not cache on-chain
+   balances, SAP agent rows, pricing, SNS ownership, quotes, or settlement
+   state when the user expects fresh data.
 5. Treat `PAYMENT-RESPONSE` as the receipt bound to the tool output.
 6. If the client runtime cannot sign or attach x402 payment headers itself, use
    the local SAP MCP `sap_payments_call_paid_tool` bridge configured by the SAP
    MCP wizard instead of falling back to local stdio automatically.
 
-Do not use x402 for basic balance reads. `sol_get_balance`,
-`spl-token_getBalance`, and `spl-token_getTokenAccounts` are free hosted tools
-and should be called directly through the remote SAP MCP connection.
+Do not use x402 for core balance reads. `sol_get_balance`,
+`spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance`,
+and `sap_x402_get_balance` are free hosted tools and should be called directly
+through the remote SAP MCP connection. Use `jupiter_getHoldings` only when the
+user needs enriched paid portfolio context. Always verify USDC and SOL balances
+before attempting paid calls — an agent without USDC cannot make paid calls.
+
+Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
+get the exact tier, estimated USD cost, and recommended `maxPriceUsd`. This
+prevents silent cap aborts and avoids wasting x402 attempts on local-signer-only
+tools that never issue a 402 challenge.
 
 When available locally, call `sap_payments_call_paid_tool` with `toolName`,
 `arguments`, `maxPriceUsd`, and `confirm: true`. It initializes the hosted MCP