@gholl-studio/pier-connector 0.0.1

package/README.md

@@ -0,0 +1,173 @@
+# pier-connector
+
+> **OpenClaw plugin — Connects directly to the Pier job marketplace.**
+> Automatically fetches jobs, lets OpenClaw's agent execute them, and instantly submits results back to the network.
+
+## ✨ Key Features
+
+- 🔄 **Auto-Polling**: Continuously listens for new tasks without manual intervention.
+- ⚡ **Smart Execution**: Leverages OpenClaw's native agent capabilities to handle complex jobs.
+- 📤 **Instant Reporting**: Submits results immediately upon completion to maximize reward efficiency.
+- 🔒 **Secure Connection**: Uses encrypted channels to communicate with the Pier ecosystem.
+
+## 📋 Requirements
+
+- **Node.js ≥ 22** (Required for latest async features)
+- **OpenClaw** (Version 2026.x or later) with plugins enabled
+- **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.
+
+## Installation
+
+```bash
+# Link for development
+openclaw plugins install -l /path/to/pier-connector
+
+# Or install from directory
+openclaw plugins install /path/to/pier-connector
+
+# Enable
+openclaw plugins enable pier-connector
+```
+
+Restart the OpenClaw Gateway.
+
+## Configuration
+
+Configure via `plugins.entries.pier-connector.config`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "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"
+        }
+      }
+    }
+  }
+}
+```
+
+| 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 |
+
+## How It Works
+
+### Accepting Jobs (Inbound)
+
+```
+Pier Platform → NATS "jobs.worker" → pier-connector → OpenClaw Agent → msg.respond(result)
+```
+
+1. Background service subscribes to `jobs.worker`
+2. Incoming NATS messages are parsed and routed to OpenClaw's agent via the `pier` channel
+3. The agent processes the task using its configured LLM
+4. The reply is sent back via `msg.respond()` as JSON
+
+### Publishing Tasks (Outbound)
+
+The agent can use the `pier_publish` tool to submit tasks:
+
+```
+OpenClaw Agent → pier_publish tool → NATS "jobs.submit" → Pier Platform
+```
+
+### Status
+
+Use `/pier` in any OpenClaw channel to check connector status.
+
+## Message Protocol
+
+### Inbound / Outbound Request (`task_request`)
+
+```json
+{
+  "version": "1.0",
+  "id": "uuid",
+  "type": "task_request",
+  "task": "The actual prompt or task description",
+  "systemPrompt": "(optional) override system behavior",
+  "timeoutMs": 60000,
+  "meta": { "sender": "user123", "price": 50 }
+}
+```
+
+### Response / Result (`task_result`)
+
+```json
+{
+  "version": "1.0",
+  "id": "uuid",
+  "type": "task_result",
+  "ok": true,
+  "result": "The AI's generated response",
+  "latencyMs": 1450,
+  "worker": {
+    "id": "agent-001",
+    "wallet": "0xABC123"
+  }
+}
+```
+
+### Error (`task_error`)
+
+```json
+{
+  "version": "1.0",
+  "id": "uuid",
+  "type": "task_error",
+  "ok": false,
+  "error": {
+    "code": "EXECUTION_FAILED",
+    "message": "Error details"
+  },
+  "worker": {
+    "id": "agent-001",
+    "wallet": "0xABC123"
+  }
+}
+```
+
+## Logging
+
+All logs use `api.logger` with `[pier-connector]` prefix:
+
+| Level   | Events                                                  |
+|---------|---------------------------------------------------------|
+| `info`  | Connection, subscription, job received/completed, publish |
+| `warn`  | Reconnection, empty tasks, fallback paths               |
+| `error` | Connection failure, job errors, publish failures        |
+
+## Project Structure
+
+```
+pier-connector/
+├── package.json              # ESM, Node ≥ 22, openclaw peer dep
+├── openclaw.plugin.json      # Plugin manifest, declares "pier" channel
+├── README.md
+└── src/
+    ├── index.js              # Plugin entry — channel + service + tool + command
+    ├── config.js             # Default constants
+    ├── nats-client.js        # NATS WebSocket connection manager
+    └── job-handler.js        # Message parsing and response utilities
+```
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,71 @@
+{
+    "id": "pier-connector",
+    "name": "Pier Connector",
+    "description": "Bridges the Pier job marketplace — accept and publish tasks via NATS WebSocket",
+    "version": "1.0.0",
+    "channels": [
+        "pier"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "natsUrl": {
+                "type": "string",
+                "default": "wss://pier.gholl.com/nexus",
+                "description": "NATS WebSocket server URL"
+            },
+            "subject": {
+                "type": "string",
+                "default": "jobs.worker",
+                "description": "NATS subject to subscribe for incoming jobs"
+            },
+            "publishSubject": {
+                "type": "string",
+                "default": "jobs.submit",
+                "description": "NATS subject for outbound task publishing"
+            },
+            "queueGroup": {
+                "type": "string",
+                "default": "openclaw-workers",
+                "description": "NATS Queue Group to join for load balancing tasks"
+            },
+            "workerId": {
+                "type": "string",
+                "default": "",
+                "description": "(Optional) Unique identifier for this agent worker"
+            },
+            "walletAddress": {
+                "type": "string",
+                "default": "",
+                "description": "(Optional) Wallet address or account ID for receiving rewards"
+            }
+        }
+    },
+    "uiHints": {
+        "natsUrl": {
+            "label": "NATS WebSocket URL",
+            "placeholder": "wss://pier.gholl.com/nexus"
+        },
+        "subject": {
+            "label": "Subscribe Subject (incoming jobs)",
+            "placeholder": "jobs.worker"
+        },
+        "publishSubject": {
+            "label": "Publish Subject (outbound tasks)",
+            "placeholder": "jobs.submit"
+        },
+        "queueGroup": {
+            "label": "Queue Group (Load Balancing)",
+            "placeholder": "openclaw-workers"
+        },
+        "workerId": {
+            "label": "Worker ID",
+            "placeholder": "agent-001"
+        },
+        "walletAddress": {
+            "label": "Wallet Address (Rewards)",
+            "placeholder": "0x..."
+        }
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@gholl-studio/pier-connector",
+    "author": "gholl",
+    "version": "0.0.1",
+    "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",
+    "engines": {
+        "node": ">=22"
+    },
+    "files": [
+        "src",
+        "openclaw.plugin.json",
+        "README.md"
+    ],
+    "openclaw": {
+        "extensions": [
+            "src/index.js"
+        ]
+    },
+    "scripts": {
+        "start": "node src/index.js",
+        "dev": "node --watch src/index.js"
+    },
+    "keywords": [
+        "openclaw",
+        "plugin",
+        "nats",
+        "pier",
+        "jobs"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "@nats-io/transport-node": "^3.0.0"
+    },
+    "peerDependencies": {
+        "openclaw": ">=2.0.0"
+    },
+    "peerDependenciesMeta": {
+        "openclaw": {
+            "optional": true
+        }
+    }
+}

package/src/config.js

@@ -0,0 +1,25 @@
+/**
+ * Default configuration constants for pier-connector.
+ * Values can be overridden via OpenClaw plugin config
+ * (plugins.entries.pier-connector.config).
+ */
+
+export const DEFAULTS = Object.freeze({
+    /** NATS WebSocket server URL */
+    NATS_URL: 'wss://pier.gholl.com/nexus',
+
+    /** NATS subject to subscribe for incoming jobs */
+    SUBJECT: 'jobs.worker',
+
+    /** NATS subject for outbound task publishing */
+    PUBLISH_SUBJECT: 'jobs.submit',
+
+    /** Default Queue Group for processing jobs (prevents duplicate work) */
+    QUEUE_GROUP: 'openclaw-workers',
+
+    /** Optional ID to identify this specific worker node */
+    WORKER_ID: '',
+
+    /** Optional Wallet address to receive points/payments for completed tasks */
+    WALLET_ADDRESS: '',
+});

package/src/index.js

@@ -0,0 +1,407 @@
+/**
+ * pier-connector — OpenClaw plugin entry point.
+ *
+ * Registers:
+ *  1. A messaging channel ("pier") for routing NATS jobs through OpenClaw agent
+ *  2. A background service that connects to NATS via WebSocket and subscribes
+ *  3. A tool ("pier_publish") for publishing tasks back to Pier
+ *  4. A command ("/pier") for checking connection status
+ */
+
+import { createNatsConnection, drainConnection } from './nats-client.js';
+import { parseJob, safeRespond, truncate } from './job-handler.js';
+import { createRequestPayload, createResultPayload, createErrorPayload } from './protocol.js';
+import { DEFAULTS } from './config.js';
+
+/**
+ * OpenClaw plugin register function.
+ *
+ * @param {object} api – OpenClaw plugin API
+ */
+export default function register(api) {
+    const logger = api.logger;
+
+    // ── shared state ───────────────────────────────────────────────────
+
+    /** @type {import('@nats-io/transport-node').NatsConnection | null} */
+    let nc = null;
+
+    /** @type {import('@nats-io/transport-node').Subscription | null} */
+    let subscription = null;
+
+    /** Connection status for the /pier command */
+    let connectionStatus = 'disconnected';
+    let jobsReceived = 0;
+    let jobsCompleted = 0;
+    let jobsFailed = 0;
+    let connectedAt = null;
+
+    // ── resolve plugin config ──────────────────────────────────────────
+
+    function resolveConfig() {
+        const cfg = api.config?.plugins?.entries?.['pier-connector']?.config ?? {};
+        return {
+            natsUrl: cfg.natsUrl || DEFAULTS.NATS_URL,
+            subject: cfg.subject || DEFAULTS.SUBJECT,
+            publishSubject: cfg.publishSubject || DEFAULTS.PUBLISH_SUBJECT,
+            queueGroup: cfg.queueGroup || DEFAULTS.QUEUE_GROUP,
+            workerId: cfg.workerId || DEFAULTS.WORKER_ID,
+            walletAddress: cfg.walletAddress || DEFAULTS.WALLET_ADDRESS,
+        };
+    }
+
+    // ── 1. Register messaging channel ──────────────────────────────────
+
+    const pierChannel = {
+        id: 'pier',
+
+        meta: {
+            id: 'pier',
+            label: 'Pier',
+            selectionLabel: 'Pier (NATS Job Marketplace)',
+            docsPath: '/plugins/pier-connector',
+            blurb: 'Accept and publish tasks on the Pier job marketplace via NATS.',
+            aliases: ['pier-connector'],
+        },
+
+        capabilities: {
+            chatTypes: ['direct'],
+        },
+
+        config: {
+            listAccountIds: () => ['default'],
+            resolveAccount: (_cfg, accountId) => ({
+                accountId: accountId ?? 'default',
+                enabled: true,
+            }),
+        },
+
+        outbound: {
+            deliveryMode: 'direct',
+
+            /**
+             * Send a reply text back through the NATS response.
+             * This is called by OpenClaw's agent after processing a job.
+             */
+            sendText: async ({ text, metadata }) => {
+                const jobId = metadata?.pierJobId;
+                const msg = metadata?.pierNatsMsg;
+
+                if (msg) {
+                    const elapsed = metadata?.pierStartTime
+                        ? (performance.now() - metadata.pierStartTime).toFixed(1)
+                        : null;
+
+                    const responsePayload = createResultPayload({
+                        id: jobId,
+                        reply: text,
+                        latencyMs: elapsed ? Number(elapsed) : undefined,
+                        workerId: resolveConfig().workerId,
+                        walletAddress: resolveConfig().walletAddress,
+                    });
+
+                    safeRespond(msg, responsePayload);
+
+                    jobsCompleted++;
+                    logger.info(
+                        `[pier-connector] ✔ Job ${jobId} completed` +
+                        (elapsed ? ` — latency: ${elapsed}ms` : ''),
+                    );
+                }
+
+                return { ok: true };
+            },
+        },
+    };
+
+    api.registerChannel({ plugin: pierChannel });
+
+    // ── 2. Register background service ─────────────────────────────────
+
+    api.registerService({
+        id: 'pier-connector',
+
+        start: async () => {
+            const config = resolveConfig();
+
+            logger.info('[pier-connector] 🚀 Starting background service …');
+            logger.info(`[pier-connector]    NATS URL         : ${config.natsUrl}`);
+            logger.info(`[pier-connector]    Subscribe subject : ${config.subject}`);
+            logger.info(`[pier-connector]    Queue Group       : ${config.queueGroup}`);
+            logger.info(`[pier-connector]    Publish subject   : ${config.publishSubject}`);
+            if (config.workerId) logger.info(`[pier-connector]    Worker ID         : ${config.workerId}`);
+            if (config.walletAddress) logger.info(`[pier-connector]    Wallet            : ${config.walletAddress}`);
+
+            try {
+                // Connect to NATS via WebSocket
+                nc = await createNatsConnection(config.natsUrl, logger);
+                connectionStatus = 'connected';
+                connectedAt = new Date();
+
+                // Subscribe to the jobs channel using a Queue Group to distribute work
+                subscription = nc.subscribe(config.subject, { queue: config.queueGroup });
+                logger.info(
+                    `[pier-connector] ✔ Subscribed to "${config.subject}" (group: "${config.queueGroup}") — waiting for jobs …`,
+                );
+
+                // Async message processing loop
+                (async () => {
+                    for await (const msg of subscription) {
+                        jobsReceived++;
+                        const startTime = performance.now();
+
+                        logger.info(
+                            `[pier-connector] 📨 Job #${jobsReceived} received on "${msg.subject}"`,
+                        );
+
+                        // Parse the incoming job
+                        const parsed = parseJob(msg, logger);
+
+                        if (!parsed.ok) {
+                            jobsFailed++;
+                            safeRespond(
+                                msg,
+                                createErrorPayload({
+                                    id: msg.subject, // Fallback ID
+                                    errorCode: 'PARSE_ERROR',
+                                    errorMessage: parsed.error,
+                                    workerId: config.workerId,
+                                    walletAddress: config.walletAddress,
+                                })
+                            );
+                            continue;
+                        }
+
+                        const { job } = parsed;
+                        logger.info(
+                            `[pier-connector] 📋 Job ${job.id}: "${truncate(job.task, 80)}"`,
+                        );
+
+                        // Route the job through OpenClaw's agent via the channel
+                        try {
+                            // Build an inbound message for the channel system
+                            const inbound = {
+                                channelId: 'pier',
+                                accountId: 'default',
+                                senderId: `pier:${job.meta?.sender ?? 'anonymous'}`,
+                                text: job.task,
+                                metadata: {
+                                    pierJobId: job.id,
+                                    pierNatsMsg: msg,
+                                    pierStartTime: startTime,
+                                    pierMeta: job.meta,
+                                },
+                            };
+
+                            // If a system prompt was provided, attach it
+                            if (job.systemPrompt) {
+                                inbound.systemPrompt = job.systemPrompt;
+                            }
+
+                            // Send to OpenClaw's agent pipeline
+                            if (api.runtime?.sendIncoming) {
+                                await api.runtime.sendIncoming(inbound);
+                            } else {
+                                // Fallback: direct agent invocation if sendIncoming is not available
+                                logger.warn(
+                                    '[pier-connector] api.runtime.sendIncoming not available, using direct response',
+                                );
+                                safeRespond(
+                                    msg,
+                                    createErrorPayload({
+                                        id: job.id,
+                                        errorCode: 'RUNTIME_UNAVAILABLE',
+                                        errorMessage: 'Agent runtime not available — plugin may need reconfiguration',
+                                        workerId: config.workerId,
+                                        walletAddress: config.walletAddress,
+                                    })
+                                );
+                                jobsFailed++;
+                            }
+                        } catch (err) {
+                            const elapsed = (performance.now() - startTime).toFixed(1);
+                            jobsFailed++;
+                            logger.error(
+                                `[pier-connector] ✖ Job ${job.id} failed after ${elapsed}ms — ${err.message}`,
+                            );
+                            safeRespond(
+                                msg,
+                                createErrorPayload({
+                                    id: job.id,
+                                    errorCode: 'EXECUTION_FAILED',
+                                    errorMessage: err.message,
+                                    workerId: config.workerId,
+                                    walletAddress: config.walletAddress,
+                                })
+                            );
+                        }
+                    }
+
+                    logger.info(
+                        `[pier-connector] Subscription loop ended. ` +
+                        `Total: ${jobsReceived} received, ${jobsCompleted} completed, ${jobsFailed} failed`,
+                    );
+                })();
+
+                // Monitor connection closure
+                nc.closed().then((err) => {
+                    connectionStatus = 'disconnected';
+                    if (err) {
+                        logger.error(
+                            `[pier-connector] NATS connection closed with error: ${err.message}`,
+                        );
+                    } else {
+                        logger.info('[pier-connector] NATS connection closed gracefully');
+                    }
+                });
+            } catch (err) {
+                connectionStatus = 'error';
+                logger.error(`[pier-connector] ✖ Failed to start: ${err.message}`);
+                logger.error(`[pier-connector]   Stack: ${err.stack}`);
+            }
+        },
+
+        stop: async () => {
+            logger.info('[pier-connector] 🛑 Stopping background service …');
+            connectionStatus = 'stopping';
+
+            if (subscription) {
+                subscription.unsubscribe();
+                subscription = null;
+            }
+
+            await drainConnection(nc, logger);
+            nc = null;
+            connectionStatus = 'disconnected';
+
+            logger.info('[pier-connector] ✔ Background service stopped');
+        },
+    });
+
+    // ── 3. Register pier_publish tool ──────────────────────────────────
+
+    api.registerTool(
+        {
+            name: 'pier_publish',
+            description:
+                'Publish a task to the Pier job marketplace. Other OpenClaw instances ' +
+                'subscribed to the Pier platform will receive and process the task.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    task: {
+                        type: 'string',
+                        description: 'The task description or prompt to publish',
+                    },
+                    meta: {
+                        type: 'object',
+                        description: 'Optional metadata to attach to the task',
+                    },
+                    timeoutMs: {
+                        type: 'number',
+                        description: 'Timeout in milliseconds to wait for a result (default 60000)',
+                    },
+                },
+                required: ['task'],
+            },
+
+            async execute(_id, params) {
+                if (!nc || connectionStatus !== 'connected') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    ok: false,
+                                    error: 'NATS not connected — cannot publish task',
+                                }),
+                            },
+                        ],
+                    };
+                }
+
+                const config = resolveConfig();
+                const timeout = params.timeoutMs || 60000;
+                
+                const taskPayload = createRequestPayload({
+                    task: params.task,
+                    timeoutMs: timeout,
+                    meta: params.meta,
+                });
+
+                try {
+                    logger.info(
+                        `[pier-connector] 📤 Publishing task to "${config.publishSubject}" and awaiting reply (timeout ${timeout}ms) — ` +
+                        `id: ${taskPayload.id}, task: "${truncate(params.task, 60)}"`,
+                    );
+
+                    const reply = await nc.request(
+                        config.publishSubject,
+                        new TextEncoder().encode(JSON.stringify(taskPayload)),
+                        { timeout }
+                    );
+
+                    let resultData;
+                    try {
+                        resultData = JSON.parse(new TextDecoder().decode(reply.data));
+                    } catch (e) {
+                         resultData = { raw: new TextDecoder().decode(reply.data) };
+                    }
+
+                    logger.info(`[pier-connector] ✔ Received result for task ${taskPayload.id}`);
+
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    ok: true,
+                                    taskId: taskPayload.id,
+                                    result: resultData,
+                                }),
+                            },
+                        ],
+                    };
+                } catch (err) {
+                    logger.error(`[pier-connector] ✖ Failed to publish or await task: ${err.message}`);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({ ok: false, error: err.message }),
+                            },
+                        ],
+                    };
+                }
+            },
+        },
+        { optional: true },
+    );
+
+    // ── 4. Register /pier status command ───────────────────────────────
+
+    api.registerCommand({
+        name: 'pier',
+        description: 'Show Pier connector status',
+        handler: () => {
+            const config = resolveConfig();
+            const uptime = connectedAt
+                ? `${Math.round((Date.now() - connectedAt.getTime()) / 1000)}s`
+                : 'N/A';
+
+            return {
+                text: [
+                    `**Pier Connector Status**`,
+                    `• Connection: ${connectionStatus}`,
+                    `• NATS URL: ${config.natsUrl}`,
+                    `• Subscribe: ${config.subject}`,
+                    `• Publish: ${config.publishSubject}`,
+                    `• Uptime: ${uptime}`,
+                    `• Jobs: ${jobsReceived} received, ${jobsCompleted} completed, ${jobsFailed} failed`,
+                ].join('\n'),
+            };
+        },
+    });
+
+    logger.info('[pier-connector] Plugin registered');
+}

