@gholl-studio/pier-connector 0.2.52 → 0.3.1

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@gholl-studio/pier-connector",
     "author": "gholl",
-    "version": "0.2.52",
+    "version": "0.3.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",
+    "main": "src/index.ts",
     "engines": {
         "node": ">=22"
     },
@@ -15,14 +15,20 @@
     ],
     "openclaw": {
         "extensions": [
-            "src/index.js"
-        ]
+            "./src/index.ts"
+        ],
+        "setupEntry": "./src/cli.ts",
+        "channel": {
+            "id": "pier",
+            "label": "Pier",
+            "blurb": "Connect OpenClaw to the Pier job marketplace."
+        }
     },
     "scripts": {
-        "dev": "vite",
-        "build": "tsc -b && vite build",
+        "build": "tsc",
+        "watch": "tsc -w",
+        "prepublishOnly": "npm run build",
         "lint": "eslint .",
-        "preview": "vite preview",
         "test:watch": "node --watch test-standalone.js"
     },
     "keywords": [
@@ -50,8 +56,9 @@
         }
     },
     "devDependencies": {
+        "@types/node": "^25.5.0",
         "dotenv": "^17.3.1",
         "openclaw": ">=2.0.0",
-        "typescript": "^5.0.0"
+        "typescript": "^5.9.3"
     }
-}
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+import fs from 'fs';
+import path from 'path';
+import type { PierPluginApi } from './types.js';
+
+export function registerCli(api: PierPluginApi, stats: any) {
+    const logger = api.logger;
+    api.registerCli(
+        ({ program }) => {
+            program
+                .command('pier')
+                .description('Check Pier connection status')
+                .action(() => {
+                    console.log('\n\x1b[1m\x1b[35m🦞 Pier Connector Status\x1b[0m\n');
+                    console.log(`Total Jobs Received:  \x1b[36m${stats.received}\x1b[0m`);
+                    console.log(`Total Jobs Completed: \x1b[32m${stats.completed}\x1b[0m`);
+                    console.log(`Total Jobs Failed:    \x1b[31m${stats.failed}\x1b[0m\n`);
+                });
+
+            program
+                .command('pier-configure')
+                .description('Interactively configure Pier Node')
+                .action(async () => {
+                    // Logic for interactive configuration
+                    // (Omitted for brevity, but can be extracted from index.js)
+                });
+        },
+        { descriptors: [{ name: 'pier', description: 'Pier status', hasSubcommands: false }] }
+    );
+}

package/src/config.ts

@@ -0,0 +1,29 @@
+/**
+ * Default configuration constants for pier-connector.
+ */
+
+export interface PierDefaults {
+    PIER_API_URL: string;
+    NATS_URL: string;
+    SUBJECT: string;
+    PUBLISH_SUBJECT: string;
+    QUEUE_GROUP: string;
+    NODE_ID: string;
+    SECRET_KEY: string;
+    PRIVATE_KEY: string;
+    WALLET_ADDRESS: string;
+    AGENT_ID: string;
+}
+
+export const DEFAULTS: PierDefaults = Object.freeze({
+    PIER_API_URL: 'https://pier-connector.gholl.com/api/v1',
+    NATS_URL: 'wss://pier.gholl.com/nexus',
+    SUBJECT: 'jobs.worker',
+    PUBLISH_SUBJECT: 'jobs.submit',
+    QUEUE_GROUP: 'openclaw-workers',
+    NODE_ID: '',
+    SECRET_KEY: '',
+    PRIVATE_KEY: '',
+    WALLET_ADDRESS: '',
+    AGENT_ID: '',
+});

package/src/inbound.ts

