@terminusagents/agents 0.1.0

package/dist/network/client.d.ts

@@ -0,0 +1,33 @@
+import { AgentConfig } from '../config/store.js';
+export declare class AgentClient {
+    private ws;
+    private config;
+    private executor;
+    private heartbeatInterval;
+    private reconnectAttempts;
+    private activeJobs;
+    private authChallenge;
+    private authenticated;
+    private manualDisconnect;
+    private connectResolve;
+    private connectReject;
+    private authAckTimeout;
+    private readonly authAckTimeoutMs;
+    constructor(config: AgentConfig);
+    connect(): Promise<void>;
+    disconnect(): void;
+    private getRuntimePrivateKey;
+    private getSystemMetrics;
+    private sendAuthFromChallenge;
+    private handleMessage;
+    private handleAuthAck;
+    private handleAgentJob;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private send;
+    private generateTraceId;
+    private resolvePendingConnect;
+    private rejectPendingConnect;
+    private clearAuthTimeout;
+}

package/dist/network/client.js

@@ -0,0 +1,389 @@
+// =============================================================================
+// TERMINUS AGENT - WebSocket Client
+// =============================================================================
+import os from 'os';
+import WebSocket from 'ws';
+import chalk from 'chalk';
+import { ethers } from 'ethers';
+import { AgentExecutor } from '../agent/executor.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function parseIncomingMessage(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed) || typeof parsed.type !== 'string')
+        return null;
+    const payload = isRecord(parsed.payload) ? parsed.payload : {};
+    switch (parsed.type) {
+        case 'AUTH_CHALLENGE':
+            if (typeof payload.challengeId !== 'string' ||
+                typeof payload.challengeMessage !== 'string' ||
+                typeof payload.expiresAt !== 'number' ||
+                typeof payload.requireWallet !== 'boolean' ||
+                typeof payload.requireNft !== 'boolean' ||
+                typeof payload.allowSharedSecret !== 'boolean') {
+                return null;
+            }
+            return parsed;
+        case 'AUTH_ACK':
+            if (typeof payload.success !== 'boolean' ||
+                (payload.message !== undefined && typeof payload.message !== 'string') ||
+                (payload.heartbeatInterval !== undefined && typeof payload.heartbeatInterval !== 'number')) {
+                return null;
+            }
+            return parsed;
+        case 'AGENT_JOB':
+            if (typeof payload.jobId !== 'string' ||
+                typeof payload.agentType !== 'string' ||
+                typeof payload.userQuery !== 'string') {
+                return null;
+            }
+            return parsed;
+        case 'HEARTBEAT_ACK':
+            return parsed;
+        case 'ERROR':
+            if (payload.message !== undefined && typeof payload.message !== 'string') {
+                return null;
+            }
+            return parsed;
+        default:
+            return null;
+    }
+}
+export class AgentClient {
+    ws = null;
+    config;
+    executor;
+    heartbeatInterval = null;
+    reconnectAttempts = 0;
+    activeJobs = 0;
+    authChallenge = null;
+    authenticated = false;
+    manualDisconnect = false;
+    connectResolve = null;
+    connectReject = null;
+    authAckTimeout = null;
+    authAckTimeoutMs = parsePositiveInt(process.env.TERMINUS_AUTH_ACK_TIMEOUT_MS, 15000);
+    constructor(config) {
+        this.config = config;
+        this.executor = new AgentExecutor(config);
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const requireWss = process.env.REQUIRE_WSS === 'true';
+            if (requireWss && !this.config.controlPlaneUrl.startsWith('wss://')) {
+                reject(new Error('REQUIRE_WSS=true but control plane URL is not wss://'));
+                return;
+            }
+            if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
+                if (this.authenticated) {
+                    resolve();
+                    return;
+                }
+                reject(new Error('Connection is already in progress'));
+                return;
+            }
+            this.connectResolve = resolve;
+            this.connectReject = reject;
+            this.authenticated = false;
+            this.manualDisconnect = false;
+            this.clearAuthTimeout();
+            console.log(chalk.gray(`🔌 Connecting to ${this.config.controlPlaneUrl}...`));
+            this.ws = new WebSocket(this.config.controlPlaneUrl);
+            this.ws.on('open', () => {
+                console.log(chalk.green('✅ Connected! Waiting AUTH_CHALLENGE...'));
+                this.reconnectAttempts = 0;
+                this.authAckTimeout = setTimeout(() => {
+                    if (!this.authenticated) {
+                        this.rejectPendingConnect(new Error('Authentication timeout waiting for AUTH_ACK'));
+                        this.disconnect();
+                    }
+                }, this.authAckTimeoutMs);
+            });
+            this.ws.on('message', (data) => {
+                this.handleMessage(data.toString());
+            });
+            this.ws.on('close', () => {
+                console.log(chalk.yellow('❌ Disconnected from Control Plane'));
+                this.stopHeartbeat();
+                this.authChallenge = null;
+                this.clearAuthTimeout();
+                const wasAuthenticated = this.authenticated;
+                this.authenticated = false;
+                this.ws = null;
+                if (!wasAuthenticated) {
+                    this.rejectPendingConnect(new Error('Connection closed before authentication completed'));
+                }
+                if (!this.manualDisconnect) {
+                    this.scheduleReconnect();
+                }
+            });
+            this.ws.on('error', (err) => {
+                console.log(chalk.red(`Socket error: ${err.message}`));
+                if (!this.authenticated) {
+                    this.rejectPendingConnect(new Error(`Socket error: ${err.message}`));
+                }
+            });
+        });
+    }
+    disconnect() {
+        this.manualDisconnect = true;
+        this.stopHeartbeat();
+        this.clearAuthTimeout();
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    getRuntimePrivateKey() {
+        const envPk = process.env.TERMINUS_WALLET_PRIVATE_KEY?.trim();
+        if (envPk)
+            return envPk;
+        return this.config.privateKey;
+    }
+    getSystemMetrics() {
+        const cpuCount = Math.max(os.cpus().length, 1);
+        const load = os.loadavg()[0];
+        const cpuUsage = Math.max(0, Math.min(100, Math.round((load / cpuCount) * 100)));
+        const totalMemory = os.totalmem();
+        const usedMemory = totalMemory - os.freemem();
+        const memoryUsage = Math.max(0, Math.min(100, Math.round((usedMemory / totalMemory) * 100)));
+        return { cpuUsage, memoryUsage };
+    }
+    async sendAuthFromChallenge(challenge) {
+        const privateKey = this.getRuntimePrivateKey();
+        let challengeSignature;
+        let wallet = this.config.wallet;
+        if (privateKey) {
+            try {
+                const normalizedPk = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
+                const signer = new ethers.Wallet(normalizedPk);
+                wallet = signer.address;
+                challengeSignature = await signer.signMessage(challenge.challengeMessage);
+                console.log(chalk.green('🔐 Challenge signature created'));
+                if (wallet.toLowerCase() !== this.config.wallet.toLowerCase()) {
+                    if (process.env.ALLOW_WALLET_MISMATCH === 'true') {
+                        console.log(chalk.yellow(`⚠ Config wallet ${this.config.wallet} differs from signer wallet ${wallet}; signer wallet will be used.`));
+                    }
+                    else {
+                        console.log(chalk.red('❌ Config wallet does not match TERMINUS_WALLET_PRIVATE_KEY signer wallet.'));
+                        console.log(chalk.gray('   Fix by running `npx terminus-agent init` with the signer wallet.'));
+                        this.rejectPendingConnect(new Error('Wallet mismatch between config and private key'));
+                        this.disconnect();
+                        return;
+                    }
+                }
+            }
+            catch (err) {
+                console.log(chalk.red(`❌ Failed to sign challenge: ${err.message}`));
+            }
+        }
+        const devSecret = process.env.NODE_SECRET?.trim();
+        const allowDevSharedSecret = process.env.ALLOW_DEV_SHARED_SECRET === 'true';
+        const canUseDevSecret = allowDevSharedSecret && challenge.allowSharedSecret && Boolean(devSecret);
+        const secret = challengeSignature ? undefined : (canUseDevSecret ? devSecret : undefined);
+        if (challenge.requireWallet && !wallet) {
+            console.log(chalk.red('❌ Wallet is required by control plane but not configured.'));
+            this.rejectPendingConnect(new Error('Wallet is required by control plane but not configured'));
+            this.disconnect();
+            return;
+        }
+        if (challenge.requireWallet && !challengeSignature && !secret) {
+            console.log(chalk.red('❌ Missing TERMINUS_WALLET_PRIVATE_KEY for challenge-signature auth.'));
+            this.rejectPendingConnect(new Error('Missing challenge signature and shared-secret fallback'));
+            this.disconnect();
+            return;
+        }
+        const totalMemoryGB = Math.round((os.totalmem() / 1024 / 1024 / 1024) * 100) / 100;
+        const message = {
+            type: 'AUTH',
+            traceId: this.generateTraceId(),
+            timestamp: Date.now(),
+            payload: {
+                nodeId: this.config.nodeId,
+                capabilities: ['agent-execution', 'llm-inference'],
+                agentTypes: [this.config.agentType],
+                wallet,
+                challengeId: challenge.challengeId,
+                challengeMessage: challenge.challengeMessage,
+                challengeSignature,
+                specs: {
+                    os: process.platform,
+                    arch: process.arch,
+                    cpuCores: os.cpus().length,
+                    totalMemoryGB,
+                    nodeVersion: process.version,
+                },
+                secret,
+                version: '0.2.0',
+            },
+        };
+        this.send(message);
+    }
+    handleMessage(raw) {
+        const message = parseIncomingMessage(raw);
+        if (!message) {
+            console.log(chalk.red('Failed to parse or validate incoming message'));
+            return;
+        }
+        switch (message.type) {
+            case 'AUTH_CHALLENGE':
+                this.authChallenge = message.payload;
+                if (Date.now() > message.payload.expiresAt) {
+                    console.log(chalk.red('❌ Received expired AUTH_CHALLENGE'));
+                    this.rejectPendingConnect(new Error('Received expired AUTH_CHALLENGE'));
+                    this.disconnect();
+                    return;
+                }
+                void this.sendAuthFromChallenge(message.payload);
+                break;
+            case 'AUTH_ACK':
+                this.handleAuthAck(message);
+                break;
+            case 'HEARTBEAT_ACK':
+                break;
+            case 'AGENT_JOB':
+                void this.handleAgentJob(message);
+                break;
+            case 'ERROR':
+                console.log(chalk.red(`❌ Error: ${message.payload.message || 'Unknown error'}`));
+                break;
+        }
+    }
+    handleAuthAck(message) {
+        if (message.payload.success) {
+            this.authenticated = true;
+            this.clearAuthTimeout();
+            this.resolvePendingConnect();
+            console.log(chalk.green(`🎉 Authenticated as ${this.config.nodeId}`));
+            this.startHeartbeat(message.payload.heartbeatInterval || 5000);
+            return;
+        }
+        console.log(chalk.red(`❌ Auth failed: ${message.payload.message || 'Unknown reason'}`));
+        this.rejectPendingConnect(new Error(message.payload.message || 'Authentication failed'));
+        this.disconnect();
+    }
+    async handleAgentJob(message) {
+        const { jobId, userQuery } = message.payload;
+        console.log(chalk.cyan(`📥 Job ${jobId} received (${message.payload.agentType})`));
+        this.activeJobs++;
+        try {
+            const startTime = Date.now();
+            const result = await this.executor.execute(userQuery);
+            const durationMs = Date.now() - startTime;
+            console.log(chalk.green(`✅ Job ${jobId} complete (${durationMs}ms)`));
+            this.send({
+                type: 'AGENT_JOB_RESULT',
+                traceId: message.traceId,
+                timestamp: Date.now(),
+                payload: {
+                    jobId,
+                    success: true,
+                    response: result.response,
+                    toolsUsed: result.toolsUsed,
+                    metrics: {
+                        executionTimeMs: durationMs,
+                    },
+                },
+            });
+        }
+        catch (err) {
+            const error = err;
+            console.log(chalk.red(`❌ Job ${jobId} failed: ${error.message}`));
+            this.send({
+                type: 'AGENT_JOB_RESULT',
+                traceId: message.traceId,
+                timestamp: Date.now(),
+                payload: {
+                    jobId,
+                    success: false,
+                    response: '',
+                    error: {
+                        code: 'EXECUTION_ERROR',
+                        message: error.message,
+                    },
+                },
+            });
+        }
+        finally {
+            this.activeJobs--;
+        }
+    }
+    startHeartbeat(intervalMs) {
+        console.log(chalk.gray(`⏱️ Starting heartbeat every ${intervalMs}ms`));
+        this.heartbeatInterval = setInterval(() => {
+            const status = this.activeJobs > 0 ? 'BUSY' : 'IDLE';
+            const metrics = this.getSystemMetrics();
+            const message = {
+                type: 'HEARTBEAT',
+                traceId: this.generateTraceId(),
+                timestamp: Date.now(),
+                payload: {
+                    status,
+                    cpuUsage: metrics.cpuUsage,
+                    memoryUsage: metrics.memoryUsage,
+                    activeJobs: this.activeJobs,
+                },
+            };
+            this.send(message);
+        }, intervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+    }
+    scheduleReconnect() {
+        this.reconnectAttempts++;
+        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 30000);
+        console.log(chalk.gray(`🔄 Reconnecting in ${delay / 1000}s (attempt ${this.reconnectAttempts})...`));
+        setTimeout(() => {
+            void this.connect().catch(() => {
+                // A failed reconnect will trigger close/error flow and next retry.
+            });
+        }, delay);
+    }
+    send(message) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(message));
+        }
+    }
+    generateTraceId() {
+        return `trace-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+    resolvePendingConnect() {
+        if (!this.connectResolve)
+            return;
+        const resolve = this.connectResolve;
+        this.connectResolve = null;
+        this.connectReject = null;
+        resolve();
+    }
+    rejectPendingConnect(error) {
+        if (!this.connectReject)
+            return;
+        const reject = this.connectReject;
+        this.connectResolve = null;
+        this.connectReject = null;
+        reject(error);
+    }
+    clearAuthTimeout() {
+        if (!this.authAckTimeout)
+            return;
+        clearTimeout(this.authAckTimeout);
+        this.authAckTimeout = null;
+    }
+}
+function parsePositiveInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+    "name": "@terminusagents/agents",
+    "version": "0.1.0",
+    "description": "Standalone agent runner for Terminus network",
+    "type": "module",
+    "main": "dist/index.js",
+    "files": [
+        "bin",
+        "dist",
+        "README.md"
+    ],
+    "bin": {
+        "terminus-agent": "bin/terminus-agent.js"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "clean": "rm -rf dist",
+        "build": "tsc",
+        "prepare": "npm run build",
+        "prepack": "npm run build",
+        "dev": "tsx src/index.ts",
+        "start": "node dist/index.js"
+    },
+    "dependencies": {
+        "chalk": "^5.3.0",
+        "commander": "^12.1.0",
+        "dotenv": "^16.4.5",
+        "ethers": "^6.16.0",
+        "inquirer": "^9.2.23",
+        "ws": "^8.18.0"
+    },
+    "devDependencies": {
+        "@types/inquirer": "^9.0.7",
+        "@types/node": "^20.11.0",
+        "@types/ws": "^8.5.10",
+        "tsx": "^4.7.0",
+        "typescript": "^5.4.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "keywords": [
+        "terminus",
+        "agent",
+        "ai",
+        "distributed",
+        "x402",
+        "operator-node",
+        "terminus-agents"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Terminusagents/agents.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Terminusagents/agents/issues"
+    },
+    "homepage": "https://github.com/Terminusagents/agents",
+    "author": "Terminusagents <terminusai@gmail.com>",
+    "license": "MIT"
+}