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

package/skills/sap-discovery-indexing/SKILL.md

@@ -18,16 +18,38 @@ indexes, and filtered agent discovery.
 
 ## Rules
 
-- Use `sap_list_all_agents` for global directory requests.
-- Use `sap_discover_agents` only with `protocol`, `capability`, or
-  `capabilities`.
+- Start with free orientation when possible:
+  - `sap_agent_context` for a one-shot compact context read and routing hints.
+  - `sap_get_agent` or `sap_get_agent_profile` for a known owner wallet.
+  - `sap_is_agent_active` for a known owner wallet status check.
+  - `sap_get_global_state` for compact registry state.
+  - `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+    `includeProtocolIndexes: false` for a small current directory page.
+- Use `sap_discover_agents` for paid hosted agent directory search. It supports
+  `query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
+  `capabilityMode`, `hasX402Endpoint`, `limit`, `cursor`, and `view`.
+- Use `sap_list_all_agents` for global directory requests or when the user asks
+  for the whole SAP ecosystem. Keep the first page small and follow
+  `pagination.nextCursor` only when the previous page is useful.
+- Use paid discovery only when the user needs search, enrichment, full rows,
+  large pages, analytics, or global enumeration beyond the free compact page.
+- Prefer exact filters before broad scans: `wallet` when a wallet is known,
+  `query` for an agent name such as `XONA`, and `capability` for one exact
+  capability such as `creative:imageGeneration`.
 - Use `sap_fetch_protocol_index` when the protocol ID is known.
 - Use `sap_fetch_capability_index` when the capability ID is known.
+- If a capability-filtered lookup returns zero results, retry with `query` or
+  `wallet` before claiming the agent does not exist; capability indexes can lag
+  the canonical AgentAccount directory.
 - Do not guess that global enumeration is impossible; try `sap_list_all_agents`
-  first.
+  first and report the exact failure if it fails.
+- If discovery hits `payment_required`, a transient RPC error, or a missing
+  local bridge, call `sap_agent_next_action` before retrying or changing route.
 
 ## Common Inputs
 
 - Protocol IDs: `sap`, `jupiter`, `pyth`, `sns`, `mcp-v1`, or the exact
   protocol ID returned by protocol indexes.
 - Capability IDs usually use namespaced form such as `jupiter:swap`.
+- For x402-enabled agents, set `hasX402Endpoint: true` and use `view:
+  "compact"` until the user selects one row.

package/skills/sap-escrow-settlement/SKILL.md

@@ -7,6 +7,17 @@ new work.
 
 ## Tools
 
+Hosted unsigned builders:
+
+- `sap_escrow_build_create_transaction`
+- `sap_escrow_build_deposit_transaction`
+- `sap_escrow_build_settle_transaction`
+- `sap_escrow_build_finalize_transaction`
+- `sap_escrow_build_withdraw_transaction`
+- `sap_escrow_build_close_transaction`
+
+Local-signer direct writes:
+
 - `sap_create_escrow_v2`
 - `sap_deposit_escrow_v2`
 - `sap_settle_escrow_v2`
@@ -26,13 +37,20 @@ recommend V1 create, deposit, settle, withdraw, close, or batch-settle flows.
 ## Flow
 
 1. Fetch V2 escrow state before mutating it.
-2. For V2 settlement, inspect pending settlement and dispute state.
-3. Explain amount, depositor, agent PDA, nonce, settlement index, and dispute
+2. In hosted SAP MCP, never call direct escrow write tools after
+   `hosted_local_signer_required`. Use the matching
+   `sap_escrow_build_*_transaction` tool, then finalize the unsigned
+   transaction locally with `sap_payments_finalize_transaction`.
+3. In local SAP MCP stdio mode, direct write tools can sign through the active
+   local SAP profile. Do not read keypair JSON or create temporary signing
+   scripts.
+4. For V2 settlement, inspect pending settlement and dispute state.
+5. Explain amount, depositor, agent PDA, nonce, settlement index, and dispute
    effect before write tools.