@@ -0,0 +1,162 @@
+import type { PierPluginApi, InboundMessage } from './types.js';
+import { truncate } from './job-handler.js';
+
+export async function handleInbound(
+    api: PierPluginApi,
+    inbound: InboundMessage,
+    jobId: string,
+    robot: any, // Avoiding circular dependency with type PierRobot
+    pierChannel: any
+) {
+    const logger = api.logger;
+    if (!api.runtime?.channel?.reply) {
+        logger.error(`[pier-connector][${robot.accountId}] SDK Error: api.runtime.channel.reply is not available.`);
+        return;
+    }
+
+    // 1. Resolve Global Configuration
+    const rootConfig = api.config || {};
+    
+    // 2. Resolve Agent Route via SDK
+    const route = api.runtime.channel.routing.resolveAgentRoute({
+        cfg: rootConfig,
+        channel: 'pier',
+        accountId: inbound.accountId,
+        peer: { kind: 'direct', id: jobId }
+    });
+
+    // 3. Robust Routing Decision Tree
+    let finalAgentId = null;
+    let routingSource = 'unresolved';
+
+    // A. Check explicit account-level binding in plugin local config
+    if (robot.config.agentId && robot.config.agentId !== 'main' && robot.config.agentId !== 'default') {
+        finalAgentId = robot.config.agentId;
+        routingSource = 'plugin-local-config';
+    }
+
+    // B. Check Global Bindings
+    if (!finalAgentId) {
+        const bindings = Array.isArray(rootConfig.bindings) ? rootConfig.bindings : [];
+        const binding = bindings.find((bi: any) => 
+            bi.match?.channel === 'pier' && 
+            (bi.match?.accountId === inbound.accountId || bi.match?.account === inbound.accountId)
+        );
+        if (binding?.agentId && binding.agentId !== 'main') {
+            finalAgentId = binding.agentId;
+            routingSource = 'manual-global-bindings-match';
+        }
+    }
+
+    // C. SDK Routing Result
+    if (!finalAgentId && route.agentId && route.agentId !== 'main' && route.agentId !== 'default') {
+        finalAgentId = route.agentId;
+        routingSource = 'sdk-global-bindings';
+    }
+
+    // D. Name-Matching Fallback
+    if (!finalAgentId && inbound.accountId && inbound.accountId !== 'default' && inbound.accountId !== 'main') {
+        const agents = (rootConfig as any).agents?.list || {};
+        const agentExists = Array.isArray(agents) ? agents.some((a: any) => a.id === inbound.accountId) : !!agents[inbound.accountId];
+        
+        if (agentExists) {
+            finalAgentId = inbound.accountId;
+            routingSource = 'account-agent-name-match';
+        }
+    }
+
+    // E. Ultimate Fallback
+    if (!finalAgentId) {
+        finalAgentId = route.agentId || 'main';
+        routingSource = route.agentId ? 'sdk-default-fallback' : 'hardcoded-main-fallback';
+    }
+
+    logger.info(`[pier-connector] Routing account '${inbound.accountId}' -> agent '${finalAgentId}' (Source: ${routingSource})`);
+
+    const dynamicSessionKey = `pier-job-${jobId}`;
+    const metadata = robot.activeNodeJobs.get(jobId);
+    let injectedPrompt = "";
+
+    if (metadata && metadata.isTargeted === false) {
+        injectedPrompt = [
+            "=========================================",
+            "CRITICAL DIRECTIVE - OPEN BIDDING MARKETPLACE",
+            "=========================================",
+            "You are an autonomous AI worker on Pier. This job currently has NO assigned worker.",
+            "1. DO NOT directly solve the user's task or output the final answer right now.",
+            "2. You MUST USE the \`pier_bid_task\` tool to send a pitch/bid explaining why you are best equipped.",
+            "3. Stop executing after submitting the bid.",
+            "4. You MUST use the Job ID provided below when calling the tool.",
+            `Job ID: ${jobId}`
+        ].join('\n');
+    } else {
+        injectedPrompt = [
+            "=========================================",
+            "CRITICAL DIRECTIVE - PIER TRADING NETWORK",
+            "=========================================",
+            "You are an autonomous AI worker on Pier.",
+            "1. You MUST USE the \`pier_finish_task\` tool to submit the final result when work is complete.",
+            "2. If you need to negotiate or clarify requirements, use \`pier_chat\`.",
+            "3. Do not just wait in silence. Always officially finish the task if the goal is met."
+        ].join('\n');
+    }
+
+    const ctxPayload = api.runtime.channel.reply.finalizeInboundContext({
+        AgentId: finalAgentId,
+        Body: inbound.body,
+        BodyForAgent: inbound.body,
+        RawBody: inbound.body,
+        From: inbound.senderId,
+        To: `pier:${jobId}`,
+        SessionKey: dynamicSessionKey,
+        AccountId: inbound.accountId, 
+        ChatType: 'direct',
+        SenderId: inbound.senderId,
+        Provider: 'pier',
+        Surface: 'pier',
+        OriginatingChannel: 'pier',
+        OriginatingTo: `pier:${jobId}`,
+        WasMentioned: true,
+        CommandAuthorized: true,
+        SystemPrompt: injectedPrompt,
+        MessageId: jobId,
+        Metadata: { 
+            ...metadata,
+            accountId: robot.accountId,
+            pierJobId: jobId,
+            routingSource: routingSource
+        }
+    });
+
+    const { dispatcher, markDispatchIdle } = api.runtime.channel.reply.createReplyDispatcherWithTyping({
+        deliver: async (payload: any) => {
+            const currentMeta = robot.activeNodeJobs.get(jobId);
+            await pierChannel.outbound.sendText({
+                text: payload.text,
+                to: `pier:${jobId}`,
+                metadata: { 
+                    ...currentMeta, 
+                    accountId: robot.accountId,
+                    pierJobId: jobId 
+                },
+            });
+        }
+    });
+
+    if (api.runtime.channel.session?.recordSessionMetaFromInbound) {
+        try {
+            const storePath = api.runtime.channel.session.resolveStorePath(dynamicSessionKey);
+            await api.runtime.channel.session.recordSessionMetaFromInbound({
+                storePath, sessionKey: dynamicSessionKey, ctx: ctxPayload
+            });
+        } catch (err) {}
+    }
+
+    try {
+        await api.runtime.channel.reply.dispatchReplyFromConfig({
+            ctx: ctxPayload, cfg: api.config, dispatcher
+        });
+    } finally {
+        markDispatchIdle();
+    }
+}

