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

package/docs/README.md

@@ -64,6 +64,7 @@ For paid/write hosted tools, also configure the local `sap_payments` bridge. The
 - [Client Configs](user/04_CLIENT_CONFIGS.md)
 - [Payments: x402 And pay.sh](user/03_PAYMENTS_X402_PAYSH.md)
 - [Smithery And MCP Marketplaces](user/07_SMITHERY_AND_MARKETPLACES.md)
+- [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
 
 ## What The Hosted Server Provides
 
@@ -116,6 +117,7 @@ Read these first:
 5. [Desktop GUI Wizard](user/06_DESKTOP_GUI_WIZARD.md)
 6. [Configuration And Wizard](03_CONFIGURATION_AND_WIZARD.md)
 7. [Endpoints And Clients](07_ENDPOINTS_AND_CLIENTS.md)
+8. [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
 
 ## Public Endpoints
 

package/docs/magicblock-tools.md

@@ -38,6 +38,10 @@ Do not hard-code MagicBlock prices in agents. Call `sap_x402_estimate_cost` or
 the local `sap_payments_call_paid_tool` helper and enforce the user profile's
 `maxPriceUsd` / spend policy.
 
+Successful MagicBlock tool payloads intentionally do not report their own
+price. Hosted cost is authoritative only in the SAP MCP x402 challenge and the
+payment receipt returned by `sap_payments_call_paid_tool`.
+
 When a hosted MagicBlock builder returns an unsigned transaction, hosted SAP MCP
 remains non-custodial. Finalize the returned `transactionBase64` with the local
 `sap_payments_finalize_transaction` bridge. Do not call hosted
@@ -146,6 +150,28 @@ Expected flow:
 Agents must not create temporary JavaScript signing scripts, read keypair JSON,
 or sign raw message bytes outside SAP MCP transaction tools.
 
+## Safety Guardrails
+
+SAP MCP fails closed for MagicBlock flows that live testing has shown to be
+unsafe:
+
+- `magicblock_swap` with `visibility: "private"` requires a valid
+  `destination`. The server rejects the request before contacting MagicBlock if
+  the destination is missing or invalid.
+- `magicblock_swap` with `visibility: "private"` and
+  `quoteResponse.outputMint = So11111111111111111111111111111111111111112`
+  is blocked. Mainnet testing found that private swaps outputting wSOL can leave
+  funds stuck in the Hydra mixer pool when shuttle delivery fails. Use
+  `visibility: "public"` for SOL output, or swap privately into a non-SOL SPL
+  token until MagicBlock provides shuttle delivery recovery.
+- `magicblock_transfer` requires `from`, `to`, `mint`, `amount`,
+  `visibility`, `fromBalance`, and `toBalance`. `amount` must be a positive
+  JavaScript-safe integer in token base units because the upstream API expects a
+  JSON number, not a string.
+- Private transfers require a bearer token from `magicblock_challenge` and
+  `magicblock_login`. Private SOL transfers may deliver wSOL, not native SOL;
+  agents should say that clearly before asking for confirmation.
+
 ---
 
 ## Response Format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.9.13",
+  "version": "0.9.16",
   "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",
@@ -148,7 +148,10 @@
   "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",
     "langsmith": "^0.6.0",
     "uuid": "^11.1.1",
     "vite": "8.1.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.13",
+  "version": "0.9.16",
   "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.13",
+      "version": "0.9.16",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.13"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.16"
         },
         {
           "type": "positional",

package/skills/README.md

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

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

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

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

@@ -18,12 +18,21 @@ indexes, and filtered agent discovery.
 
 ## Rules
 
+- 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`.
@@ -34,6 +43,8 @@ indexes, and filtered agent discovery.
   the canonical AgentAccount directory.
 - Do not guess that global enumeration is impossible; try `sap_list_all_agents`
   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
 

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,19 +8,31 @@ 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.
 
 Always inspect runtime context through MCP tools, not by reading config files:
 
 1. `sap_agent_start`
-2. `sap_skills_bundle` with `includeContents: true`
-3. `sap_skills_upgrade_plan` when local skills are missing or stale
-4. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
-5. `sap_profile_current`
-6. `sap_profile_list`
-7. `sap_profile_public_key`
-8. `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
@@ -35,6 +47,11 @@ and error strings unchanged.
 
 ## Discovery Rules
 
+- 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`,
@@ -42,7 +59,9 @@ and error strings unchanged.
 - Use `sap_list_all_agents` when the user asks for all current SAP ecosystem
   agents. It performs global on-chain `AgentAccount` enumeration and returns
   `pagination.nextCursor` when more pages are available.
-- Use `sap_list_agents` as a compatibility alias for `sap_discover_agents`.
+- 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
@@ -70,11 +89,13 @@ 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`,
-`sap_skills_upgrade_plan`, `sap_runtime_repair_plan`, and local
-`sap_skills_install` directly. Do not route startup, skill listing, bundling,
+`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`. On hosted remote MCP, use
+`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.
@@ -128,12 +149,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.
 
@@ -180,9 +202,36 @@ 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 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.
+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.
+
+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
@@ -204,6 +253,18 @@ 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,12 +49,30 @@ SAP registry and discovery:
 `sap_deactivate_tool`, `sap_reactivate_tool`,
 `sap_report_tool_invocations`, `sap_report_calls`.
 
-Use `sap_discover_agents` for targeted paid hosted agent search by `query`,
-`wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
-`hasX402Endpoint`. Use `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 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:
 
@@ -75,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`,
@@ -86,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:

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`
@@ -34,6 +36,32 @@ 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