shll-skills 4.0.1 → 5.0.1

package/README.md

@@ -65,18 +65,30 @@ RUNNER_PRIVATE_KEY=0x... shll-mcp
 
 The server communicates via **stdio** using JSON-RPC 2.0. Send `tools/list` to discover all available tools.
 
-### Available MCP Tools
+### Available MCP Tools (20 total)
 
 | Tool | Type | Description |
 |------|------|-------------|
 | `portfolio` | Read | Vault holdings + token balances |
 | `balance` | Read | Operator wallet gas balance |
 | `price` | Read | Real-time token price (DexScreener) |
+| `search` | Read | Search token by name/symbol on BSC |
+| `tokens` | Read | List known token symbols + addresses |
 | `lending_info` | Read | Venus Protocol supply balances + APY |
+| `policies` | Read | View active on-chain policies + config |
+| `status` | Read | One-shot security overview (vault, operator, policies, activity) |
+| `history` | Read | Recent transactions + policy rejections |
+| `my_agents` | Read | List agents where current operator is authorized |
+| `listings` | Read | Available agent templates for rent |
 | `swap` | Write | PancakeSwap V2/V3 auto-routing swap |
+| `wrap` | Write | BNB → WBNB in vault |
+| `unwrap` | Write | WBNB → BNB in vault |
 | `lend` | Write | Supply tokens to Venus for yield |
 | `redeem` | Write | Withdraw from Venus |
 | `transfer` | Write | Send BNB or ERC20 from vault |
+| `config` | Write | Configure risk parameters (spending limits, cooldown) |
+| `setup_guide` | Info | Generate dual-wallet onboarding URL + steps |
+| `generate_wallet` | Info | Create new operator wallet (address + key) |
 
 ---
 