-4. Treat `settlementSecurity = 2` / DisputeWindow as the safe default.
+6. Treat `settlementSecurity = 2` / DisputeWindow as the safe default.
    Use `settlementSecurity = 1` / CoSigned only when a valid `coSigner` is
    provided. Never default to SelfReport / `0`.
-5. Amounts are always in the smallest unit of the escrow token: lamports for
+7. Amounts are always in the smallest unit of the escrow token: lamports for
    SOL, micro-USDC for USDC.
 
 ## Safety

package/skills/sap-mcp/SKILL.md

@@ -8,16 +8,37 @@ safe signing behavior.
 
 If the user says "Start SAP MCP", "Initialize SAP MCP", "Load SAP", or "SAP
 mode", treat it as the activation command. Call `sap_agent_start` when it is
-available, then call `sap_skills_bundle` with `includeContents: true` and load
-the returned SAP MCP skill contents into context.
+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`
-2. `sap_profile_current`
-3. `sap_profile_list`
-4. `sap_profile_public_key`
-5. `sap_network_stats`
+2. `sap_agent_runtime_status` with `intent: "connection"`, `"paid-call"`, `"registry-write"`, `"transaction-finalize"`, `"escrow"`, `"identity"`, or `"general"`
+3. `sap_agent_context` for free compact agent/directory orientation before paid discovery
+4. `sap_skills_bundle` with `includeContents: true`
+5. `sap_pricing_catalog` before estimating hosted paid call tiers
+6. `sap_agent_next_action` before retrying after any SAP MCP error or partial write result
+7. `sap_skills_upgrade_plan` when local skills are missing or stale
+8. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
+9. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
+10. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
+11. `sap_profile_current`
+12. `sap_profile_list`
+13. `sap_profile_public_key`
+14. `sap_network_stats`
+
+For simple "are you connected?" checks, do not dump tool counts or inspect
+local files. Use `sap_agent_runtime_status` first and answer with the hosted
+endpoint, accountless/non-custodial model, local bridge readiness if visible,
+and the next exact action.
 
 The server profile is the source of truth. Environment variables from the MCP
 client must not override profile-owned RPC or wallet settings unless
@@ -32,12 +53,29 @@ 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
+  `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+  `includeProtocolIndexes: false`.
 - Use `sap_get_network_overview` for live ecosystem counters.
+- Use `sap_discover_agents` for targeted paid hosted discovery. Prefer
+  `query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
+  `hasX402Endpoint`, and small `limit` values before broad scans.
 - Use `sap_list_all_agents` when the user asks for all current SAP ecosystem
-  agents. It performs global on-chain `AgentAccount` enumeration.
-- Use `sap_discover_agents` or `sap_list_agents` only for filtered lookups by
-  `protocol`, `capability`, or `capabilities`.
+  agents. It performs global on-chain `AgentAccount` enumeration and returns
+  `pagination.nextCursor` when more pages are available.
+- Use `sap_list_agents` for a free compact orientation page first. Larger
+  pages, `view: "full"`, hydration, protocol index summaries, and global scans
+  are paid read-premium.
 - Use `sap_fetch_protocol_index` when a specific protocol ID is known.
+- If a capability lookup returns zero results, retry with `query` or `wallet`
+  before saying an agent is absent. AgentAccount rows are canonical; indexes can
+  lag.
 - Do not tell the user that all-agent enumeration is impossible unless
   `sap_list_all_agents` fails and you report the exact failure.
 
@@ -61,12 +99,19 @@ Use the bundled routing map for local MCP tool selection:
 - `USER_DOCS/05_SKILLS_AND_TOOLS.md`
 
 SAP MCP startup and skill bootstrap tools are free context/setup tools. Call
-`sap_agent_start`, `sap_skills_list`, `sap_skills_bundle`, and local
-`sap_skills_install` directly. Do not route startup, skill listing, bundling, or
-installation through `sap_x402_paid_call`. On hosted remote MCP, use
+`sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
+`sap_agent_next_action`, `sap_pricing_catalog`,
+`sap_skills_list`, `sap_skills_bundle`, `sap_skills_upgrade_plan`,
+`sap_runtime_repair_plan`, and local `sap_skills_install` directly. Do not
+route startup, runtime status, pricing catalog, skill listing, bundling,
+upgrade planning, runtime repair planning, or installation through
+`sap_x402_paid_call` or `sap_payments_call_paid_tool`. On hosted remote MCP, use
 `sap_skills_bundle` to download skill contents; the hosted server cannot
 install files onto the caller's local machine. Local installation belongs to the
 wizard, desktop app, addon installer, or a local stdio SAP MCP process.