package/src/index.ts

@@ -0,0 +1,297 @@
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { protocol } from '@gholl-studio/pier-sdk';
+const { createRequestPayload } = protocol;
+import { DEFAULTS } from './config.js';
+import { PierRobot } from './robot.js';
+import { handleInbound } from './inbound.js';
+import { registerCli } from './cli.js';
+import type { PierAccountConfig, PierPluginApi } from './types.js';
+
+const register = (api: PierPluginApi) => {
+    const logger = api.logger;
+    const instances = new Map<string, PierRobot>();
+    const globalStats = { received: 0, completed: 0, failed: 0 };
+
+    function mergedCfgFrom(legacy: any, account: any): PierAccountConfig {
+        const merged = { ...legacy, ...account };
+        return {
+            accountId: account.accountId || 'default',
+            pierApiUrl: merged.pierApiUrl || DEFAULTS.PIER_API_URL,
+            nodeId: merged.nodeId || DEFAULTS.NODE_ID,
+            secretKey: merged.secretKey || DEFAULTS.SECRET_KEY,
+            privateKey: merged.privateKey || process.env.PIER_PRIVATE_KEY || DEFAULTS.PRIVATE_KEY,
+            natsUrl: merged.natsUrl || DEFAULTS.NATS_URL,
+            subject: merged.subject || DEFAULTS.SUBJECT,
+            publishSubject: merged.publishSubject || DEFAULTS.PUBLISH_SUBJECT,
+            queueGroup: merged.queueGroup || DEFAULTS.QUEUE_GROUP,
+            agentId: merged.agentId || DEFAULTS.AGENT_ID,
+            walletAddress: merged.walletAddress || DEFAULTS.WALLET_ADDRESS,
+            capabilities: merged.capabilities || ['translation', 'code-execution', 'reasoning', 'vision'],
+        };
+    }
+
+    function resolveConfigs(): PierAccountConfig[] {
+        const globalAccounts = (api.config as any)?.channels?.['pier']?.accounts || {};
+        const pluginAccounts = (api.pluginConfig as any)?.accounts || {};
+        const rawAccounts = { ...globalAccounts, ...pluginAccounts };
+        const legacyCfg = api.pluginConfig || {};
+
+        if (Object.keys(rawAccounts).length === 0) {
+            return [mergedCfgFrom(legacyCfg, { accountId: 'default' })];
+        }
+
+        return Object.entries(rawAccounts).map(([id, account]: [string, any]) => 
+            mergedCfgFrom(legacyCfg, { ...account, accountId: id })
+        );
+    }
+
+    const pierChannel = {
+        id: 'pier',
+        meta: {
+            id: 'pier',
+            label: 'Pier',
+            selectionLabel: 'Pier (NATS Job Marketplace)',
+            blurb: 'Connect to the Pier distributed job marketplace.'
+        },
+        outbound: {
+            sendText: async (params: any) => {
+                const robot = instances.get(params.metadata?.accountId || 'default') || instances.values().next().value;
+                if (!robot || !robot.js) return;
+                
+                const jobId = params.metadata?.pierJobId || params.to.replace(/^pier:/, '');
+                const subject = `chat.${jobId}`;
+                
+                const payload = {
+                    id: crypto.randomUUID ? crypto.randomUUID() : (Math.random().toString(36).substring(2)),
+                    job_id: jobId,
+                    sender_id: robot.config.nodeId,
+                    sender_name: robot.accountId,
+                    sender_type: 'node',
+                    content: params.text,
+                    created_at: new Date().toISOString(),
+                    auth_token: robot.config.secretKey
+                };
+
+                await robot.js.publish(subject, new TextEncoder().encode(JSON.stringify(payload)));
+            }
+        }
+    };
+
+    api.registerChannel(pierChannel as any);
+
+    api.registerService({
+        id: 'pier-connector',
+        start: async () => {
+            const configs = resolveConfigs();
+            for (const config of configs) {
+                const robot = new PierRobot(config, api, async (inbound, jobId) => {
+                    await handleInbound(api, inbound, jobId, robot, pierChannel);
+                    globalStats.received++;
+                });
+                instances.set(config.accountId, robot);
+                await robot.start();
+            }
+        },
+        stop: async () => {
+            for (const robot of instances.values()) {
+                await robot.stop();
+            }
+            instances.clear();
+        }
+    });
+
+    api.registerTool({
+        name: 'pier_publish',
+        label: 'Publish to Pier',
+        description: 'Publish a task to the Pier job marketplace.',
+        parameters: {
+            type: 'object',
+            properties: {
+                task: { type: 'string' },
+                accountId: { type: 'string' }
+            },
+            required: ['task']
+        },
+        async execute(_id, params) {
+            const robot = instances.get(params.accountId || 'default') || instances.values().next().value;
+            if (!robot || robot.connectionStatus !== 'connected') {
+                return { 
+                    content: [{ type: 'text', text: 'Robot not connected' }],
+                    details: {}
+                };
+            }
+            
+            const taskPayload = createRequestPayload({ task: params.task });
+            const reply = await robot.nc!.request(robot.config.publishSubject, new TextEncoder().encode(JSON.stringify(taskPayload)));
+            return { 
+                content: [{ type: 'text', text: new TextDecoder().decode(reply.data) }],
+                details: {}
+            };
+        }
+    }, { optional: true });
+
+    api.registerTool(
+        {
+            name: 'pier_chat',
+            label: 'Pier Chat',
+            description: 'Send a message to the employer regarding a specific job.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    jobId: { type: 'string' },
+                    text: { type: 'string' },
+                    accountId: { type: 'string' }
+                },
+                required: ['jobId', 'text']
+            },
+            async execute(_id, params, ctx: any) {
+                const accountId = params.accountId || 'default';
+                const robot = instances.get(accountId) || instances.values().next().value;
+                if (!robot || robot.connectionStatus !== 'connected') {
+                    return { content: [{ type: 'text', text: 'Error: Robot not connected' }], details: {} };
+                }
+
+                try {
+                    const subject = `chat.${params.jobId}`;
+                    let metadata = robot.activeNodeJobs.get(params.jobId);
+                    
+                    if (!metadata && ctx.to) {
+                        const toId = ctx.to.replace(/^pier:/, '');
+                        metadata = robot.activeNodeJobs.get(toId);
+                    }
+                    
+                    const jobId = metadata?.pierJobId || params.jobId;
+
+                    if (!robot.js) {
+                        return { content: [{ type: 'text', text: 'Error: JetStream not available' }], details: {} };
+                    }
+
+                    const payload = {
+                        id: (globalThis.crypto as any).randomUUID ? (globalThis.crypto as any).randomUUID() : (Math.random().toString(36).substring(2)),
+                        job_id: jobId,
+                        sender_id: robot.config.nodeId,
+                        sender_name: accountId,
+                        sender_type: 'node',
+                        content: params.text,
+                        created_at: new Date().toISOString(),
+                        auth_token: robot.config.secretKey
+                    };
+
+                    await robot.js.publish(subject, new TextEncoder().encode(JSON.stringify(payload)));
+                    return { content: [{ type: 'text', text: 'Message sent' }], details: {} };
+                } catch (err: any) {
+                    return { content: [{ type: 'text', text: `Error: ${err.message}` }], details: {} };
+                }
+            }
+        },
+        { optional: true }
+    );
+
+    const registerSystemActionTool = (name: string, label: string, description: string, action: string, extraParams: any, userRole = 'node') => {
+        api.registerTool({
+            name,
+            label,
+            description,
+            parameters: {
+                type: 'object',
+                properties: {
+                    jobId: { type: 'string', description: 'The ID of the job' },
+                    accountId: { type: 'string' },
+                    ...extraParams
+                },
+                required: ['jobId', ...Object.keys(extraParams)]
+            },
+            async execute(_id, params) {
+                const accountId = params.accountId || 'default';
+                const robot = instances.get(accountId) || instances.values().next().value;
+                if (!robot || robot.connectionStatus !== 'connected') {
+                    return { content: [{ type: 'text', text: 'Error: Robot not connected' }], details: {} };
+                }
+
+                try {
+                    const subject = `chat.${params.jobId}`;
+                    const { jobId: j, accountId: _, ...p } = params;
+
+                    if (!robot.js) {
+                        return { content: [{ type: 'text', text: 'Error: JetStream not available' }], details: {} };
+                    }
+
+                    const msgData = {
+                        id: (globalThis.crypto as any).randomUUID ? (globalThis.crypto as any).randomUUID() : (Math.random().toString(36).substring(2)),
+                        job_id: params.jobId,
+                        sender_id: userRole === 'user' ? 'user_' + robot.config.nodeId : robot.config.nodeId, 
+                        sender_type: userRole,
+                        content: JSON.stringify({ type: 'system_action', action, payload: p }),
+                        created_at: new Date().toISOString(),
+                        auth_token: robot.config.secretKey,
+                        type: 'system_action',
+                        action: action
+                    };
+
+                    await robot.js.publish(subject, new TextEncoder().encode(JSON.stringify(msgData)));
+                    return { content: [{ type: 'text', text: `${action} executed successfully` }], details: {} };
+                } catch (err: any) {
+                    return { content: [{ type: 'text', text: `Error: ${err.message}` }], details: {} };
+                }
+            }
+        }, { optional: true });
+    };
+
+    registerSystemActionTool('pier_bid_task', 'Bid on task', 'Bid on an marketplace task', 'task_bid', { message: { type: 'string', description: 'Your pitch' } });
+    registerSystemActionTool('pier_accept_task', 'Accept task', 'Accept offered task', 'task_accept', {});
+    registerSystemActionTool('pier_finish_task', 'Finish task', 'Submit final result', 'task_submit', { result: { type: 'string', description: 'Final result' } });
+    registerSystemActionTool('pier_propose_task', 'Offer task', 'Offer task to a node', 'task_offer', {
+        price: { type: 'number' },
+        description: { type: 'string' }
+    }, 'user');
+    registerSystemActionTool('pier_rate_task', 'Rate task', 'Rate the node', 'task_rate', {
+        score: { type: 'number' },
+        comment: { type: 'string' }
+    }, 'user');
+    registerSystemActionTool('pier_reject_task', 'Reject task', 'Reject task', 'task_reject', { reason: { type: 'string' } });
+    registerSystemActionTool('pier_fail_task', 'Report error', 'Report that the task has failed', 'task_error', { error: { type: 'string' } });
+    registerSystemActionTool('pier_cancel_task', 'Cancel task', 'Cancel the task', 'task_cancel', { reason: { type: 'string' } }, 'user');
+
+    api.registerTool({
+        name: 'pier_get_profile',
+        label: 'Pier Profile',
+        description: 'Get current Pier profile and node stats.',
+        parameters: {
+            type: 'object',
+            properties: { accountId: { type: 'string' } }
+        },
+        async execute(_id, params) {
+            const robot = instances.get(params.accountId || 'default') || instances.values().next().value;
+            if (!robot) return { content: [{ type: 'text', text: 'Error: Robot not found' }], details: {} };
+            try {
+                const profile = await robot.client.getUserProfile(robot.config.secretKey);
+                return { content: [{ type: 'text', text: JSON.stringify(profile, null, 2) }], details: {} };
+            } catch (err: any) {
+                return { content: [{ type: 'text', text: `Error: ${err.message}` }], details: {} };
+            }
+        }
+    }, { optional: true });
+
+    // Register simple status command
+    api.registerCommand({
+        name: 'pier',
+        description: 'Show Pier status',
+        handler: () => {
+            const lines = ['**Pier Connector Status**'];
+            instances.forEach((r, id) => {
+                lines.push(`\n**Account: ${id}**\n• Status: ${r.connectionStatus}\n• Jobs: ${r.stats.received}/${r.stats.completed}/${r.stats.failed}`);
+            });
+            return { text: lines.join('\n') };
+        }
+    });
+
+    registerCli(api, globalStats);
+    logger.info('[pier-connector] Plugin registered');
+};
+
+export default definePluginEntry({
+    id: 'pier-connector',
+    name: 'Pier Connector',
+    description: 'Connects OpenClaw to the Pier job marketplace.',
+    register
+});