package/src/job-handler.js

@@ -0,0 +1,80 @@
+/**
+ * Job handler — processes incoming NATS messages by routing them
+ * through OpenClaw's built-in agent and responding with results.
+ *
+ * No direct LLM calls — OpenClaw handles inference internally.
+ */
+
+/**
+ * Parse a raw NATS message into a structured job object.
+ *
+ * Expected inbound JSON:
+ * {
+ *   "id":           "job-uuid",
+ *   "task":         "Summarize this article …",
+ *   "systemPrompt": "(optional) system prompt",
+ *   "meta":         { … }   // pass-through metadata
+ * }
+ *
+ * @param {import('@nats-io/transport-node').Msg} msg
+ * @param {object} logger
+ * @returns {{ ok: true, job: object } | { ok: false, error: string }}
+ */
+import { normalizeInboundPayload } from './protocol.js';
+
+export function parseJob(msg, logger) {
+    let raw;
+    try {
+        raw = msg.string();
+    } catch (err) {
+        logger.error(`[pier-connector] Failed to read message bytes: ${err.message}`);
+        return { ok: false, error: 'Unreadable message payload' };
+    }
+
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    } catch (err) {
+        logger.error(`[pier-connector] Failed to parse JSON: ${err.message}`);
+        return { ok: false, error: `Invalid JSON: ${err.message}` };
+    }
+
+    return normalizeInboundPayload(payload);
+}
+
+/**
+ * Build a JSON response buffer to send back via msg.respond().
+ *
+ * @param {object} data
+ * @returns {Uint8Array}
+ */
+export function encodeResponse(data) {
+    return new TextEncoder().encode(JSON.stringify(data));
+}
+
+/**
+ * Safely respond to a NATS message with a JSON object.
+ *
+ * @param {import('@nats-io/transport-node').Msg} msg
+ * @param {object} data
+ */
+export function safeRespond(msg, data) {
+    try {
+        msg.respond(encodeResponse(data));
+    } catch {
+        // msg.respond may throw if connection is closed or
+        // message is not a request — silently ignore.
+    }
+}
+
+/**
+ * Truncate a string for log readability.
+ *
+ * @param {string} str
+ * @param {number} max
+ * @returns {string}
+ */
+export function truncate(str, max = 100) {
+    if (typeof str !== 'string') return String(str);
+    return str.length > max ? str.slice(0, max) + '…' : str;
+}