@@ -169,6 +181,20 @@ AI Agent -> CLI/MCP -> PolicyClient.validate() -> PolicyGuard (on-chain) -> vaul
 - npm: [shll-skills](https://www.npmjs.com/package/shll-skills)
 - GitHub: [kledx/shll-skills](https://github.com/kledx/shll-skills)
 
+## 🧩 Multi-Skill Compatibility
+
+SHLL can coexist with other DeFi skills (OKX DEX API, Bitget Wallet, etc.). Key architectural differences:
+
+| | **SHLL** | **OKX DEX API** | **Bitget Wallet** |
+|---|---|---|---|
+| **Wallet** | Smart contract vault (AgentNFA) | User EOA | Bitget custody |
+| **Execution** | On-chain via PolicyGuard | Calldata only (user signs) | HMAC API |
+| **Safety** | On-chain policy enforcement | User approval | API key perms |
+| **AI autonomy** | Execute within policy limits | Cannot execute | Full API access |
+| **Risk if key leaked** | Policy-limited trades only | N/A | Full API access |
+
+**SHLL is the only skill with on-chain policy enforcement.** Even if the AI hallucinates, the smart contract rejects unsafe operations.
+
 ## License
 
 MIT

package/SKILL.md

@@ -26,6 +26,7 @@ These rules are **non-negotiable**. Violating any of them is a critical failure.
 4. **One agent per conversation.** Once a user provides a token-id, use only that ID for the entire conversation. If they want to switch, they must explicitly say so.
 5. **Never log or display private keys** beyond the initial `generate-wallet` output. If the user asks you to repeat it, remind them to check their saved copy.
 6. **Do not infer trading intent.** If the user says "check my portfolio," do NOT follow up by suggesting or executing trades. Only trade when the user explicitly asks.
+7. **Multi-skill coexistence.** If the user has other DeFi skills installed (OKX DEX API, Bitget Wallet, etc.), **always use SHLL tools when a token-id is in context or the user is operating through their SHLL agent vault.** Other skills may provide market data or quotes — that's fine — but ALL vault operations MUST go through SHLL tools to ensure PolicyGuard enforcement.
 
 ---
 
@@ -229,6 +230,27 @@ All commands output JSON:
 - Rejected by policy: `{"status":"rejected", "reason":"Exceeds per-tx limit"}`
 - Error: `{"status":"error", "message":"..."}`
 
+---
+
+## 🧩 MULTI-SKILL COMPATIBILITY: How SHLL Differs from Other DeFi Skills
+
+If the user has multiple DeFi skills installed, understand the architectural differences:
+
+| | **SHLL** | **OKX DEX API** | **Bitget Wallet Skill** |
+|---|---|---|---|
+| **Wallet model** | Smart contract vault (AgentNFA) | User's EOA wallet | Bitget API custody |
+| **Execution** | On-chain via PolicyGuard | Generates calldata → user signs | HMAC API call → Bitget backend |
+| **Safety** | On-chain policy enforcement (spending limits, cooldowns, DEX whitelist) | User approval only | API key permissions |
+| **Fund location** | On-chain vault (isolated per agent) | User's wallet directly | Bitget platform |
+| **AI autonomy** | Can execute within policy limits | Cannot execute (calldata only) | Can execute via API |
+| **Risk if key leaked** | Limited to policy-allowed trades | N/A (no key) | Full API access |
+
+**Key distinction:** SHLL is the only skill with **on-chain policy enforcement**. Even if the AI makes a mistake, the smart contract rejects operations that violate spending limits or cooldowns. Other skills rely on the user or platform to gatekeep.
+
+**Routing rule:** When the user's intent involves their SHLL agent vault (identified by token-id), ALWAYS use SHLL tools. It's fine to use other skills for price quotes, market research, or operations outside SHLL.
+
+---
+
 ## LINKS
 - Website: https://shll.run
 - Twitter: @shllrun

package/dist/index.js

@@ -2152,6 +2152,71 @@ lendingInfoCmd.action(async (opts) => {
     process.exit(1);
   }
 });
+var OPERATOR_OF_ABI = [{
+  type: "function",
+  name: "operatorOf",
+  inputs: [{ name: "tokenId", type: "uint256" }],
+  outputs: [{ name: "", type: "address" }],
+  stateMutability: "view"
+}];
+var myAgentsCmd = new import_commander.Command("my-agents").description("List all agents where the current RUNNER_PRIVATE_KEY is the operator").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA).option("--indexer <url>", "Indexer base URL", DEFAULT_INDEXER);
+myAgentsCmd.action(async (opts) => {
+  try {
+    if (!process.env.RUNNER_PRIVATE_KEY) {
+      output({ status: "error", message: "RUNNER_PRIVATE_KEY environment variable is missing" });
+      process.exit(1);
+    }
+    const operator = (0, import_accounts2.privateKeyToAccount)(toHex(process.env.RUNNER_PRIVATE_KEY)).address.toLowerCase();
+    const rpcUrl = opts.rpc || DEFAULT_RPC;
+    const nfaAddr = toHex(opts.nfaAddress || DEFAULT_NFA);
+    const indexerUrl = (opts.indexer || DEFAULT_INDEXER).replace(/\/+$/, "");
+    const publicClient = (0, import_viem2.createPublicClient)({ chain: import_chains2.bsc, transport: (0, import_viem2.http)(rpcUrl) });
+    const res = await fetch(`${indexerUrl}/api/agents`);
+    if (!res.ok) {
+      output({ status: "error", message: `Indexer error: ${res.status}` });
+      process.exit(1);
+    }
+    const json = await res.json();
+    const agents = (json.items || []).filter((a) => !a.isTemplate && a.tokenId !== void 0);
+    if (agents.length === 0) {
+      output({ status: "success", agents: [], message: "No agents found in indexer" });
+      return;
+    }
+    const checks = await Promise.all(
+      agents.map(async (a) => {
+        const tokenId = BigInt(a.tokenId);
+        try {
+          const op = await publicClient.readContract({
+            address: nfaAddr,
+            abi: OPERATOR_OF_ABI,
+            functionName: "operatorOf",
+            args: [tokenId]
+          });
+          return {
+            tokenId: tokenId.toString(),
+            vault: a.account || "",
+            owner: a.owner || "",
+            agentType: a.agentType || "unknown",
+            isOperator: op.toLowerCase() === operator
+          };
+        } catch {
+          return null;
+        }
+      })
+    );
+    const myAgents = checks.filter((c) => c !== null && c.isOperator);
+    output({
+      status: "success",
+      operator,
+      agents: myAgents,
+      count: myAgents.length
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
 program.addCommand(swapCmd);
 program.addCommand(rawCmd);
 program.addCommand(tokensCmd);
@@ -2173,4 +2238,5 @@ program.addCommand(statusCmd);
 program.addCommand(lendCmd);
 program.addCommand(redeemCmd);
 program.addCommand(lendingInfoCmd);
+program.addCommand(myAgentsCmd);
 program.parse(process.argv);

package/dist/index.mjs

@@ -1664,6 +1664,71 @@ lendingInfoCmd.action(async (opts) => {
     process.exit(1);
   }
 });
+var OPERATOR_OF_ABI = [{
+  type: "function",
+  name: "operatorOf",
+  inputs: [{ name: "tokenId", type: "uint256" }],
+  outputs: [{ name: "", type: "address" }],
+  stateMutability: "view"
+}];
+var myAgentsCmd = new Command("my-agents").description("List all agents where the current RUNNER_PRIVATE_KEY is the operator").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA).option("--indexer <url>", "Indexer base URL", DEFAULT_INDEXER);
+myAgentsCmd.action(async (opts) => {
+  try {
+    if (!process.env.RUNNER_PRIVATE_KEY) {
+      output({ status: "error", message: "RUNNER_PRIVATE_KEY environment variable is missing" });
+      process.exit(1);
+    }
+    const operator = privateKeyToAccount(toHex(process.env.RUNNER_PRIVATE_KEY)).address.toLowerCase();
+    const rpcUrl = opts.rpc || DEFAULT_RPC;
+    const nfaAddr = toHex(opts.nfaAddress || DEFAULT_NFA);
+    const indexerUrl = (opts.indexer || DEFAULT_INDEXER).replace(/\/+$/, "");
+    const publicClient = createPublicClient({ chain: bsc, transport: http(rpcUrl) });
+    const res = await fetch(`${indexerUrl}/api/agents`);
+    if (!res.ok) {
+      output({ status: "error", message: `Indexer error: ${res.status}` });
+      process.exit(1);
+    }
+    const json = await res.json();
+    const agents = (json.items || []).filter((a) => !a.isTemplate && a.tokenId !== void 0);
+    if (agents.length === 0) {
+      output({ status: "success", agents: [], message: "No agents found in indexer" });
+      return;
+    }
+    const checks = await Promise.all(
+      agents.map(async (a) => {
+        const tokenId = BigInt(a.tokenId);
+        try {
+          const op = await publicClient.readContract({
+            address: nfaAddr,
+            abi: OPERATOR_OF_ABI,
+            functionName: "operatorOf",
+            args: [tokenId]
+          });
+          return {
+            tokenId: tokenId.toString(),
+            vault: a.account || "",
+            owner: a.owner || "",
+            agentType: a.agentType || "unknown",
+            isOperator: op.toLowerCase() === operator
+          };
+        } catch {
+          return null;
+        }
+      })
+    );
+    const myAgents = checks.filter((c) => c !== null && c.isOperator);
+    output({
+      status: "success",
+      operator,
+      agents: myAgents,
+      count: myAgents.length
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
 program.addCommand(swapCmd);
 program.addCommand(rawCmd);
 program.addCommand(tokensCmd);
@@ -1685,4 +1750,5 @@ program.addCommand(statusCmd);
 program.addCommand(lendCmd);
 program.addCommand(redeemCmd);
 program.addCommand(lendingInfoCmd);
+program.addCommand(myAgentsCmd);
 program.parse(process.argv);