shll-skills 2.0.5 → 2.0.7

package/SKILL.md

@@ -48,86 +48,102 @@ SHLL uses **two separate wallets** for maximum security:
 
 ## CONVERSATION FLOW: New User Onboarding
 
-When a user wants to use SHLL for the first time, follow this decision tree:
+🚨 **CORE PRINCIPLE: YOU execute ALL commands. The user NEVER runs CLI commands.**
+The user only needs to: (1) answer simple questions, (2) open a browser link, (3) click buttons on shll.run.
+You do everything else by running `shll-run` commands directly.
 
 ### Step 1: Generate operator wallet
 
-Ask: *"Do you already have an operator wallet set up for SHLL? (a RUNNER_PRIVATE_KEY)"*
+Ask: *"Do you already have an operator wallet (RUNNER_PRIVATE_KEY)?"*
 
-**If NO** → Generate one:
+**If NO** → YOU execute this right now:
 ```bash
 shll-run generate-wallet
 ```
 
-Tell the user:
-- *"I've generated an operator wallet for you."*
-- *"Address: `0xABC...` — send about $1 of BNB here for gas fees."*
-- *"Private key: `0x123...` — save this securely, then set it as RUNNER_PRIVATE_KEY."*
-- *"This is an OPERATOR wallet — it can only trade within safety limits. It CANNOT withdraw your vault funds or touch your agent ownership."*
+Then YOU set the environment variable from the output:
+```bash
+export RUNNER_PRIVATE_KEY="0x<key from output>"
+```
 
-**If YES** → Set it:
+Tell user the **address only** (for them to fund gas), and explain:
+- *"I've created and configured an operator wallet: `0xABC...`"*
+- *"Send a small amount of BNB (~0.001 BNB) to this address for gas fees."*
+- *"This wallet can only trade within safety limits — it cannot withdraw your vault."*
+- *"Save the private key I showed above securely."*
+
+**If YES** → YOU set it:
 ```bash
-export RUNNER_PRIVATE_KEY="0x..."
+export RUNNER_PRIVATE_KEY="0x<user's key>"
 ```
 
-### Step 2: Check gas balance & token-id
+### Step 2: Check balance & ask about token-id
 
+YOU execute:
 ```bash
 shll-run balance
 ```
 
-Ask user: *"Do you already have a SHLL Agent token-id (a number like 4, 5, etc.)?"*
+Show the result, then ask: *"Do you already have a SHLL Agent token-id (a number)?"*
 
-**If user says YES and gives a number** → Go to Step 4.
+- **If YES** → go to Step 4.
+- **If NO / don't know / "next" / "continue"** → go to Step 3.
 
-**If user says NO, or doesn't know, or says "next" / "continue" / any variation** → Go to Step 3 immediately.
+### Step 3: Create agent — YOU do this, not the user
 
-### Step 3: Create the agent — YOU MUST DO THIS, DO NOT SKIP
+**3a.** YOU query available agent templates:
+```bash
+shll-run listings
+```
+
+Show the user a clear list:
+*"Here are the available agents:"*
 
-🚨 **MANDATORY**: If the user doesn't have a token-id, you MUST run `setup-guide` RIGHT NOW. Do not ask them to "go to a website". Do not keep asking for a token-id they don't have. YOU generate the link for them.
+| # | Name | Type | Price/day | Min days |
+|---|------|------|-----------|----------|
+| 1 | LLM Trader Agent | llm_trader | 0.0005 BNB | 1 |
 
-**First ask**: *"How many days do you want to rent the agent? (default: 1 day, you can extend later)"*
-- If user says a number → use that number.
-- If user says "default" / "ok" / doesn't specify → use 1.
+*"Which one do you want? And how many days? (default: 1 day, can extend later)"*
 
-**Then immediately run**:
+**3b.** Once user picks, YOU execute:
 ```bash
-shll-run setup-guide --listing-id <LISTING_ID> --days <DAYS>
+shll-run setup-guide --listing-id <SELECTED_ID> --days <DAYS>
 ```
 
-Then tell the user:
+Take the `setupUrl` from the JSON output and tell the user:
 
-*"I've generated your setup link. This page lets you **pay the rental fee** and **authorize the operator wallet** — open it now:*
-*👉 `<URL from command output>`*
+*"I've prepared everything. Now open this link to **pay the rental fee and authorize the operator wallet**:*
+*👉 `<setupUrl>`*
 