package/src/job-handler.ts

@@ -0,0 +1,51 @@
+import { protocol } from '@gholl-studio/pier-sdk';
+const { normalizeInboundPayload } = protocol;
+
+/**
+ * Parse a raw NATS message into a structured job object.
+ */
+export function parseJob(msg: any, logger?: any) {
+    let raw: string;
+    try {
+        raw = msg.string();
+    } catch (err: any) {
+        if (logger) logger.error(`[pier-connector] Failed to read message bytes: ${err.message}`);
+        return { ok: false, error: 'Unreadable message payload' };
+    }
+
+    let payload: any;
+    try {
+        payload = JSON.parse(raw);
+    } catch (err: any) {
+        if (logger) 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().
+ */
+export function encodeResponse(data: any): Uint8Array {
+    return new TextEncoder().encode(JSON.stringify(data));
+}
+
+/**
+ * Safely respond to a NATS message with a JSON object.
+ */
+export function safeRespond(msg: any, data: any) {
+    try {
+        msg.respond(encodeResponse(data));
+    } catch {
+        // Silently ignore
+    }
+}
+
+/**
+ * Truncate a string for log readability.
+ */
+export function truncate(str: string, max: number = 100): string {
+    if (typeof str !== 'string') return String(str);
+    return str.length > max ? str.slice(0, max) + '…' : str;
+}