+If skills or runtime bridge config are stale, call `sap_skills_upgrade_plan` or
+`sap_runtime_repair_plan` first. These tools return the pinned latest-release
+commands and preserve the non-custodial local signing model.
 
 ## Hosted Remote MCP
 
@@ -114,12 +159,13 @@ actions. The hosted MCP server is not a wallet custodian.
 
 For hosted paid tools, use the native x402 flow. If the client runtime cannot
 attach `PAYMENT-SIGNATURE` itself, use the local SAP MCP `sap_payments` bridge.
-Call `sap_payments_readiness` first to verify the active profile, signer,
-SOL/USDC balance, policy limits, and bridge status. Then call
-`sap_payments_call_paid_tool` for the hosted paid tool. This is not a separate
-hosted signing plugin: it is the local SAP MCP process using the user's
-configured SAP profile wallet or external signer to sign the x402 payment
-payload, retry the hosted tool call, and return the receipt.
+Call `sap_agent_runtime_status` first for routing, then
+`sap_payments_readiness` to verify the active profile, signer, SOL/USDC
+balance, policy limits, and bridge status. Then call `sap_payments_call_paid_tool`
+for the hosted paid tool. This is not a separate hosted signing plugin: it is
+the local SAP MCP process using the user's configured SAP profile wallet or
+external signer to sign the x402 payment payload, retry the hosted tool call,
+and return the receipt.
 `sap_x402_paid_call` is a backward-compatible alias only for older runtime
 snippets. Neither helper must be treated as a remote hosted signing service.
 
@@ -139,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
@@ -155,6 +210,52 @@ and arguments, `confirm: true`, and `maxAttempts: 5` so a fresh payment payload
 is created. Use `sap_x402_paid_call` only when a runtime still exposes the
 legacy alias.
 
+When a hosted paid/write builder returns `transactionBase64`, `transaction`, or
+another unsigned Solana transaction payload, finalize it locally with
+`sap_payments_finalize_transaction`. Do not call hosted `sap_sign_transaction`
+for a user-owned signer, do not create `.js`/`.mjs` signing scripts, and do not
+read keypair JSON.
+
+If hosted SAP MCP returns `hosted_local_signer_required`, no x402 payment was
+charged. The tool requires a local user signature or has no hosted unsigned
+builder yet. For `sap_register_agent`, call
+`sap_payments.sap_payments_register_agent` with the same registration fields and
+`confirm: true`; it runs the SAP registry write through the local signer bridge
+without charging a hosted x402 access fee. For `sap_update_agent`, call
+`sap_payments.sap_payments_update_agent` with the intended replacement fields
+and `confirm: true`; use it for public agent image/profile metadata updates via
+`agentUri` or `metadataUri`. For Escrow V2, call the matching
+`sap_escrow_build_*_transaction` hosted builder and finalize with
+`sap_payments_finalize_transaction`. For other direct writes, do not retry the
+same hosted tool; use the local SAP MCP profile or an unsigned hosted builder
+plus `sap_payments_finalize_transaction` when one exists.
+
+For registry lifecycle completion, do not treat a transaction signature alone
+as enough. After `sap_payments_register_agent`, verify `success`,
+`agentRegistered`, `agentPda`, `confirmationStatus`, `protocolComplete`, and
+the returned `protocolFee.status`. `success: true` means both the agent account
+and protocol fee invariant were verified. If `success` is false while
+`agentRegistered` is true, report that the account may exist but the SAP
+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:
+
+1. Hosted read or paid hosted read: direct hosted tool, or
+   `sap_payments_call_paid_tool` when x402 is required.
+2. Hosted unsigned transaction builder: finalize with
+   `sap_payments_finalize_transaction` and `submit: true` when the user confirms.
+3. SAP registry registration/update: use `sap_payments_register_agent` or
+   `sap_payments_update_agent`; do not retry hosted accountless writes.
+4. External x402 HTTP provider: use `sap_payments_call_external_x402`.
+5. Missing bridge: call `sap_runtime_repair_plan`, then tell the user to run the
+   pinned repair command or desktop wizard repair path.
+
 When summarizing a hosted connection, use language like:
 "server is non-custodial; user signatures come from the local SAP profile or
 external signer." Avoid saying "signer not configured", "read-only only",
