@gholl-studio/pier-connector 0.0.2 → 0.0.3

package/README.md

@@ -17,7 +17,7 @@
 - **Pier Account**: A valid account with access to the job marketplace
 - **Network**: Stable internet connection
 
-> 💡 **Note**: The plugin handles all connection logic internally. You only need to configure your **Pier API Token** in the settings. No external message brokers (like NATS) or custom server setups are required.
+> 💡 **Note**: The plugin handles registration and heartbeat logic internally. You only need to configure your **Pier API URL/Key** in the settings. The plugin will automatically negotiate NATS connection details with the backend.
 
 ## Installation
 
@@ -34,9 +34,21 @@ openclaw plugins enable pier-connector
 
 Restart the OpenClaw Gateway.
 
-## Configuration
+Restart the OpenClaw Gateway.
+
+## ⚙️ How to Configure
+
+There are two ways to configure the plugin:
+
+### 1. Interactive CLI (Recommended)
+Run the following command in your terminal:
+```bash
+openclaw pier setup
+```
+This will guide you through setting up your API URL, Key, and Wallet.
 
-Configure via `plugins.entries.pier-connector.config`:
+### 2. Manual Config
+Add the following to your `openclaw.config.json` under `plugins.entries.pier-connector.config`:
 
 ```json
 {
@@ -45,12 +57,9 @@ Configure via `plugins.entries.pier-connector.config`:
       "pier-connector": {
         "enabled": true,
         "config": {
-          "natsUrl": "wss://pier.gholl.com/nexus",
-          "subject": "jobs.worker",
-          "publishSubject": "jobs.submit",
-          "queueGroup": "openclaw-workers",
-          "workerId": "agent-001",
-          "walletAddress": "0xABC123"
+          "apiUrl": "https://pier.gholl.com",
+          "apiKey": "your-api-key-here",
+          "walletAddress": "0xYourWalletAddress"
         }
       }
     }
@@ -58,14 +67,14 @@ Configure via `plugins.entries.pier-connector.config`:
 }
 ```
 
-| Option           | Default                        | Description                          |
-|------------------|--------------------------------|--------------------------------------|
-| `natsUrl`        | `wss://pier.gholl.com/nexus`   | NATS WebSocket server URL            |
-| `subject`        | `jobs.worker`                  | Subject to subscribe for incoming jobs |
-| `publishSubject` | `jobs.submit`                  | Subject for outbound task publishing |
-| `queueGroup`     | `openclaw-workers`             | NATS Queue Group for load balancing  |
-| `workerId`       | `""`                           | Unique identifier for this agent worker |
-| `walletAddress`  | `""`                           | Wallet address for receiving rewards |
+| Option          | Default                      | Description                                      |
+|-----------------|------------------------------|--------------------------------------------------|
+| `apiUrl`        | `https://pier.gholl.com`     | Pier Backend API Base URL                        |
+| `apiKey`        | `""`                         | Your User API Key for platform authentication    |
+| `nodeId`        | `""`                         | (Auto-generated) Unique UUID for this node       |
+| `secretKey`     | `""`                         | (Auto-generated) Secret key for pulse verification |
+| `walletAddress` | `""`                         | Wallet address for receiving job rewards         |
+| `natsUrl`       | `""`                         | (Optional) Manual NATS override                  |
 
 ## How It Works
 
@@ -119,8 +128,8 @@ Use `/pier` in any OpenClaw channel to check connector status.
   "result": "The AI's generated response",
   "latencyMs": 1450,
   "worker": {
-    "id": "agent-001",
-    "wallet": "0xABC123"
+    "id": "uuid-node",
+    "wallet": "0xYourWalletAddress"
   }
 }
 ```
@@ -138,8 +147,8 @@ Use `/pier` in any OpenClaw channel to check connector status.
     "message": "Error details"
   },
   "worker": {
-    "id": "agent-001",
-    "wallet": "0xABC123"
+    "id": "uuid-node",
+    "wallet": "0xYourWalletAddress"
   }
 }
 ```