package/src/nats-client.js

@@ -0,0 +1,74 @@
+/**
+ * NATS WebSocket connection manager.
+ *
+ * Uses `wsconnect` from @nats-io/transport-node to establish a
+ * WebSocket connection to the NATS server.
+ */
+
+import { wsconnect } from '@nats-io/transport-node';
+
+/**
+ * Create and return a NATS connection over WebSocket.
+ *
+ * @param {string}  url    – WebSocket URL, e.g. "wss://pier.gholl.com/nexus"
+ * @param {object}  logger – OpenClaw logger (api.logger)
+ * @returns {Promise<import('@nats-io/transport-node').NatsConnection>}
+ */
+export async function createNatsConnection(url, logger) {
+    logger.info(`[pier-connector] Connecting to NATS at ${url} …`);
+
+    const nc = await wsconnect({ servers: url });
+
+    logger.info('[pier-connector] ✔ NATS connected successfully');
+
+    // ---------- lifecycle event monitoring ----------
+
+    // Fired when the client is disconnected from the server
+    (async () => {
+        for await (const status of nc.status()) {
+            switch (status.type) {
+                case 'disconnect':
+                    logger.warn(`[pier-connector] NATS disconnected: ${status.data}`);
+                    break;
+
+                case 'reconnect':
+                    logger.info(`[pier-connector] NATS reconnected to ${status.data}`);
+                    break;
+
+                case 'reconnecting':
+                    logger.warn('[pier-connector] NATS reconnecting …');
+                    break;
+
+                case 'error':
+                    logger.error(`[pier-connector] NATS error: ${status.data}`);
+                    break;
+
+                case 'update':
+                    logger.info(`[pier-connector] NATS cluster update: ${JSON.stringify(status.data)}`);
+                    break;
+
+                default:
+                    logger.info(`[pier-connector] NATS status: ${status.type}`);
+            }
+        }
+    })();
+
+    return nc;
+}
+
+/**
+ * Gracefully drain (flush pending + close) a NATS connection.
+ *
+ * @param {import('@nats-io/transport-node').NatsConnection} nc
+ * @param {object} logger
+ */
+export async function drainConnection(nc, logger) {
+    if (!nc) return;
+    try {
+        logger.info('[pier-connector] Draining NATS connection …');
+        await nc.drain();
+        logger.info('[pier-connector] ✔ NATS connection drained');
+    } catch (err) {
+        logger.error(`[pier-connector] Error draining NATS: ${err.message}`);
+    }
+}