@@ -170,6 +271,23 @@ the current agent runtime injected every tool as callable. If `tools/list`
 works but callable functions are missing, report a runtime reload/injection
 issue and ask the user to restart the runtime.
 
+If `sap_payments` tools are missing after the user says the wizard completed,
+call `sap_runtime_repair_plan`. Do not ask the user to manually rebuild their
+runtime config unless the repair plan has already failed or runtime startup logs
+show a concrete package/runtime error.
+
+For agent identity work, load the matching focused skills before acting:
+
+- register, update, profile image, capability, pricing, or x402 endpoint:
+  `sap-agent-registry`
+- NFT-backed identity, MPL Core, Metaplex metadata, creator/collection flows:
+  `sap-nft-metaplex`
+- `.sol` domain ownership, records, or primary identity:
+  `sap-sns`
+
+The canonical field and pipeline reference is
+`docs/16_SAP_AGENT_IDENTITY_PIPELINE.md`. Follow it before registry writes.
+
 ## Profile Tools
 
 | Tool | Purpose |

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -37,7 +37,7 @@ Profile, config, runtime context, and raw transaction lifecycle:
 
 SAP registry and discovery:
 
-`sap_register_agent`, `sap_update_agent`, `sap_deactivate_agent`,
+`sap_protocol_invariants`, `sap_agent_identity_plan`, `sap_register_agent`, `sap_update_agent`, `sap_deactivate_agent`,
 `sap_reactivate_agent`, `sap_close_agent`, `sap_get_agent`,
 `sap_get_agent_profile`, `sap_get_agent_stats`, `sap_get_global_state`,
 `sap_get_network_overview`, `sap_discover_agents`, `sap_list_agents`,
@@ -49,9 +49,30 @@ SAP registry and discovery:
 `sap_deactivate_tool`, `sap_reactivate_tool`,
 `sap_report_tool_invocations`, `sap_report_calls`.
 