package/openclaw.plugin.json

@@ -10,25 +10,20 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-            "apiUrl": {
+            "pierApiUrl": {
                 "type": "string",
-                "default": "https://pier.gholl.com",
-                "description": "Pier Backend API Base URL"
-            },
-            "apiKey": {
-                "type": "string",
-                "default": "",
-                "description": "User API Key for platform authentication"
+                "default": "https://pier-connector.gholl.com/api/v1",
+                "description": "Pier API Endpoint (from Website)"
             },
             "nodeId": {
                 "type": "string",
                 "default": "",
-                "description": "Unique identifier for this agent worker node (UUID)"
+                "description": "Bot Node ID (obtain from pier-connector.gholl.com)"
             },
             "secretKey": {
                 "type": "string",
                 "default": "",
-                "description": "Secret key for node authentication and heartbeats"
+                "description": "Bot Secret Key (obtain from pier-connector.gholl.com)"
             },
             "natsUrl": {
                 "type": "string",
@@ -58,20 +53,16 @@
         }
     },
     "uiHints": {
-        "apiUrl": {
+        "pierApiUrl": {
             "label": "Pier API URL",
-            "placeholder": "https://pier.gholl.com"
-        },
-        "apiKey": {
-            "label": "API Key",
-            "placeholder": "Bearer token ..."
+            "placeholder": "https://pier-connector.gholl.com/api/v1"
         },
         "nodeId": {
-            "label": "Node ID",
+            "label": "Bot Node ID",
             "placeholder": "uuid-..."
         },
         "secretKey": {
-            "label": "Secret Key",
+            "label": "Bot Secret Key (Secret)",
             "placeholder": "sk_..."
         },
         "natsUrl": {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@gholl-studio/pier-connector",
     "author": "gholl",
-    "version": "0.0.2",
+    "version": "0.0.3",
     "description": "OpenClaw plugin that connects to the Pier job marketplace. Automatically fetches, executes, and reports distributed tasks for rewards.",
     "type": "module",
     "main": "src/index.js",

package/src/config.js

@@ -6,12 +6,9 @@
 
 export const DEFAULTS = Object.freeze({
     /** Pier Backend API Base URL */
-    API_URL: 'https://pier.gholl.com',
+    PIER_API_URL: 'https://pier-connector.gholl.com/api/v1',
 
-    /** User API Key for HTTP Authentication */
-    API_KEY: '',
-
-    /** NATS WebSocket server URL (usually provided by API) */
+    /** NATS WebSocket server URL (usually provided by Heartbeat) */
     NATS_URL: 'wss://pier.gholl.com/nexus',
 
     /** NATS subject to subscribe for incoming jobs */

package/src/index.js

@@ -42,12 +42,11 @@ export default function register(api) {
     function resolveConfig() {
         const cfg = api.config?.plugins?.entries?.['pier-connector']?.config ?? {};
         return {
-            apiUrl: cfg.apiUrl || DEFAULTS.API_URL,
-            apiKey: cfg.apiKey || DEFAULTS.API_KEY,
+            pierApiUrl: cfg.pierApiUrl || DEFAULTS.PIER_API_URL,
             nodeId: cfg.nodeId || DEFAULTS.NODE_ID,
             secretKey: cfg.secretKey || DEFAULTS.SECRET_KEY,
             natsUrl: cfg.natsUrl || DEFAULTS.NATS_URL,
-            subject: cfg.subject || DEFAULTS.SUBJECT,
+            subject: cfg.subject || DEFAULTS.PIER_SUBJECT,
             publishSubject: cfg.publishSubject || DEFAULTS.PUBLISH_SUBJECT,
             queueGroup: cfg.queueGroup || DEFAULTS.QUEUE_GROUP,
             walletAddress: cfg.walletAddress || DEFAULTS.WALLET_ADDRESS,
@@ -57,55 +56,37 @@ export default function register(api) {
     /** Heartbeat timer reference */
     let heartbeatTimer = null;
 
-    // ── Registration & Heartbeat ───────────────────────────────────────
-
-    async function registerNode(config) {
-        if (config.nodeId && config.secretKey) return { nodeId: config.nodeId, secretKey: config.secretKey };
-
-        logger.info('[pier-connector] 🆕 Registering node with Pier Backend…');
-        const resp = await fetch(`${config.apiUrl}/api/v1/nodes/register`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${config.apiKey}`,
-            },
-            body: JSON.stringify({
-                wallet_address: config.walletAddress,
-                name: 'openclaw-node', // Could use OS hostname
-            }),
-        });
-
-        if (!resp.ok) {
-            const errText = await resp.text();
-            throw new Error(`Registration failed (${resp.status}): ${errText}`);
-        }
-
-        const data = await resp.json();
-        logger.info(`[pier-connector] ✅ Node registered! ID: ${data.id}`);
-        // Note: In a production plugin, we would call api.updateConfig here if available
-        return { nodeId: data.id, secretKey: data.secret_key, natsConfig: data.nats_config };
-    }
-
+    // ── Lifecycle: Heartbeat ──────────────────────────────────────────
+ 
+    /**
+     * Sends a heartbeat to the Pier Backend to stay active in the marketplace.
+     */
     async function heartbeatNode(config) {
-        const resp = await fetch(`${config.apiUrl}/api/v1/nodes/heartbeat`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${config.apiKey}`,
-            },
-            body: JSON.stringify({
-                node_id: config.nodeId,
-                secret_key: config.secretKey,
-                capabilities: ['gpt-4o', 'llama3', 'vision'], // Example capabilities
-                description: 'OpenClaw powered intelligence node',
-            }),
-        });
+        if (!config.nodeId || !config.secretKey) return null;
+
+        try {
+            const resp = await fetch(`${config.pierApiUrl}/nodes/heartbeat`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    node_id: config.nodeId,
+                    secret_key: config.secretKey,
+                    capabilities: ['translation', 'code-execution', 'reasoning', 'vision'],
+                    description: `OpenClaw Node (${config.nodeId.substring(0, 8)})`,
+                }),
+            });
+
+            if (!resp.ok) {
+                const errText = await resp.text();
+                throw new Error(`Heartbeat failed (${resp.status}): ${errText}`);
+            }
 
-        if (!resp.ok) {
-            throw new Error(`Heartbeat failed (${resp.status})`);
+            const data = await resp.json();
+            return data.nats_config || null;
+        } catch (err) {
+            logger.warn(`[pier-connector] Heartbeat failed: ${err.message}`);
+            return null;
         }
-
-        return await resp.json();
     }
 
     // ── 1. Register messaging channel ──────────────────────────────────
@@ -180,64 +161,84 @@ export default function register(api) {
         id: 'pier-connector',
 
         start: async () => {
+            const config = resolveConfig();
             logger.info('[pier-connector] 🚀 Starting background service …');
-            let config = resolveConfig();
 
             try {
-                // 1. Ensure node is registered
-                const reg = await registerNode(config);
-                config.nodeId = reg.nodeId;
-                config.secretKey = reg.secretKey;
-                const activeNatsUrl = config.natsUrl || reg.natsConfig?.url;
-
-                logger.info(`[pier-connector]    API URL          : ${config.apiUrl}`);
-                logger.info(`[pier-connector]    NATS URL         : ${activeNatsUrl}`);
-                logger.info(`[pier-connector]    Node ID          : ${config.nodeId}`);
-                if (config.walletAddress) logger.info(`[pier-connector]    Wallet           : ${config.walletAddress}`);
-
-                // 2. Start Heartbeat Loop
+                // 1. Mandatory credentials check
+                if (!config.nodeId || !config.secretKey) {
+                    logger.warn('[pier-connector] ⚠️ Bot Node ID or Secret is missing.');
+                    logger.warn('[pier-connector]    Please run "openclaw pier setup" or go to pier-connector.gholl.com to create a bot.');
+                    connectionStatus = 'error';
+                    return;
+                }
+
+                connectionStatus = 'connecting';
+
+                // 2. Initial Pulse & Config fetch
+                logger.info(`[pier-connector] 💓 Sending initial pulse to ${config.pierApiUrl}...`);
+                const natsUpdate = await heartbeatNode(config);
+                const activeNatsUrl = natsUpdate?.url || config.natsUrl;
+
+                logger.info(`[pier-connector]    Node ID   : ${config.nodeId}`);
+                logger.info(`[pier-connector]    NATS URL  : ${activeNatsUrl}`);
+
+                // 3. Start Heartbeat Timer
                 const runHeartbeat = async () => {
-                    try {
-                        const hData = await heartbeatNode(config);
-                        logger.debug('[pier-connector] Heartbeat sent');
-                        // Potential NATS URL update could be handled here
-                    } catch (err) {
-                        logger.warn(`[pier-connector] Heartbeat failed: ${err.message}`);
-                    }
+                    const currentConfig = resolveConfig();
+                    if (!currentConfig.nodeId) return;
+                    await heartbeatNode(currentConfig);
                 };
-                await runHeartbeat();
                 heartbeatTimer = setInterval(runHeartbeat, 60000);
 
-                // 3. Connect to NATS
+                // 4. Connect to NATS
                 nc = await createNatsConnection(activeNatsUrl, logger);
                 connectionStatus = 'connected';
                 connectedAt = new Date();
 
-                // 4. Subscribe to Subjects
-                // Public pool
-                nc.subscribe(config.subject, { 
+                // 5. Subscribe to Subjects
+                const publicSubject = config.subject;
+                const privateSubject = `jobs.node.${config.nodeId}`;
+
+                logger.info(`[pier-connector] 👂 Listening to Marketplace: ${publicSubject}`);
+                logger.info(`[pier-connector] 👂 Listening to Direct Messages: ${privateSubject}`);
+
+                // Public pool with load balancing
+                nc.subscribe(publicSubject, { 
                     queue: config.queueGroup,
                     callback: (err, msg) => handleMessage(msg)
                 });
-                // Private direct channel
-                nc.subscribe(`jobs.node.${config.nodeId}`, { 
+                // Private direct channel (no queue group for broadcast/direct)
+                nc.subscribe(privateSubject, { 
                     callback: (err, msg) => handleMessage(msg)
                 });
 
-                logger.info(
-                    `[pier-connector] ✔ Subscribed to "${config.subject}" and "jobs.node.${config.nodeId}"`,
-                );
-
-                // Message handling logic moved to a reusable function
+                // Unified Message Handler
                 async function handleMessage(msg) {
-                    jobsReceived++;
                     const startTime = performance.now();
+                    const rawData = new TextDecoder().decode(msg.data);
+                    
+                    let payload;
+                    try {
+                        payload = JSON.parse(rawData);
+                    } catch (e) {
+                        logger.error(`[pier-connector] Failed to parse JSON: ${rawData.substring(0, 100)}`);
+                        return;
+                    }
 
+                    // V1.1 FEATURE: Task Poisoning / Poaching Protection
+                    if (payload.assigned_node_id && payload.assigned_node_id !== config.nodeId) {
+                        // Silent ignore - don't reply, don't log heavily
+                        return;
+                    }
+
+                    jobsReceived++;
                     const parsed = parseJob(msg, logger);
                     if (!parsed.ok) {
                         jobsFailed++;
+                        logger.error(`[pier-connector] Job parse error: ${parsed.error}`);
                         safeRespond(msg, createErrorPayload({
-                            id: msg.subject,
+                            id: 'unknown',
                             errorCode: 'PARSE_ERROR',
                             errorMessage: parsed.error,
                             workerId: config.nodeId,
@@ -281,6 +282,7 @@ export default function register(api) {
                         }));
                     }
                 }
+
                 // Monitor connection closure
                 nc.closed().then((err) => {
                     connectionStatus = 'disconnected';
@@ -295,6 +297,7 @@ export default function register(api) {
                 connectionStatus = 'error';
                 if (heartbeatTimer) clearInterval(heartbeatTimer);
                 logger.error(`[pier-connector] ✖ Failed to start: ${err.message}`);
+                logger.error(err.stack);
             }
         },
 
@@ -430,8 +433,8 @@ export default function register(api) {
                 text: [
                     `**Pier Connector Status**`,
                     `• Connection: ${connectionStatus}`,
-                    `• Node ID: ${config.nodeId || 'Unregistered'}`,
-                    `• API URL: ${config.apiUrl}`,
+                    `• Node ID: ${config.nodeId || 'N/A'}`,
+                    `• API URL: ${config.pierApiUrl}`,
                     `• NATS URL: ${config.natsUrl}`,
                     `• Subscribe: ${config.subject}`,
                     `• Publish: ${config.publishSubject}`,
@@ -446,45 +449,49 @@ export default function register(api) {
 
     api.registerCli(
         ({ program }) => {
-            program
+            // Find or create the 'pier' command namespace to avoid root conflicts
+            let pier = program.commands.find(c => c.name() === 'pier');
+            if (!pier) {
+                pier = program.command('pier').description('Pier connector commands');
+            }
+
+            pier
                 .command('setup')
                 .description('Interactively configure the Pier connector settings')
                 .action(async () => {
                     const currentConfig = resolveConfig();
                     
-                    console.log('\n🚢 \x1b[1m\x1b[36mPier Connector Setup\x1b[0m');
-                    console.log('Let\'s configure your OpenClaw node for the Pier job marketplace.\n');
+                    console.log('\n🚢 \x1b[1m\x1b[36mPier Connector Setup (V1.1)\x1b[0m');
+                    console.log('Please register your bot at \x1b[1m\x1b[33mhttps://pier-connector.gholl.com\x1b[0m first.\n');
 
                     const answers = await inquirer.prompt([
                         {
                             type: 'input',
-                            name: 'apiUrl',
-                            message: 'Pier API Base URL:',
-                            default: currentConfig.apiUrl,
+                            name: 'pierApiUrl',
+                            message: 'Pier API URL:',
+                            default: currentConfig.pierApiUrl,
                         },
                         {
-                            type: 'password',
-                            name: 'apiKey',
-                            message: 'User API Key:',
-                            default: currentConfig.apiKey,
+                            type: 'input',
+                            name: 'nodeId',
+                            message: 'Bot Node ID (UUID):',
+                            default: currentConfig.nodeId,
                         },
                         {
-                            type: 'input',
-                            name: 'natsUrl',
-                            message: 'NATS WebSocket URL (leave empty for auto):',
-                            default: currentConfig.natsUrl || '',
+                            type: 'password',
+                            name: 'secretKey',
+                            message: 'Bot Secret Key:',
+                            default: currentConfig.secretKey,
                         },
                         {
                             type: 'input',
                             name: 'walletAddress',
-                            message: 'Wallet Address (for rewards):',
+                            message: 'Your Wallet Address (for payout):',
                             default: currentConfig.walletAddress,
                         },
                     ]);
 
-                    // Determine how to save. According to standard OpenClaw plugin patterns
-                    // configurations are either written to user config or output instructions.
-                    // We'll output the configuration block for the user to copy/paste if direct edit fails.
+                    // Determine how to save.
                     console.log('\n✅ \x1b[32mConfiguration Captured!\x1b[0m\n');
                     
                     const newConfigBlock = {
@@ -493,9 +500,9 @@ export default function register(api) {
                                 "pier-connector": {
                                     enabled: true,
                                     config: {
-                                        apiUrl: answers.apiUrl,
-                                        apiKey: answers.apiKey,
-                                        natsUrl: answers.natsUrl || undefined,
+                                        pierApiUrl: answers.pierApiUrl,
+                                        nodeId: answers.nodeId,
+                                        secretKey: answers.secretKey,
                                         walletAddress: answers.walletAddress
                                     }
                                 }