package/src/protocol.js

@@ -0,0 +1,123 @@
+/**
+ * Protocol Definitions for Pier Connector
+ * 
+ * Standardizes outbound and inbound JSON boundaries for NATS.
+ */
+
+export const PROTOCOL_VERSION = '1.0';
+
+/**
+ * Creates a standard task request payload to send to Pier.
+ * 
+ * @param {object} params
+ * @param {string} params.task
+ * @param {string} [params.systemPrompt]
+ * @param {number} [params.timeoutMs]
+ * @param {object} [params.meta]
+ * @returns {object}
+ */
+export function createRequestPayload({ task, systemPrompt, timeoutMs, meta }) {
+    return {
+        version: PROTOCOL_VERSION,
+        id: crypto.randomUUID(),
+        type: 'task_request',
+        task,
+        systemPrompt,
+        timeoutMs: timeoutMs || 60000,
+        meta: meta || {},
+    };
+}
+
+/**
+ * Creates a standard task result payload to respond to Pier.
+ * 
+ * @param {object} params
+ * @param {string} params.id
+ * @param {string} params.reply
+ * @param {number} [params.latencyMs]
+ * @param {string} [params.workerId]
+ * @param {string} [params.walletAddress]
+ * @returns {object}
+ */
+export function createResultPayload({ id, reply, latencyMs, workerId, walletAddress }) {
+    return {
+        version: PROTOCOL_VERSION,
+        id,
+        type: 'task_result',
+        ok: true,
+        result: reply,
+        latencyMs,
+        worker: {
+            id: workerId || 'anonymous-worker',
+            wallet: walletAddress || null,
+        },
+    };
+}
+
+/**
+ * Creates a standard task error payload to respond to Pier.
+ * 
+ * @param {object} params
+ * @param {string} params.id
+ * @param {string} params.errorCode
+ * @param {string} params.errorMessage
+ * @param {string} [params.workerId]
+ * @param {string} [params.walletAddress]
+ * @returns {object}
+ */
+export function createErrorPayload({ id, errorCode, errorMessage, workerId, walletAddress }) {
+    return {
+        version: PROTOCOL_VERSION,
+        id,
+        type: 'task_error',
+        ok: false,
+        error: {
+            code: errorCode,
+            message: errorMessage,
+        },
+        worker: {
+            id: workerId || 'anonymous-worker',
+            wallet: walletAddress || null,
+        },
+    };
+}
+
+/**
+ * Validate and normalize an incoming NATS payload to a standard job format.
+ * 
+ * @param {object} payload
+ * @returns {{ ok: true, job: object } | { ok: false, error: string }}
+ */
+export function normalizeInboundPayload(payload) {
+    // If it's a strict v1.0 protocol request
+    if (payload.type === 'task_request') {
+        if (!payload.task) {
+            return { ok: false, error: 'Missing "task" field in task_request payload' };
+        }
+        return {
+            ok: true,
+            job: {
+                id: payload.id || crypto.randomUUID(),
+                task: payload.task,
+                systemPrompt: payload.systemPrompt,
+                meta: payload.meta || {},
+            },
+        };
+    }
+
+    // Fallback for legacy / generic JSON structures
+    const task = payload.task ?? payload.prompt ?? payload.content ?? '';
+    if (!task) {
+        return { ok: false, error: 'Missing "task" or "prompt" field in payload' };
+    }
+
+    return {
+        ok: true,
+        job: {
+            id: payload.id || crypto.randomUUID(),
+            task,
+            systemPrompt: payload.systemPrompt,
+            meta: payload.meta || {},
+        },
+    };
+}