-Use `sap_list_all_agents` for user requests such as "give me a list of all
-agents in the SAP ecosystem rn". Use `sap_discover_agents` only when the user
-provides a protocol or capability filter.
+Use free exact/base 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
+`sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+`includeProtocolIndexes: false`.
+Use `sap_discover_agents` for targeted paid hosted search by `query`, `wallet`,
+`agentPda`, `protocol`, `capability`, `capabilities`, or `hasX402Endpoint`.
+Use paid `sap_list_all_agents` for user requests such as "give me a list of all
+agents in the SAP ecosystem rn"; start with a small `limit` and continue with
+`pagination.nextCursor`. If a capability lookup returns zero, retry with
+`query` or `wallet` before reporting that the agent is absent.
+
+Use `sap_agent_next_action` before retrying any SAP MCP error or partial write
+result. It normalizes `payment_required`, `hosted_local_signer_required`,
+transient Solana RPC failures, missing local bridge tools, and unconfirmed
+submitted signatures into the next safe tool route.
+
+Use `sap_protocol_invariants` before registry writes when the program id,
+protocol treasury, source-level 0.1 SOL registration fee invariant, hosted
+write route, or local signer route is unclear. Use `sap_agent_identity_plan`
+before registration,
+profile/image updates, Metaplex identity bridging, SNS linking, or x402
+endpoint publishing. It is a free planner and should run before any local
+signer write.
 
 SAP memory and sessions:
 
@@ -72,6 +93,12 @@ SAP payments, x402, subscriptions, Escrow V2, settlement, disputes, staking:
 `sap_x402_prepare_payment`, `sap_x402_get_balance`,
 `sap_create_subscription`, `sap_fund_subscription`,
 `sap_cancel_subscription`, `sap_fetch_subscription`,
+`sap_escrow_build_create_transaction`,
+`sap_escrow_build_deposit_transaction`,
+`sap_escrow_build_settle_transaction`,
+`sap_escrow_build_finalize_transaction`,
+`sap_escrow_build_withdraw_transaction`,
+`sap_escrow_build_close_transaction`,
 `sap_create_escrow_v2`, `sap_deposit_escrow_v2`,
 `sap_settle_escrow_v2`, `sap_finalize_settlement_v2`,
 `sap_file_dispute_v2`, `sap_withdraw_escrow_v2`, `sap_close_escrow_v2`,
@@ -83,6 +110,13 @@ SAP payments, x402, subscriptions, Escrow V2, settlement, disputes, staking:
 Use `sap_fetch_escrow` only for legacy read-only inspection. V1 escrow write
 tools are not part of the active SAP MCP surface.
 
+In hosted mode, prefer `sap_escrow_build_*_transaction` for Escrow V2 writes
+and finalize the returned unsigned transaction locally with
+`sap_payments_finalize_transaction`. Use direct `sap_create_escrow_v2`,
+`sap_deposit_escrow_v2`, `sap_settle_escrow_v2`,
+`sap_finalize_settlement_v2`, `sap_withdraw_escrow_v2`, and
+`sap_close_escrow_v2` only when running a local SAP MCP profile with a signer.
+
 ## `sap-sns`
 
 SAP SNS and direct SNS domain workflows:
@@ -92,13 +126,16 @@ SAP SNS and direct SNS domain workflows:
 `sap_sns_get_domain_records`, `sap_sns_get_record`,
 `sap_sns_resolve_wallet`, `sap_sns_check_ownership`,
 `sap_sns_get_domain_pda`, `sap_sns_get_record_pda`,
-`sap_sns_build_register_domain_transaction`,
 `sap_sns_build_manage_record_transaction`,
-`sap_sns_build_set_primary_domain_transaction`,
 `sap_sns_register_agent_domain`, `sns_registerDomain`, `sns_resolveDomain`,
 `sns_reverseLookup`, `alldomains_getOwnedDomains`,
 `alldomains_registerDomain`, `alldomains_resolveDomain`.
 
+`sap_sns_register_agent_domain` is local-signer-only. Hosted accountless SAP MCP
+rejects that direct write before x402 payment. For hosted record changes, use
+`sap_sns_build_manage_record_transaction` and finalize the unsigned transaction
+locally with `sap_payments_finalize_transaction`.
+
 ## `sap-agentkit`
 
 Solana RPC, SPL token, pricing, DAS:
@@ -164,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-nft-metaplex/SKILL.md

@@ -32,6 +32,28 @@ flows.
 2. Validate collection, creator, metadata URI, royalties, and authority.
 3. Preview transaction-producing outputs before signing.
 
+## SAP Bridged Identity
+
+When the user wants an SAP agent picture, NFT-backed identity, MPL Core asset,
+or Metaplex-linked profile:
+
+1. Publish the image and metadata to a public URI. Desktop file paths are never
+   valid on-chain metadata.
+2. If creating a Metaplex NFT/MPL Core identity asset, mint or update that asset
+   with the same public metadata and keep the owner/authority clear.
+3. Register or update the SAP agent with `metadataUri`/`agentUri` pointing to
+   the public metadata document or profile page.
+4. In the metadata JSON, include a `metaplex` object with the asset or
+   collection address when available.
+5. Hosted users must use local `sap_payments_register_agent` or
+   `sap_payments_update_agent` for SAP registry writes. Do not call hosted
+   `sap_register_agent` or hosted `sap_update_agent` after
+   `hosted_local_signer_required`.
+
+Load `sap-agent-registry` together with this skill when the user says “register
+my agent”, “add my picture”, “link my NFT identity”, or “bridge SAP with
+Metaplex”.
+
 ## Safety
 
 Minting, listing, buying, authority changes, and metadata updates are high-risk.

package/skills/sap-operations/SKILL.md

@@ -19,6 +19,8 @@ This skill corresponds to upstream SAP SDK v1.0.x domains such as
 
 Use:
 
+- `sap_protocol_invariants`
+- `sap_agent_identity_plan`
 - `sap_register_agent`
 - `sap_update_agent`
 - `sap_deactivate_agent`
@@ -30,9 +32,36 @@ Use:
 - `sap_list_agents`
 - `sap_list_all_agents`
 
-Use `sap_list_all_agents` for global current ecosystem requests. Use
-`sap_discover_agents` and `sap_list_agents` only when the user provides a
-protocol or capability filter.
+Use `sap_discover_agents` for targeted hosted directory reads by `query`,
+`wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
+`hasX402Endpoint`. Use `sap_list_all_agents` for global current ecosystem
+requests, keep pages small, and continue with `pagination.nextCursor`.
+For first-pass orientation, prefer free reads: `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`. Use paid discovery
+only when the user needs search, enrichment, full rows, large pages, analytics,
+or global enumeration beyond the compact page.
+
+Before registering or updating an agent profile, call free
+`sap_protocol_invariants` when treasury, registration fee, hosted write route,
+or local signer route is unclear. Then call `sap_agent_identity_plan`. The
+planner tells the agent which fields are missing, whether the action should use
+hosted reads or local signing, whether Metaplex or SNS identity is involved,
+and how to verify the write afterward.
+
+Hosted accountless SAP MCP cannot sign wallet-owned registry writes. If hosted
+`sap_register_agent` or `sap_update_agent` returns
+`hosted_local_signer_required`, do not retry the hosted write. Use local
+`sap_payments_register_agent` or `sap_payments_update_agent` with
+`confirm: true`. After registration, verify `success`, `agentPda`,
+`confirmationStatus`, and `protocolFee.status`; after update, fetch the agent
+profile again and compare the changed fields.
+
+If any SAP operation returns `payment_required`, `hosted_local_signer_required`,
+`BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted signature
+that did not confirm, call `sap_agent_next_action` before retrying. Follow its
+`safeToRetryNow` and `nextTool` fields.
 
 ## Memory
 

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

@@ -9,6 +9,10 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 - `sap_x402_get_balance`
 - `sap_payments_profile_current`
 - `sap_payments_call_paid_tool`
+- `sap_payments_call_external_x402`
+- `sap_payments_register_agent`
+- `sap_payments_update_agent`
+- `sap_payments_finalize_transaction`
 - `sap_payments_prepare_challenge`
 - `sap_payments_sign_challenge`
 - `sap_payments_verify_receipt`
@@ -41,9 +45,16 @@ hosted calls still proceed through x402/pay.sh plus the user's local SAP profile
 or external signer.
 
 - Free: `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`,
-  `sap_get_network_overview`, `sol_get_balance`, `spl-token_getBalance`, and
-  `spl-token_getTokenAccounts`.
-- Read premium: `sap_list_all_agents`, indexed discovery, network stats,
+  `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
+  `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.
 - Builder: batch SNS/domain checks, analytics, transaction builders.
 - Value action: fixed fee plus configured basis-points fee when public USD
@@ -54,6 +65,11 @@ instructions, create a payment, retry with `PAYMENT-SIGNATURE`, and capture
 `PAYMENT-RESPONSE` after settlement. If a `payShCheckoutUrl` is present, surface
 it for browser/manual checkout flows.
 
+Before retrying `payment_required`, `hosted_local_signer_required`,
+`BlockhashNotFound`, timeout, missing `sap_payments`, or an unconfirmed
+signature, call `sap_agent_next_action`. Use its `safeToRetryNow`, `nextTool`,
+and `paymentCharged` fields as the retry guard.
+
 For fast x402 execution:
 
 1. Reuse the MCP session returned by `initialize`.
@@ -61,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
@@ -81,6 +107,57 @@ SAP MCP `sap_payments` bridge is already configured. The legacy
 `sap_x402_paid_call` alias is acceptable only when a runtime has not refreshed
 to the new tool name.
 
+For external x402 agents discovered through SAP registry metadata, do not
+hand-roll HTTP payment scripts. Call `sap_payments_call_external_x402` with
+`url`, `method`, optional JSON `body`, `maxPriceUsd`, `maxAttempts`, and
+`confirm: true`. Use this for non-SAP-hosted HTTP providers such as another
+agent's own x402 endpoint. It fetches the external 402 challenge, signs locally,
+retries the same HTTP request with `PAYMENT-SIGNATURE`, and returns the response
+plus receipt without exposing keypair bytes.
+
+For hosted-user SAP agent registration, do not retry hosted
+`sap_register_agent` after `hosted_local_signer_required`. The hosted server is
+accountless by design and cannot sign user-owned registry writes. Call local
+`sap_payments_register_agent` with the same registration fields and
+`confirm: true`; it uses the active local SAP MCP profile signer, submits the
+SAP registry transaction locally, and does not charge a hosted x402 access fee.
+After it returns, verify `success`, `agentRegistered`, `confirmationStatus`,
+`agentPda`, `protocolComplete`, and `protocolFee.status`. The expected protocol
+fee is `100000000` lamports to treasury
+`J7PyZAGKvprCz4SQ5DKBLAHstJxgVqZcz6kguUoWpP7P`. `success: true` means the agent
+account and protocol fee invariant were both verified. If `success` is false
+while `agentRegistered` is true, the account may exist but registration is not
+SAP protocol-complete; report that state and do not retry automatically.
+
+For hosted-user SAP agent profile updates, do not retry hosted
+`sap_update_agent` after `hosted_local_signer_required`. Call local
+`sap_payments_update_agent` with the intended replacement fields and
+`confirm: true`; it signs locally and does not charge a hosted x402 access fee.
+Use this for agent picture/profile metadata by first uploading the image or
+metadata JSON to a public URI such as IPFS, Arweave, Kommodo, or HTTPS, then
+setting `agentUri` or `metadataUri`. Do not use desktop file paths.
+After update, fetch the agent profile again and verify the changed fields.
+
+If the hosted paid tool returns `transactionBase64`, `transaction`, or an
+unsigned transaction object, call `sap_payments_finalize_transaction` with
+`confirm: true`. Set `submit: false` for preview/sign only, or `submit: true`
+after the user approves execution. With `submit: true`, the bridge submits
+already-signed bytes through `https://mcp.sap.oobeprotocol.ai/tx/submit` by
+default and returns `confirmationStatus` plus `retrySafe`. Treat
+`expired_or_not_landed` as unresolved, not success. Never create temporary
+signing scripts, read keypair JSON, or call hosted `sap_sign_transaction` for
+user-owned signatures.
+
+For Escrow V2 hosted workflows, use the unsigned builder family first:
+`sap_escrow_build_create_transaction`,
+`sap_escrow_build_deposit_transaction`,
+`sap_escrow_build_settle_transaction`,
+`sap_escrow_build_finalize_transaction`,
+`sap_escrow_build_withdraw_transaction`, or
+`sap_escrow_build_close_transaction`, then finalize locally with
+`sap_payments_finalize_transaction`. Use direct escrow write tools only when a
+local SAP MCP profile with signer is the selected runtime.
+
 Use low-level helpers only for custom clients:
 
 - `sap_payments_prepare_challenge` returns the parsed hosted x402 challenge