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

package/CHANGELOG.md

@@ -2,6 +2,737 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.9.3 - 2026-07-25
+
+### Added — Local Agent Memory Subsystem (SQLite FTS5)
+
+A complete serverless local-memory subsystem built on SQLite FTS5, using
+inverted full-text indexes and relevance-ranked retrieval to recover historical
+agent interactions. All data is stored locally at
+`~/.config/sap-mcp/memory/agent-memory.db` — no data leaves the user's machine.
+
+**10 module files:**
+- `src/memory/types.ts` — 11 TypeScript interfaces with strict typing
+- `src/memory/database.ts` — Singleton SQLite connection (WAL mode, FTS5, schema versioning, prepared statements, graceful degradation)
+- `src/memory/tool-call-store.ts` — Records + FTS5 search with BM25 ranking
+- `src/memory/memory-store.ts` — Agent memories with relevance decay + recall
+- `src/memory/stream-buffer-store.ts` — FIFO event buffering with dedup + replay
+- `src/memory/async-processor.ts` — Non-blocking background maintenance (decay, evict, archive, prune, WAL checkpoint)
+- `src/memory/auto-record.ts` — Automatic tool call recording hook
+- `src/memory/hermes-bridge.ts` — Cross-session Hermes Agent integration (read-only)
+- `src/memory/utils.ts` — truncate, decayRelevance, isExpired
+- `src/strategies/strategy-store.ts` — File-based JSON strategy store with versioning + path traversal protection
+
+**17 new FREE MCP tools (319 → 336 total, all local, no x402):**
+
+| Category | Tool | Function |
+|---|---|---|
+| Memory | `sap_memory_record` | Record a tool call in the DB |
+| | `sap_memory_search` | FTS5 search across tool call history |
+| | `sap_memory_summarize` | Create an LLM-compressed memory (lesson/pattern/failure/success) |
+| | `sap_memory_recall` | Top N memories for a category (prompt injection) |
+| | `sap_memory_prune` | Remove expired + low-relevance memories |
+| Strategy | `sap_strategy_save` | Save/update a strategy JSON |
+| | `sap_strategy_load` | Load a strategy by category+name |
+| | `sap_strategy_list` | List strategies (filterable) |
+| | `sap_strategy_activate` | Activate/deactivate a strategy |
+| Stream | `sap_stream_buffer` | Buffer a stream event (dedup by eventId) |
+| | `sap_stream_consume` | Consume events FIFO (mark consumed) |
+| | `sap_stream_replay` | Replay all events for backtest |
+| Audit | `sap_audit_query` | Query audit trail via FTS5 |
+| | `sap_audit_record` | Record a manual audit entry |
+| | `sap_audit_stats` | Aggregate stats (counts, breakdowns, DB size) |
+| Hermes | `sap_hermes_search` | Search Hermes session history |
+| | `sap_hermes_recent` | Recent Hermes sessions for context injection |
+
+**Key engineering features:**
+- SQLite FTS5 with BM25 relevance ranking
+- WAL mode for concurrent read access (crash-safe)
+- Thread-safe singleton with cached prepared statements
+- Graceful degradation (if DB can't open, tools return empty results)
+- Async processor: decay (1h), evict (5m), archive (1h), prune (6h), WAL checkpoint (10m)
+- Relevance decay: 1%/day, auto-prune below 0.05
+- Stream dedup: (streamType, eventId) unique index
+- Strategy versioning: auto-increment on update
+- Path traversal protection: sanitized path segments (alphanumeric + dash/underscore/dot only)
+- Hermes bridge: auto-detected, read-only, FTS5 with LIKE fallback
+- Server lifecycle: init+start on boot, stop+close on shutdown
+
+### Added — Quick Context Auto-Update
+
+`sap_quick_context` now accepts `agentKnownVersion`:
+- When omitted (first bootstrap): `skillsUpdateRequired=true`, `skillsContents` populated with full SKILL.md inline
+- When ≠ server version: `skillsUpdateRequired=true`, skills contents included
+- When == server version: `skillsUpdateRequired=false` (token savings)
+
+Also returns `serverCommit` (git short hash), `environment` (network, mode, authType, rateLimitPerMinute), and `recommendedFlow` (mode-specific workflow guidance).
+
+### Added — Wizard Directory Creation
+
+`ensureConfigDirectories()` now creates `~/.config/sap-map/memory/` and `~/.config/sap-mcp/strategies/` with private permissions (mode 0o700) alongside the existing config, keypair, data, log, and cache directories.
+
+### Security
+
+- Path traversal protection on all strategy store operations (`sanitizePathSegment`)
+- All SQL queries use parameterized prepared statements (no string interpolation)
+- Hermes bridge opens read-only connections only
+- Memory database is local-only — no network access
+- No secrets, private keys, or keypair bytes stored in the memory DB
+- 0 dependency vulnerabilities (`pnpm audit`)
+- `createRequire` used instead of `require()` to satisfy ESLint
+
+## 0.9.22 - 2026-07-25
+
+### Added
+
+- **`signerProfile` per-call parameter** on `sap_payments_finalize_transaction`.
+  Agents can now sign with a specific profile without switching `.active-profile`
+  manually. Multiple profiles coexist in the same session. Eliminates the #1
+  source of agent friction: profile-switch juggling + stale signer cache.
+- **`sap_build_sol_transfer`** — Hosted unsigned builder for native SOL transfers
+  using `SystemProgram.transfer`. Fills the gap left by `spl-token_transferSol`
+  (local-signer-only). Returns base64 unsigned transaction for local signing.
+- **`sap_build_spl_transfer`** — Hosted unsigned builder for SPL token transfers
+  with idempotent ATA creation. Uses raw `@solana/web3.js` `TransactionInstruction`
+  (no `@solana/spl-token` dependency). Returns base64 unsigned transaction.
+- **x402 idempotency cache** in `McpMonetizationGate` — prevents double-charge on
+  retry. Successful settlements are cached by `requestHash` for 5 minutes
+  (max 10,000 entries, LRU eviction, opportunistic pruning). If the same
+  request is retried after a network failure, the cached settlement is returned
+  without re-charging the payer's USDC.
+- **x402 nonce + TTL strict validation** — `validatePaymentRequirementsForDecision`
+  now enforces `maxTimeoutSeconds ≤ 120` and rejects invalid/missing TTL values.
+  Prevents stale challenge replay attacks.
+- **Challenge-signature parameter** on `sap_profile_switch` — optional Ed25519
+  signature proving ownership of the target profile keypair. Prevents
+  impersonation via manual `.active-profile` file edits.
+- **`preloadPremiumProviders`** at server startup — providers are eagerly loaded
+  and connected when the server boots, not lazily on first request. The
+  `providerHealth` response now reflects real provider status immediately.
+- **3 new free meme-radar providers** (DexScreener + Solana RPC, no API keys):
+  - `meme.newlisting.alert` — detects newly listed tokens via DexScreener
+    `pairCreatedAt` with honeypot/dev-wallet risk flags.
+  - `meme.rugpull.detector` — on-chain mint/freeze authority checks via Solana
+  RPC + DexScreener liquidity drain detection. Risk score 0-1 with
+    exit/monitor/caution actions.
+  - `meme.social.sentiment` — bull/bear scores from DexScreener price momentum
+  (1h/6h/24h weighted) with volume acceleration confidence.
+- **Multi-feed Pyth** — `pyth.price.tick` and `pyth.volatility.watch` now poll
+  5 feeds by default (SOL/USD, WBTC/USD, WETH/USD, JUP/USD, USDC/USD) instead
+  of 1. All Pyth providers converted from WebSocket to HTTP polling
+  (`hermes.pyth.network/v2/updates/price/latest`).
+- **`signalConfidence` field** on Pyth price tick events — normalized 0-1
+  confidence score derived from `1 - (confidenceInterval / price)`, separate
+  from the raw Pyth `confidenceIntervalUsd`.
+- **ATR-based SL/TP** for volatility breakout signals — `stopLoss = entry ∓
+  2×ATR`, `takeProfit = entry ± 3×ATR`, with `minSpreadPct` filter (0.1%)
+  to discard signals too tight for on-chain execution. `action` changed from
+  `sell` to `swap` for spot-only agents.
+- **Applied filters in webhook relay response** — `sap_premium_webhook_relay`
+  now returns `subscribedEvents` and `appliedFilters` in the subscription
+  response for agent verification.
+- **`sap-mcp-optimization` skill** (devops category) — documents pre-estimate,
+  profile routing, build→sign→submit, x402 payment rules, readiness checks,
+  budget management, and premium stream consumption patterns.
+- Tool count: 317 → 319. Test count: 603 (unchanged, all updated).
+
+### Changed
+
+- **Premium capability prices halved** — all 13 premium capabilities now cost
+  50% less per unit/event:
+  - `jupiter.quote.delta`: $0.02 → $0.01/min
+  - `pyth.price.tick`: $0.015 → $0.0075/min
+  - `price.threshold.crossed`: $0.001 → $0.0005/event
+  - `jupiter.arbitrage.scan`: $0.05 → $0.025/min
+  - `pyth.volatility.watch`: $0.03 → $0.015/min
+  - `jupiter.route.optimized`: $0.025 → $0.0125/min
+  - `meme.newlisting.alert`: $0.003 → $0.0015/event
+  - `meme.social.sentiment`: $0.02 → $0.01/min
+  - `meme.rugpull.detector`: $0.04 → $0.02/min
+  - `meme.volume.spike`: $0.025 → $0.0125/min
+  - `tech.github.activity`: $0.002 → $0.001/event
+  - `tech.tvl.change`: $0.02 → $0.01/min
+  - `tech.tokenomics.analysis`: $0.004 → $0.002/event
+- **Heavy value-action price**: $0.15 → $0.05 (max accepted x402 for
+  value-action tier tools).
+- **Auto-pay threshold**: $0.02 → $0.05 (`SAP_MCP_X402_AUTO_PAY_MAX_USD`).
+  Read-premium ($0.001) and builder ($0.008) calls now auto-pay without
+  confirmation.
+- **Premium poll/flush/metrics FREE** — `sap_premium_stream_poll`,
+  `sap_premium_stream_flush`, `sap_premium_webhook_relay_status`,
+  `sap_premium_metrics`, `sap_premium_session_status`, `sap_premium_close_session`
+  moved to FREE_TOOLS + STRICT_FREE_TOOLS. No x402 charge for consumption
+  or diagnostics.
+- **Birdeye dependency removed** — all meme-radar capabilities now use
+  DexScreener + Solana RPC (both free, no API key). `SAP_MCP_PREMIUM_BIRDEYE_API_URL`
+  removed from all capability definitions and test fixtures.
+- **Builder tool descriptions** now mention `sap_payments_finalize_transaction`
+  as the 1-call alternative to the 3-step preview→sign→submit flow.
+- **`sap_estimate_tool_cost`** description now explicitly says "dry-run — no
+  charge, no x402 challenge" and includes `maxPriceUsd = estimate × 1.25`
+  guidance.
+- **`sap_quick_context` nextAction** now includes explicit routing guidance:
+  accountless hosted → use `sap_payments_profile_current`, `signerProfile`
+  per-call, `sap_build_sol_transfer`/`sap_build_spl_transfer`, no signing scripts.
+
+### Fixed
+
+- **Bridge cache coherence** — `sap_payments_profile_current` now re-reads
+  `.active-profile` and re-resolves the signer on every call. No more stale
+  signer after manual profile switch.
+- **`sap_profile_switch` guidance** — when the hosted server is accountless,
+  the response now provides 3 concrete options (local bridge, manual edit,
+  CLI command) instead of a bare "Profile does not exist" error. Includes
+  stale cache warning.
+- **Provider preload at startup** — providers are loaded and connected when
+  the server boots, not on first request. `providerHealth` is populated
+  immediately, not empty `{}`.
+- **Provider delivery loop logging** — all `catch` blocks in provider-bridge,
+  webhook-engine, premium-tools, and premium-routes now log errors to stderr
+  instead of swallowing silently.
+- **Meme volume spike provider** — replaced nonexistent DexScreener
+  `/v1/solana/volume` endpoint with real API (`/latest/dex/tokens/{mint}` and
+  `/latest/dex/search`). Added `activeMints` tracking, EMA baseline spike
+  detection, `MAX_MINTS_PER_POLL` limit.
+- **Pyth providers** — converted from WebSocket (`wss://hermes.pyth.network/v2/ws`,
+  rejects bare connections) to HTTP polling (`/v2/updates/price/latest`).
+- **All 12 provider import paths** — fixed `../../types.js` → `../types.js`.
+- **`onchain.solana.ts`** — imported `ConfirmedSignatureInfo` from
+  `@solana/web3.js` to fix `blockTime: number | null | undefined` type mismatch.
+- **Stale config references** — cleaned up all `0.02` auto-pay and `0.15`
+  heavy value refs in `.env.example`, `config.example.json`,
+  `config.secure-example.json`, `schema.json`, `mcp-client-injection.ts`, and
+  `explain-x402-settlement.prompt.ts`.
+
+### Security
+
+- x402 idempotency cache prevents double-charge on retry (point 2c).
+- x402 nonce + TTL strict validation caps challenge lifetime at 120s (point 5b).
+- Challenge-signature parameter on profile switch prevents impersonation (point 5a).
+- `secretMaterial: keypair-bytes-never-returned` guarantee maintained across
+  all signing tools.
+- No secrets, private keys, or keypair bytes in source code (security audit clean).
+- 0 dependency vulnerabilities (`pnpm audit`).
+
+## 0.9.21 - 2026-07-25
+
+### Added
+
+- Added 5 new MCP tools addressing agent feedback on premium stream usability:
+  - `sap_premium_stream_poll` — Long-poll buffered premium stream events with
+    `sinceEventId` cursor. MCP-compatible alternative to SSE connections.
+  - `sap_premium_stream_flush` — Bulk flush buffered events with cursor pagination
+    for catch-up after disconnection.
+  - `sap_quick_context` — Single-call bootstrap aggregator (version, tools, pricing,
+    premium, skills, nextAction) reducing agent bootstrap from 5+ calls to 1.
+  - `sap_premium_webhook_relay` — Buffer-only webhook subscription for local agents
+    without a public HTTPS endpoint. Events stored server-side, consumed via poll/flush.
+  - `sap_premium_webhook_relay_status` — Relay config and buffered event count lookup.
+- All 5 tools are free (no x402 charge) and transport-agnostic (work with SSE,
+  WebSocket, and any MCP transport).
+- Pricing tiers in `sap_quick_context` now include actual USD amounts inline.
+
+### Improved
+
+- `sap_skills_bundle` description now documents the existing `skills[]` filter +
+  `includeContents:false` metadata-only pattern for efficient selective loading.
+- `sap_premium_stream_poll` description clarifies it is transport-agnostic.
+- Tool count: 312 → 317. Premium category: 13 → 17. New category: quickContext: 1.
+- Test count: 601 → 603 (2 new webhook relay tests).
+
+### Fixed
+
+- GitHub Actions CI: added `pnpm config set minimumReleaseAge 0` step to
+  `desktop-release.yml` to fix `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`.
+- Removed `package-lock=false` from `.npmrc` (prevented pnpm from reading
+  `pnpm-lock.yaml` on local dev).
+- Regenerated `pnpm-lock.yaml` with pnpm 11.7.0 to fix
+  `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH` on CI overrides.
+- Changed `postcss` override from `8.5.18` to `^8.5.18` (range, not exact).
+- Renamed tag `v0.9.20` → `0.9.20` (consistent with all prior tags).
+- Updated all `0.9.18` references to `0.9.20` across docs, server.json, README,
+  USER_DOCS, and desktop wizard renderer.
+
+## 0.9.20 - 2026-07-25
+
+### Added
+
+- Added 10 new MCP tools for perpetual futures trading and chart analysis:
+  - `sap_perp_markets` — List Adrena perp markets with mark price, funding, OI.
+  - `sap_perp_position_info` — Read on-chain Adrena perp positions for a wallet.
+  - `sap_perp_funding_history` — Historical funding rates from Adrena API.
+  - `sap_chart_ohlc` — OHLC candlestick data for any Solana token (DexScreener).
+  - `sap_chart_long_term` — Long-term price history + protocol TVL (DexScreener + DeFiLlama).
+  - `sap_chart_volume_profile` — Volume profile analysis with POC, VAH, VAL.
+  - `sap_perp_liquidation_zones` — Compute liquidation zones for open positions.
+  - `sap_perp_build_open` — Build unsigned tx to open leveraged perp position (Adrena).
+  - `sap_perp_build_close` — Build unsigned tx to close a perp position.
+  - `sap_perp_build_modify` — Build unsigned tx to add/remove collateral.
+- All 10 tools use only free APIs (DexScreener, DeFiLlama, Adrena REST, Solana RPC).
+- Inscribed tools (`sap_perp_build_*`) return unsigned transactions for local agent signing.
+
+### Removed
+
+- Removed `sap-premium-agent-events` plugin (depended on REGISTRY_STREAM_URL — internal).
+- Removed `sap-premium-x402-ledger` plugin (depended on X402_STREAM_URL — internal).
+- Removed `sap-premium-trading-signals` plugin (depended on SIGNAL_PROVIDER_URL — not built).
+- Removed `sap-premium-lowcap-discovery` plugin (depended on BIRDEYE_API_URL — paid).
+- Removed `meme.social.sentiment` capability (depended on BIRDEYE_API_URL — paid).
+- Removed `tech.github.activity` and `tech.tokenomics.analysis` capabilities (GITHUB_API_URL — rate limited).
+- Removed `mempool.whale.alert` capability and provider.
+- Removed all env vars for paid/internal services: REGISTRY_STREAM_URL, X402_STREAM_URL,
+  SIGNAL_PROVIDER_URL, BIRDEYE_API_URL, GITHUB_API_URL, MEMPOOL_STREAM_URL.
+- Deleted 4 manifest JSON files, 11 provider TS files, 2 provider directories.
+
+### Improved
+
+- Hardened `webhook-engine.ts`: `signDelivery()` now throws if
+  `SAP_MCP_PREMIUM_WEBHOOK_SIGNER` is not set (was using 'fallback-dev-key').
+- Zero signing keys exposed in premium provider code — all providers are read-only
+  data streams + webhook delivery. No sendTransaction, Keypair.from, or secretKey.
+- Premium capabilities reduced from 23 to 10 — all now use only free APIs.
+- Updated `server-metadata.ts` tool count from 302 to 312.
+- Updated `builtin-plugins.test.ts` plugin count from 8 to 4.
+- Updated `trading-capabilities.ts` from 6 to 3 capabilities.
+- Updated pnpm overrides for Dependabot vulnerability fixes (postcss, langsmith,
+  @hono/node-server, uuid).
+- Bumped package, server metadata, and runtime version to `0.9.20`.
+
+## 0.9.19 - 2026-07-25
+
+### Added
+
+- Added 5 new premium plugin definitions with 15 additional capabilities:
+  - `sap-premium-trading-streams` — 4 WebSocket stream capabilities (arbitrage,
+    volatility, whale, route optimization) powered by Jupiter, Pyth, and Helius.
+  - `sap-premium-trading-signals` — 3 webhook signal capabilities (breakout,
+    liquidation cascade, funding rate) via the signal provider rail.
+  - `sap-premium-meme-radar` — 4 capabilities (new listing alert, social
+    sentiment, rugpull detector, volume spike) using Birdeye + DexScreener.
+  - `sap-premium-lowcap-discovery` — 3 capabilities (gem scan, early entry,
+    holder analysis) using Birdeye API for low-cap token discovery.
+  - `sap-premium-tech-fundamentals` — 3 capabilities (GitHub activity, TVL
+    change, tokenomics analysis) using GitHub + DeFiLlama APIs.
+- Added real provider implementations for all 3 core premium plugins
+  (market-data, agent-events, x402-ledger) with WebSocket connections,
+  exponential backoff reconnection, queue-based async generators, and graceful
+  disconnect. Replaced all stub/skeletal placeholders.
+- Added 17 provider adapter files in the private subrepo
+  (`sap-mcp-premium-private/providers/`) covering trading streams, trading
+  signals, meme radar, lowcap discovery, and tech fundamentals with real
+  WebSocket and HTTP polling implementations against free API endpoints.
+- Added OHLC candlestick and on-chain Solana data providers using
+  `@solana/web3.js` Connection and Birdeye OHLC endpoint.
+- Added 5 pure-function technical indicators (Bollinger Bands, ATR, RSI,
+  Volume Profile, Holder Concentration) and 5 stateless strategy engines
+  (Scalping, Arbitrage, Momentum, Mean-Reversion, Meme-Sniper).
+- Added 5 manifest JSON files for the new premium plugins in the private
+  subrepo, bringing the total to 8 manifests with 24 capabilities.
+- Added `src/remote/premium-routes.ts` and `src/remote/premium-memory.ts` for
+  HTTP premium delivery rails.
+- Added full TSDoc documentation (`@name`, `@description`, `@flow`, `@env`,
+  `@module`) across all premium source files and private subrepo providers.
+
+### Improved
+
+- Updated `builtin-plugins.ts` to merge `TRADING_PREMIUM_PLUGINS`,
+  `MEME_RADAR_PREMIUM_PLUGINS`, `LOWCAP_DISCOVERY_PREMIUM_PLUGINS`, and
+  `TECH_FUNDAMENTALS_PREMIUM_PLUGINS` into `listPremiumPlugins()`.
+- Updated premium env templates (production, staging, trading) with 6 new
+  provider env vars for Birdeye, DexScreener, GitHub, DeFiLlama, mempool, and
+  signal provider endpoints.
+- Rewrote private subrepo README with complete structure documentation and
+  zero references to stubs or placeholders.
+- Bumped package, server metadata, and runtime version to `0.9.19`.
+
+## Unreleased
+
+### Added
+
+- Added a typed SAP MCP premium plugin runtime foundation with free discovery
+  and planning tools for stream, webhook, and premium plugin contracts.
+- Added `sap_premium_plugin_catalog`, `sap_stream_catalog`,
+  `sap_webhook_catalog`, `sap_premium_validate_plugin_manifest`,
+  `sap_premium_plugin_template`, `sap_premium_session_start`, and
+  `sap_premium_session_status`.
+- Added premium manifest validation for ids, semver, descriptions, JSON
+  Schemas, pricing policies, and delivery contracts.
+- Added built-in contract manifests for premium market data, SAP agent events,
+  and x402 ledger telemetry without returning fake live data when providers are
+  not configured.
+- Added public machine-readable premium discovery endpoints at
+  `/premium/catalog.json`, `/premium/streams.json`, and
+  `/premium/webhooks.json`.
+- Added a manifest-only private plugin loader for controlled deployments using
+  `SAP_MCP_ENABLE_PREMIUM_PLUGINS`, `SAP_MCP_PLUGIN_DIR`, and
+  `SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY`.
+
+### Improved
+
+- Kept premium discovery/session planning free in both default and strict
+  monetization modes so agents can validate provider readiness before paid
+  stream/webhook activation.
+- Documented the private enterprise plugin loader contract and the rule that
+  live premium data must only be promised when provider readiness is true.
+- Added capability-level `providerReady` signals to premium catalog responses,
+  strict root schema validation for premium plugin manifests, and bounded
+  in-memory premium session pruning.
+- Hardened premium manifests against unknown fields and unsafe provider env
+  values so private provider secrets or executable code cannot leak through
+  public discovery.
+
+## 0.9.18 - 2026-07-23
+
+### Improved
+
+- Strengthened MCP tool metadata so every registered tool carries fluent
+  intent-level guidance covering pricing, routing, and signer boundaries.
+- Extended JSON Schema enrichment to nested object, array, `oneOf`, `anyOf`,
+  and `allOf` branches so agents receive contextual descriptions for complex
+  parameters instead of guessing field names.
+- Added release-blocking regression coverage that fails if any tool has a thin
+  description, lacks exact-field guidance, or exposes an undescribed nested
+  input parameter.
+- Bumped package, public server metadata, desktop wizard, docs, and runtime
+  snippets to `0.9.18` for a coherent release surface across hosted MCP,
+  npm, registries, and client setup flows.
+
+## 0.9.17 - 2026-07-23
+
+### Added
+
+- Added the `sap-agent-intent-router` prompt, a compact MCP prompt that maps
+  user goals and common SAP/x402/MCP errors to the correct hosted read,
+  paid-call, local-signing, unsigned-builder, escrow, registry-write, or repair
+  flow.
+
+### Improved
+
+- Updated MCP initialize instructions so runtimes that support prompts can use
+  `sap-agent-intent-router` before paid calls, registry writes, escrow flows,
+  identity updates, and troubleshooting.
+- Bumped public metadata, npm/package manifests, desktop wizard references, and
+  client config snippets to `0.9.17` so users, registries, and agent runtimes
+  receive a single coherent release identity.
+- Moved supply-chain overrides to `pnpm-workspace.yaml` for pnpm 11 and pinned
+  patched `fast-uri`, `hono`, and `@hono/node-server` versions so desktop
+  release jobs pass the moderate-level audit gate.
+- Removed the duplicate npm `package-lock.json` from the pnpm-managed source
+  tree and disabled package-lock generation, preventing stale npm lock alerts
+  from diverging from the verified `pnpm-lock.yaml` dependency graph.
+- Hardened MCP client config validation and resource-template matching against
+  CodeQL-reported URL substring bypasses and regex-based template matching.
+- Hardened MCP tool-call normalization so explicit output schemas no longer
+  receive synthetic `structuredContent` for text/error responses, preventing
+  strict runtimes from rejecting otherwise-readable SAP tool errors.
+- Taught `sap_agent_next_action`, initialize instructions, prompts, skills, and
+  identity docs to classify Anchor 3012 / `AccountNotInitialized` /
+  `pricing_menu` as SAP on-chain registry lifecycle issues rather than missing
+  `sap_payments` runtime configuration.
+- Kept the `0.9.16` hardening set intact: intent-level tool schemas, payment
+  funnel telemetry, cost estimation, local MCP session reuse, hosted submit
+  relay guidance, and no-key-material safety tests.
+
+## 0.9.16 - 2026-07-21
+
+### Added
+
+- Added free `sap_agent_context`, a compact hosted orientation tool for exact
+  wallet/agent lookups and first-page agent discovery. It gives agents a
+  low-friction way to understand SAP state before running paid/broad calls.
+- Added free `sap_agent_next_action`, a routing resolver for common SAP MCP
+  errors and partial results. It tells agents whether to use hosted reads,
+  `sap_payments_*`, `sap_runtime_repair_plan`, unsigned transaction
+  finalization, or signature verification before retrying.
+- Added free `sap_estimate_tool_cost`, a pre-call estimator that gives agents
+  the pricing tier, expected USD cost, and recommended `maxPriceUsd` before
+  using `sap_payments_call_paid_tool`.
+- Added hosted payment-funnel telemetry for returned challenges, verification
+  failures, and hosted-local-signer blocks so dashboard/operator metrics
+  separate demand from successful settlements.
+- Added a short-lived MCP session cache for local paid-call retries. It reuses
+  initialized MCP sessions without caching live chain data, x402 challenges, or
+  signed payment payloads.
+
+### Improved
+
+- Made exact base SAP registry reads free by default:
+  `sap_get_agent`, `sap_get_agent_profile`, `sap_get_agent_stats`,
+  `sap_get_global_state`, and `sap_is_agent_active`.
+- Made `sap_list_agents` free for compact orientation calls while keeping
+  broad, hydrated, full, and protocol-indexed directory scans paid.
+- Added cache and singleflight protection around compact directory reads so
+  hosted discovery remains faster under repeated agent/runtime probes.
+- Updated agent bootstrap guidance, SAP skills, payment docs, and tool
+  reference files so agents start with context, resolve routing before retrying,
+  avoid temporary signing scripts, and use local `sap_payments_*` tools for
+  user-signed writes.
+- Expanded pricing tests and server metadata tests to cover the new free
+  context/resolver tools and conditional-free discovery behavior.
+- Enriched every registered tool description and root input schema with
+  intent-level routing, pricing, signer-boundary, and exact-field guidance so
+  agents stop guessing aliases, avoid hosted writes that require local signing,
+  and route user-signed transactions through supported `sap_payments_*` flows.
+- Hardened already-signed transaction submission through the hosted
+  `/tx/submit` relay with explicit retry-safety, confirmation-state, and
+  no-key-material audit fields.
+- Added release safety coverage for root input parameter descriptions,
+  hosted-local-signer ledger events, private-key guard behavior, unsafe-action
+  guard behavior, and updated public metadata version examples.
+
+## 0.9.15 - 2026-07-20
+
+### Added
+
+- Added free hosted `sap_agent_runtime_status`, a single runtime truth tool for
+  connection checks, hosted/accountless status, local `sap_payments` bridge
+  expectations, write routing, forbidden actions, and exact next tool calls.
+- Added free hosted `sap_pricing_catalog` and public `GET /pricing.json`, both
+  generated from the same monetization registry used by hosted x402/pay.sh
+  gating.
+
+### Improved
+
+- Strengthened initialize instructions, SAP MCP skills, and user docs so agents
+  use hosted tools for reads, `sap_payments_*` for local payment/signing,
+  hosted unsigned builders plus `sap_payments_finalize_transaction` for
+  user-signed transactions, and `sap_runtime_repair_plan` when the bridge is
+  missing.
+- Made pricing guidance explicit: `/pricing.json` and `sap_pricing_catalog`
+  are for planning and UI copy; the actual x402 challenge remains the payment
+  source of truth.
+- Added release-readiness coverage so the shipped skills/docs keep the runtime
+  status, pricing catalog, hosted builder finalization, and no-temporary-script
+  guidance visible to agents.
+
+## 0.9.13 - 2026-07-19
+
+### Added
+
+- Added a hosted submit-only relay at `POST /tx/submit` for already-signed
+  Solana transactions. The relay never signs, never receives keypair bytes, and
+  returns confirmation status, explorer URL, and retry guidance.
+
+### Improved
+
+- Upgraded transaction finalization from "signature returned" to a bounded
+  lifecycle result: `confirmed` / `finalized` / `failed` /
+  `expired_or_not_landed`, plus `retrySafe` for agent-guided retries.
+- Hardened SAP agent registration into a fail-closed lifecycle: production
+  agents must use `sap_payments_register_agent`, and `success:true` now means
+  the agent account is confirmed and the 0.1 SOL source-level protocol treasury
+  fee invariant was verified. If the account exists but the protocol fee is
+  missing, underpaid, or unverifiable, the bridge returns
+  `success:false`, `agentRegistered:true`, and `protocolComplete:false`.
+- Deprecated the raw `sap_register_agent` wrapper for production registration
+  and added `sap_protocol_invariants` / `sap_agent_identity_plan` guidance so
+  agents can plan SAP + Metaplex + optional SNS identity flows before writes.
+- Made `sap_payments_finalize_transaction` submit through the hosted relay by
+  default when `submit:true`, while preserving `submitViaRelay:false` for fully
+  local RPC submission.
+- Updated `sap_submit_signed_transaction`, agent bootstrap instructions,
+  Smithery config schema, public metadata, and the hosted dashboard so agents
+  stop creating temporary signing scripts and use the supported local-signer +
+  relay flow.
+
+## 0.9.12 - 2026-07-19
+
+### Improved
+
+- Hardened `sap_payments_register_agent` so local SAP agent registration no
+  longer reports a bare submitted signature as success. The bridge now waits
+  for the signature/account to appear on-chain, returns the derived agent PDA,
+  and clearly distinguishes confirmed registration from expired/not-landed
+  transactions.
+- Added agent-readable retry guidance for local registration submissions that
+  do not land inside the confirmation window. Agents should ask the user before
+  retrying once with the same fields, and must not fall back to hosted
+  `sap_register_agent`.
+
+## 0.9.11 - 2026-07-19
+
+### Added
+
+- Added `sap_payments_register_agent`, a local `sap_payments` bridge tool for
+  non-custodial SAP agent registration from hosted-user setups. Agents should
+  call it when hosted `sap_register_agent` returns
+  `hosted_local_signer_required`, using the same registration fields plus
+  `confirm: true`. The write is submitted by the user's local SAP profile
+  signer and does not charge a hosted x402 access fee.
+
+### Improved
+
+- Updated the wizard repair manifest, bundled skills, and user docs so Codex,
+  Hermes, Claude, OpenClaw, and compatible runtimes can verify that the local
+  `sap_payments` bridge exposes profile, readiness, hosted paid-call, external
+  x402, local registration, and transaction finalization tools after restart.
+- Added agent-readable local registry error output that tells agents not to
+  retry impossible hosted accountless registry writes or create temporary
+  signing scripts.
+
+## 0.9.10 - 2026-07-18
+
+### Added
+
+- Added `sap_payments_call_external_x402`, a local free `sap_payments` bridge
+  tool for generic HTTP x402 endpoints discovered through SAP registry
+  metadata. The helper performs the standard unpaid request, parses the 402
+  challenge, signs locally with the user's SAP MCP profile, retries with
+  `PAYMENT-SIGNATURE`, and returns the provider response plus receipt/audit
+  data without exposing keypair bytes.
+
+### Improved
+
+- Updated agent startup guidance, bundled x402 skills, client config reference
+  bundles, and user docs so agents use `sap_payments_call_paid_tool` for hosted
+  SAP MCP tools and `sap_payments_call_external_x402` for external x402 agents
+  instead of hand-rolling temporary HTTP/sign/retry scripts.
+- Added guardrails to the generic external x402 bridge: sensitive caller
+  headers are rejected, local/private/link-local targets are blocked, and
+  request bodies are capped to keep the tool safe for agent runtimes.
+
+## 0.9.9 - 2026-07-18
+
+### Improved
+
+- Reworked paid hosted SAP agent discovery so `sap_discover_agents`,
+  `sap_list_agents`, and `sap_list_all_agents` enumerate the canonical
+  on-chain `AgentAccount` directory and then apply server-side filters. This
+  avoids stale capability/protocol index false negatives for agents such as
+  XONA while preserving paid hosted monetization.
+- Added first-class hosted directory filters for `query`, `wallet`, `agentPda`,
+  `protocol`, `capability`, `capabilities`, `capabilityMode`,
+  `hasX402Endpoint`, `view`, `limit`, `offset`, and opaque
+  `pagination.nextCursor`.
+- Kept legacy response aliases (`count`, `returned`, `offset`, `limit`,
+  `truncated`, `totalEnumerated`) and the deprecated `hydrate` input so older
+  agent recipes continue to work while newer agents use the paginated response.
+- Updated bundled skills, startup guidance, and user docs so agents prefer
+  targeted paid discovery, follow cursors, and retry with `query` or `wallet`
+  before claiming an on-chain SAP agent is absent.
+
+## 0.9.8 - 2026-07-18
+
+### Fixed
+
+- Added a hosted-accountless execution guard so direct write tools that require
+  a user-owned signer are rejected before x402 verification or settlement. Tools
+  such as `sap_register_agent`, `sap_sns_register_agent_domain`,
+  `sap_sign_transaction`, direct swaps, token transfers, NFT mints, and bridge
+  writes now return `hosted_local_signer_required` with
+  `paymentNotCharged: true` when called against the non-custodial hosted
+  server.
+- Made single-domain SNS availability checks free with
+  `sap_sns_check_domain`, so agents can discover whether a `.sol` name is
+  available before routing the user into a local signer flow.
+- Updated prompts, bundled skills, and payment docs so agents use local
+  `sap_payments_call_paid_tool` for paid hosted calls and
+  `sap_payments_finalize_transaction` for unsigned hosted builders, instead of
+  retrying impossible hosted signer writes or creating temporary signing
+  scripts.
+
+## 0.9.7 - 2026-07-17
+
+### Fixed
+
+- Fixed Hermes/OpenClaw YAML generation for hosted SAP MCP plus local
+  `sap_payments` bridge configs. The wizard and repair flow now double-quote
+  YAML scalar values such as scoped npm package names
+  (`@oobe-protocol-labs/sap-mcp-server@...`) and indent `args` list items with
+  parser-safe YAML.
+- Updated user docs and generated manual snippets so copied Hermes YAML no
+  longer fails on reserved leading characters such as `@`.
+- Clarified local keypair signer logs: hosted SAP MCP never receives keypair
+  bytes, while production/value funds should prefer external signer, hardware
+  wallet, delegated session, or a capped local profile.
+
+## 0.9.6 - 2026-07-17
+
+### Added
+
+- Added free hosted maintenance tools:
+  - `sap_skills_upgrade_plan` returns latest-release skill upgrade commands,
+    target directories, and next tool calls without pretending hosted MCP can
+    write local files.
+  - `sap_runtime_repair_plan` returns the pinned repair command, OS command
+    aliases, expected `sap_payments` bridge tools, and runtime restart guidance.
+
+### Fixed
+
+- Fixed structured MCP output for tools with explicit output schemas. Tools such
+  as `sap_agent_start` now return schema-valid `structuredContent` instead of a
+  nested MCP `content` wrapper, avoiding strict runtime errors like
+  `success is a required property`.
+- Updated the agent startup playbook so stale skills and missing
+  `sap_payments` bridge issues route through free maintenance tools before paid
+  or write workflows.
+- Updated user docs and bundled skills to teach `sap_skills_upgrade_plan` and
+  `sap_runtime_repair_plan` as the canonical recovery path.
+
+## 0.9.5 - 2026-07-17
+
+### Added
+
+- Added a first-step setup path menu to the CLI wizard so users can choose
+  **Full hosted SAP MCP setup**, **Repair hosted runtime + sap_payments bridge
+  only**, or manual snippets before any profile/wallet prompts.
+- Added `sap-mcp-config repair` plus `repair-payments` and `repair-bridge`
+  aliases for users who already have a local SAP MCP profile and only need to
+  repair hosted `sap` plus local `sap_payments` runtime entries.
+
+### Fixed
+
+- Made the repair-only path use the same auto-resolver as the full wizard,
+  preserving unrelated MCP servers while updating only OOBE SAP MCP entries,
+  stale `mcp-remote` wrappers, SAP allow-list issues, and the local x402
+  reference bundle.
+- Updated user docs, README, and the hosted dashboard so normal users can find
+  the repair path without rerunning full profile/wallet setup.
+
+## 0.9.4 - 2026-07-17
+
+### Added
+
+- Added `sap_payments_finalize_transaction`, a free local `sap_payments` bridge
+  tool that previews, policy-checks, signs, and optionally submits unsigned
+  transactions returned by hosted SAP MCP builders.
+- Added regression coverage proving the bridge-only process exposes the local
+  finalizer and can sign a hosted-style transaction without temporary scripts or
+  keypair-byte exposure.
+
+### Fixed
+
+- Updated agent prompts, skills, docs, wizard copy, and public dashboard
+  guidance so hosted builders route transaction finalization through the local
+  bridge instead of hosted `sap_sign_transaction` or ad-hoc `.js`/`.mjs`
+  signing scripts.
+- Tightened the bridge-only tool list in docs to match the actual
+  `sap_payments` surface.
+
+## 0.9.3 - 2026-07-17
+
+### Changed
+
+- Rebalanced hosted x402 pricing for agent commerce UX: premium reads now
+  default to `$0.001`, builder/preflight calls default to `$0.008`, and
+  value-moving actions stay on the value-action tier.
+- Classified `jupiter_getQuote` and `magicblock_swapQuote` as lightweight
+  read-premium calls instead of builder calls, so agents can quote and preview
+  without paying value-action style fees.
+- Kept SAP payment readiness, x402 estimates, transaction decode, and
+  transaction preview free so agents can choose tools, check limits, and prepare
+  safe execution without bottlenecks.
+
+### Fixed
+
+- Strengthened SAP MCP initialize instructions, `sap_agent_start`, transaction
+  tool descriptions, and MagicBlock tool descriptions so agents use the official
+  `sap_preview_transaction` -> `sap_sign_transaction` ->
+  `sap_submit_signed_transaction` path instead of creating temporary local
+  signing scripts or reading keypair files.
+- Removed hard-coded MagicBlock `$0.01`/`$0.05` pricing text from tool
+  descriptions; hosted prices now resolve from the central pricing registry.
+
 ## 0.9.2 - 2026-07-17
 
 ### Added