-*⚠️ Connect your **personal wallet** (MetaMask / hardware wallet) — NOT the operator wallet I generated earlier.*
+*⚠️ Connect your **personal wallet** (MetaMask / hardware wallet) — NOT the operator wallet.*
 
 *The page walks you through:*
-1. *Pay — pays the rental fee, mints your Agent NFT*
-2. *Authorize — allows the operator wallet to trade on your behalf*
-3. *Fund — deposits BNB into the trading vault (optional, can skip)*
-4. *Done — shows your **token-id** number*
+1. *Pay — rental fee, creates your Agent NFT*
+2. *Authorize — allows me to trade on your behalf*
+3. *Fund — deposit BNB to the trading vault (optional)*
+4. *Done — shows your **token-id***
+
+*Tell me the token-id when you're done."*
 
-*Paste the token-id here when you're done, and I'll start trading for you."*
+❌ **FORBIDDEN PATTERNS:**
+- Telling the user to run `shll-run` or `node dist/index.js` commands themselves
+- "Please prepare your token-id" (they don't have one yet!)
+- Showing raw CLI commands for the user to copy-paste
+- Asking for token-id repeatedly without running setup-guide first
 
-❌ **FORBIDDEN PATTERNS — never do any of these:**
-- "Please prepare your token-id" (user doesn't have one!)
-- "Go to shll.run and find your agent" (too vague!)
-- "I need your token-id to proceed" (you should be CREATING it for them!)
-- Asking for token-id more than once without running setup-guide
+### Step 4: Verify & ready to trade
 
-**If the user already has a token-id**, verify it:
+YOU execute:
 ```bash
-shll-run portfolio -k <ID>
+shll-run portfolio -k <TOKEN_ID>
 ```
 
-### Step 4: Ready to trade!
+Show results and tell user: *"Your agent is ready! What would you like to do?"*
 
-The user is now set up. They can ask you things like:
+Examples:
 - "Swap 0.1 BNB for USDC"
-- "What's in my portfolio?"
+- "What's my portfolio?"
 - "What's the price of CAKE?"
-- "Tighten my spending limit to 0.5 BNB per transaction"
 
 ---
 
@@ -138,7 +154,8 @@ The user is now set up. They can ask you things like:
 |---------|-------------|
 | `shll-run generate-wallet` | Create a new operator wallet (address + private key) |
 | `shll-run balance` | Check operator wallet BNB balance |
-| `shll-run setup-guide -l <LISTING> -d <DAYS>` | Output setup instructions + shll.run link for secure onboarding |
+| `shll-run listings` | List all available agent templates (name, type, price) |
+| `shll-run setup-guide [-l <LISTING>] [-d <DAYS>]` | Output setup link for onboarding (defaults: auto listing-id, 1 day) |
 | ~~`shll-run init`~~ | **DEPRECATED** — insecure single-wallet mode |
 
 ### Trading

package/dist/index.js

@@ -507,6 +507,7 @@ var DEFAULT_NFA = "0xe98dcdbf370d7b52c9a2b88f79bef514a5375a2b";
 var DEFAULT_GUARD = "0x25d17ea0e3bcb8ca08a2bfe917e817afc05dbbb3";
 var DEFAULT_RPC = "https://bsc-dataseed1.binance.org";
 var DEFAULT_LISTING_MANAGER = "0x322E7b1DaefE32E3D25defEA731C6384425E5A9f";
+var DEFAULT_LISTING_ID = "0x792d9b08749fd9739b7e57217daa08a673042fe9e1e1c35545e99acb72c12186";
 var PANCAKE_V2_ROUTER = "0x10ED43C718714eb63d5aA57B78B54704E256024E";
 var WBNB = "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c";
 var TOKEN_REGISTRY = {
@@ -1466,7 +1467,42 @@ configCmd.action(async (opts) => {
     process.exit(1);
   }
 });
-var setupGuideCmd = new import_commander.Command("setup-guide").description("Output step-by-step instructions for secure dual-wallet agent setup").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
+var DEFAULT_INDEXER = "https://indexer.shll.run";
+var listingsCmd = new import_commander.Command("listings").description("List all available agent templates for rent").option("--indexer <url>", "Indexer API URL", DEFAULT_INDEXER).action(async (opts) => {
+  try {
+    const indexerUrl = opts.indexer || DEFAULT_INDEXER;
+    const res = await fetch(`${indexerUrl}/api/listings`);
+    if (!res.ok) {
+      output({ status: "error", message: `Indexer returned ${res.status}` });
+      process.exit(1);
+    }
+    const data = await res.json();
+    const available = data.items.filter((l) => l.active);
+    if (available.length === 0) {
+      output({ status: "success", message: "No active listings found.", listings: [] });
+      return;
+    }
+    const listings = available.map((l) => ({
+      listingId: l.id,
+      name: l.agentName || "Unnamed Agent",
+      type: l.agentType || "unknown",
+      pricePerDayBNB: (Number(l.pricePerDay) / 1e18).toFixed(6),
+      minDays: l.minDays,
+      nfa: l.nfa
+    }));
+    output({
+      status: "success",
+      count: listings.length,
+      listings,
+      hint: "Use the listingId with setup-guide: shll-run setup-guide --listing-id <ID> --days <N>"
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
+var setupGuideCmd = new import_commander.Command("setup-guide").description("Output step-by-step instructions for secure dual-wallet agent setup").option("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)", DEFAULT_LISTING_ID).option("-d, --days <number>", "Number of days to rent", "1").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
 setupGuideCmd.action(async (opts) => {
   try {
     const pk = process.env.RUNNER_PRIVATE_KEY;
@@ -1626,6 +1662,7 @@ program.addCommand(transferCmd);
 program.addCommand(policiesCmd);
 program.addCommand(configCmd);
 program.addCommand(setupGuideCmd);
+program.addCommand(listingsCmd);
 program.addCommand(genWalletCmd);
 program.addCommand(balanceCmd);
 program.parse(process.argv);

package/dist/index.mjs

@@ -517,6 +517,7 @@ var DEFAULT_NFA = "0xe98dcdbf370d7b52c9a2b88f79bef514a5375a2b";
 var DEFAULT_GUARD = "0x25d17ea0e3bcb8ca08a2bfe917e817afc05dbbb3";
 var DEFAULT_RPC = "https://bsc-dataseed1.binance.org";
 var DEFAULT_LISTING_MANAGER = "0x322E7b1DaefE32E3D25defEA731C6384425E5A9f";
+var DEFAULT_LISTING_ID = "0x792d9b08749fd9739b7e57217daa08a673042fe9e1e1c35545e99acb72c12186";
 var PANCAKE_V2_ROUTER = "0x10ED43C718714eb63d5aA57B78B54704E256024E";
 var WBNB = "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c";
 var TOKEN_REGISTRY = {
@@ -1476,7 +1477,42 @@ configCmd.action(async (opts) => {
     process.exit(1);
   }
 });
-var setupGuideCmd = new Command("setup-guide").description("Output step-by-step instructions for secure dual-wallet agent setup").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
+var DEFAULT_INDEXER = "https://indexer.shll.run";
+var listingsCmd = new Command("listings").description("List all available agent templates for rent").option("--indexer <url>", "Indexer API URL", DEFAULT_INDEXER).action(async (opts) => {
+  try {
+    const indexerUrl = opts.indexer || DEFAULT_INDEXER;
+    const res = await fetch(`${indexerUrl}/api/listings`);
+    if (!res.ok) {
+      output({ status: "error", message: `Indexer returned ${res.status}` });
+      process.exit(1);
+    }
+    const data = await res.json();
+    const available = data.items.filter((l) => l.active);
+    if (available.length === 0) {
+      output({ status: "success", message: "No active listings found.", listings: [] });
+      return;
+    }
+    const listings = available.map((l) => ({
+      listingId: l.id,
+      name: l.agentName || "Unnamed Agent",
+      type: l.agentType || "unknown",
+      pricePerDayBNB: (Number(l.pricePerDay) / 1e18).toFixed(6),
+      minDays: l.minDays,
+      nfa: l.nfa
+    }));
+    output({
+      status: "success",
+      count: listings.length,
+      listings,
+      hint: "Use the listingId with setup-guide: shll-run setup-guide --listing-id <ID> --days <N>"
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
+var setupGuideCmd = new Command("setup-guide").description("Output step-by-step instructions for secure dual-wallet agent setup").option("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)", DEFAULT_LISTING_ID).option("-d, --days <number>", "Number of days to rent", "1").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
 setupGuideCmd.action(async (opts) => {
   try {
     const pk = process.env.RUNNER_PRIVATE_KEY;
@@ -1636,6 +1672,7 @@ program.addCommand(transferCmd);
 program.addCommand(policiesCmd);
 program.addCommand(configCmd);
 program.addCommand(setupGuideCmd);
+program.addCommand(listingsCmd);
 program.addCommand(genWalletCmd);
 program.addCommand(balanceCmd);
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shll-skills",
-    "version": "2.0.5",
+    "version": "2.0.7",
     "description": "SHLL Agent Runtime Skill for OpenClaw",
     "main": "dist/index.js",
     "bin": {

package/src/index.ts

@@ -20,6 +20,7 @@ const DEFAULT_NFA = "0xe98dcdbf370d7b52c9a2b88f79bef514a5375a2b";
 const DEFAULT_GUARD = "0x25d17ea0e3bcb8ca08a2bfe917e817afc05dbbb3";
 const DEFAULT_RPC = "https://bsc-dataseed1.binance.org";
 const DEFAULT_LISTING_MANAGER = "0x322E7b1DaefE32E3D25defEA731C6384425E5A9f";
+const DEFAULT_LISTING_ID = "0x792d9b08749fd9739b7e57217daa08a673042fe9e1e1c35545e99acb72c12186";
 const PANCAKE_V2_ROUTER = "0x10ED43C718714eb63d5aA57B78B54704E256024E";
 const WBNB = "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c";
 
@@ -1240,11 +1241,68 @@ configCmd.action(async (opts) => {
     }
 });
 
+// -- Subcommand: listings (query available agent templates) --------
+const DEFAULT_INDEXER = "https://indexer.shll.run";
+
+const listingsCmd = new Command("listings")
+    .description("List all available agent templates for rent")
+    .option("--indexer <url>", "Indexer API URL", DEFAULT_INDEXER)
+    .action(async (opts) => {
+        try {
+            const indexerUrl = opts.indexer || DEFAULT_INDEXER;
+            const res = await fetch(`${indexerUrl}/api/listings`);
+            if (!res.ok) {
+                output({ status: "error", message: `Indexer returned ${res.status}` });
+                process.exit(1);
+            }
+            const data = await res.json() as {
+                items: Array<{
+                    id: string;
+                    agentName: string;
+                    agentType: string;
+                    pricePerDay: string;
+                    minDays: number;
+                    active: boolean;
+                    nfa: string;
+                    tokenId: string;
+                    owner: string;
+                }>;
+                count: number;
+            };
+
+            const available = data.items.filter((l) => l.active);
+            if (available.length === 0) {
+                output({ status: "success", message: "No active listings found.", listings: [] });
+                return;
+            }
+
+            const listings = available.map((l) => ({
+                listingId: l.id,
+                name: l.agentName || "Unnamed Agent",
+                type: l.agentType || "unknown",
+                pricePerDayBNB: (Number(l.pricePerDay) / 1e18).toFixed(6),
+                minDays: l.minDays,
+                nfa: l.nfa,
+            }));
+
+            output({
+                status: "success",
+                count: listings.length,
+                listings,
+                hint: "Use the listingId with setup-guide: shll-run setup-guide --listing-id <ID> --days <N>",
+            });
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            output({ status: "error", message });
+            process.exit(1);
+        }
+    });
+
 // -- Subcommand: setup-guide (secure dual-wallet onboarding) ------
 const setupGuideCmd = new Command("setup-guide")
     .description("Output step-by-step instructions for secure dual-wallet agent setup")
-    .requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)")
-    .requiredOption("-d, --days <number>", "Number of days to rent")
+    .option("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)", DEFAULT_LISTING_ID)
+    .option("-d, --days <number>", "Number of days to rent", "1")
     .option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC)
     .option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER)
     .option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
@@ -1433,6 +1491,7 @@ program.addCommand(transferCmd);
 program.addCommand(policiesCmd);
 program.addCommand(configCmd);
 program.addCommand(setupGuideCmd);
+program.addCommand(listingsCmd);
 program.addCommand(genWalletCmd);
 program.addCommand(balanceCmd);
 program.parse(process.argv);