@elizaos/plugin-ngrok 2.0.0-beta.1

package/dist/services/NgrokService.js

@@ -0,0 +1,333 @@
+import { elizaLogger, Service } from '@elizaos/core';
+/** Coerce runtime.getSetting() (string | number | boolean | null) to string. */
+function settingString(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    return String(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+import { spawn } from 'node:child_process';
+import * as http from 'node:http';
+import { validateNgrokConfig } from '../environment';
+export class NgrokService extends Service {
+    static serviceType = 'tunnel';
+    capabilityDescription = 'Provides secure tunnel functionality using ngrok for exposing local services to the internet';
+    static MIN_TUNNEL_INTERVAL = 2000; // 2 seconds minimum between tunnel starts
+    ngrokProcess = null;
+    tunnelUrl = null;
+    tunnelPort = null;
+    startedAt = null;
+    lastStartTime = 0;
+    tunnelConfig;
+    constructor(runtime) {
+        super(runtime);
+        this.tunnelConfig = {
+            provider: 'ngrok',
+            authToken: settingString(runtime?.getSetting('NGROK_AUTH_TOKEN')) ?? process.env.NGROK_AUTH_TOKEN,
+        };
+    }
+    async initialize() {
+        elizaLogger.info('🚇 Initializing Ngrok tunnel service...');
+        const isInstalled = await this.checkNgrokInstalled();
+        if (!isInstalled) {
+            throw new Error('ngrok is not installed. Please install it from https://ngrok.com/download or run: brew install ngrok');
+        }
+        const authToken = this.tunnelConfig.authToken ??
+            settingString(this.runtime.getSetting('NGROK_AUTH_TOKEN')) ??
+            process.env.NGROK_AUTH_TOKEN;
+        if (authToken) {
+            await this.setAuthToken(authToken);
+            elizaLogger.info('Setting ngrok auth token');
+        }
+        else {
+            elizaLogger.warn('No ngrok auth token found - running in limited mode');
+        }
+    }
+    static async start(runtime) {
+        const service = new NgrokService(runtime);
+        await service.start();
+        return service;
+    }
+    // Base Service lifecycle methods
+    async start() {
+        elizaLogger.info('NgrokService started');
+    }
+    async stop() {
+        await this.stopTunnel();
+    }
+    // ITunnelService implementation
+    async startTunnel(port) {
+        if (this.isActive()) {
+            elizaLogger.warn('Ngrok tunnel is already running');
+            return this.tunnelUrl || undefined;
+        }
+        if (!port) {
+            elizaLogger.warn('NgrokService.start() called without a port. The service will be active but no tunnel will be started.');
+            return;
+        }
+        // Validate environment
+        try {
+            await validateNgrokConfig(this.runtime);
+        }
+        catch (error) {
+            throw new Error(`Ngrok environment validation failed: ${errorMessage(error)}`);
+        }
+        // Enforce rate limiting
+        const now = Date.now();
+        if (this.lastStartTime && now - this.lastStartTime < NgrokService.MIN_TUNNEL_INTERVAL) {
+            const waitTime = NgrokService.MIN_TUNNEL_INTERVAL - (now - this.lastStartTime);
+            elizaLogger.warn(`Rate limiting: waiting ${waitTime}ms before starting tunnel`);
+            await new Promise((resolve) => setTimeout(resolve, waitTime));
+        }
+        this.lastStartTime = Date.now();
+        elizaLogger.info(`🚀 Starting ngrok tunnel on port ${port}...`);
+        try {
+            const tunnelUrl = await this.attemptStartTunnel(port);
+            this.tunnelUrl = tunnelUrl;
+            this.tunnelPort = port;
+            this.startedAt = new Date();
+            elizaLogger.success(`✅ Ngrok tunnel started: ${tunnelUrl}`);
+            return tunnelUrl;
+        }
+        catch (error) {
+            elizaLogger.error('Failed to start ngrok tunnel:', errorMessage(error));
+            throw error;
+        }
+    }
+    async attemptStartTunnel(port) {
+        let attempts = 0;
+        const maxAttempts = 3;
+        const baseDelay = 2000;
+        while (attempts < maxAttempts) {
+            try {
+                return await this.startTunnelInternal(port);
+            }
+            catch (error) {
+                attempts++;
+                if (errorMessage(error).includes('domain might already be in use')) {
+                    if (attempts < maxAttempts) {
+                        elizaLogger.warn(`Domain conflict detected, retrying in ${baseDelay * attempts}ms (attempt ${attempts}/${maxAttempts})`);
+                        await new Promise((resolve) => setTimeout(resolve, baseDelay * attempts));
+                        // Try to stop any existing process just in case
+                        if (this.ngrokProcess) {
+                            this.ngrokProcess.kill();
+                            this.ngrokProcess = null;
+                            await new Promise((resolve) => setTimeout(resolve, 1000));
+                        }
+                        continue;
+                    }
+                }
+                throw error;
+            }
+        }
+        throw new Error(`Failed to start tunnel after ${maxAttempts} attempts`);
+    }
+    async startTunnelInternal(port) {
+        return new Promise((resolve, reject) => {
+            const args = ['http', port.toString()];
+            if (this.tunnelConfig.region) {
+                args.push('--region', this.tunnelConfig.region);
+            }
+            // Check for domain configuration
+            const domain = settingString(this.runtime.getSetting('NGROK_DOMAIN')) ?? process.env.NGROK_DOMAIN;
+            const useRandomSubdomain = settingString(this.runtime.getSetting('NGROK_USE_RANDOM_SUBDOMAIN')) === 'true';
+            if (domain && !useRandomSubdomain) {
+                args.push('--domain', domain);
+                elizaLogger.info(`Using ngrok domain: ${domain}`);
+            }
+            else if (this.tunnelConfig.subdomain && !useRandomSubdomain) {
+                // Only use subdomain if explicitly configured and not in test mode
+                // Note: Subdomains require a paid ngrok account
+                args.push('--subdomain', this.tunnelConfig.subdomain);
+                elizaLogger.info(`Using configured subdomain: ${this.tunnelConfig.subdomain}`);
+            }
+            // For free accounts or when random subdomain is requested,
+            // don't specify any domain/subdomain - let ngrok generate a random URL
+            this.ngrokProcess = spawn('ngrok', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+            let errorOccurred = false;
+            this.ngrokProcess.on('error', (error) => {
+                errorOccurred = true;
+                elizaLogger.error(`Failed to start ngrok: ${error.message}`);
+                reject(new Error(`Failed to start ngrok: ${error.message}`));
+            });
+            this.ngrokProcess.stderr?.on('data', (data) => {
+                const message = data.toString();
+                elizaLogger.error('Ngrok error:', message);
+                if (!errorOccurred) {
+                    errorOccurred = true;
+                    // Kill the process to clean up
+                    if (this.ngrokProcess && !this.ngrokProcess.killed) {
+                        this.ngrokProcess.kill();
+                    }
+                    // Handle specific error cases
+                    if (message.includes('invalid port')) {
+                        reject(new Error('Invalid port specified'));
+                    }
+                    else if (message.includes('address already in use')) {
+                        reject(new Error('Port is already in use'));
+                    }
+                    else if (message.includes('ERR_NGROK_15002') || message.includes('Pay-as-you-go')) {
+                        // Pay-as-you-go account requires domain
+                        if (!domain) {
+                            reject(new Error('Pay-as-you-go ngrok account requires NGROK_DOMAIN to be set. Please set NGROK_DOMAIN=your-domain.ngrok-free.app in your .env file'));
+                        }
+                        else {
+                            reject(new Error('Failed to start tunnel with pay-as-you-go account. Ensure your domain is registered at https://dashboard.ngrok.com/domains'));
+                        }
+                    }
+                    else if (message.includes('failed to start tunnel') ||
+                        message.includes('is already bound to another tunnel') ||
+                        message.includes('tunnel session failed')) {
+                        // This might happen if the domain is already in use
+                        reject(new Error('Failed to start tunnel - domain might already be in use'));
+                    }
+                    else {
+                        reject(new Error(`Ngrok error: ${message}`));
+                    }
+                }
+            });
+            // Give ngrok more time to start and handle multiple retry attempts
+            let retryCount = 0;
+            const maxRetries = 3;
+            const retryDelay = 2000;
+            const tryFetchUrl = async () => {
+                if (errorOccurred) {
+                    return; // Don't try to fetch URL if we already have an error
+                }
+                try {
+                    const url = await this.fetchTunnelUrl();
+                    if (url) {
+                        this.tunnelUrl = url;
+                        this.tunnelPort = port;
+                        this.startedAt = new Date();
+                        elizaLogger.success(`✅ Ngrok tunnel started: ${url}`);
+                        resolve(url);
+                    }
+                    else if (retryCount < maxRetries) {
+                        retryCount++;
+                        elizaLogger.warn(`Retrying to fetch tunnel URL (attempt ${retryCount}/${maxRetries})...`);
+                        setTimeout(tryFetchUrl, retryDelay);
+                    }
+                    else {
+                        reject(new Error('Failed to get tunnel URL from ngrok after multiple attempts'));
+                    }
+                }
+                catch (error) {
+                    if (retryCount < maxRetries && !errorOccurred) {
+                        retryCount++;
+                        elizaLogger.warn(`Retrying to fetch tunnel URL (attempt ${retryCount}/${maxRetries})...`);
+                        setTimeout(tryFetchUrl, retryDelay);
+                    }
+                    else {
+                        reject(error);
+                    }
+                }
+            };
+            setTimeout(tryFetchUrl, 2000);
+        });
+    }
+    async stopTunnel() {
+        if (!this.ngrokProcess) {
+            elizaLogger.warn('Ngrok tunnel is not running');
+            return;
+        }
+        elizaLogger.info('🛑 Stopping ngrok tunnel...');
+        return new Promise((resolve) => {
+            if (this.ngrokProcess) {
+                this.ngrokProcess.on('exit', () => {
+                    this.cleanup();
+                    elizaLogger.info('✅ Ngrok tunnel stopped');
+                    resolve();
+                });
+                this.ngrokProcess.kill();
+                setTimeout(() => {
+                    if (this.ngrokProcess && !this.ngrokProcess.killed) {
+                        this.ngrokProcess.kill('SIGKILL');
+                    }
+                    this.cleanup();
+                    resolve();
+                }, 5000);
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    getUrl() {
+        return this.tunnelUrl;
+    }
+    isActive() {
+        return this.ngrokProcess !== null && !this.ngrokProcess.killed && this.tunnelUrl !== null;
+    }
+    getStatus() {
+        return {
+            active: this.isActive(),
+            url: this.tunnelUrl,
+            port: this.tunnelPort,
+            startedAt: this.startedAt,
+            provider: 'ngrok',
+        };
+    }
+    cleanup() {
+        this.ngrokProcess = null;
+        this.tunnelUrl = null;
+        this.tunnelPort = null;
+        this.startedAt = null;
+    }
+    async checkNgrokInstalled() {
+        return new Promise((resolve) => {
+            const proc = spawn('which', ['ngrok']);
+            proc.on('exit', (code) => resolve(code === 0));
+            proc.on('error', () => resolve(false));
+        });
+    }
+    async setAuthToken(token) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn('ngrok', ['config', 'add-authtoken', token]);
+            proc.on('exit', (code) => {
+                if (code === 0) {
+                    elizaLogger.info('✅ Ngrok auth token configured');
+                    resolve();
+                }
+                else {
+                    reject(new Error('Failed to set ngrok auth token'));
+                }
+            });
+            proc.on('error', reject);
+        });
+    }
+    async fetchTunnelUrl() {
+        return new Promise((resolve) => {
+            http
+                .get('http://localhost:4040/api/tunnels', (res) => {
+                let data = '';
+                res.on('data', (chunk) => (data += chunk));
+                res.on('end', () => {
+                    try {
+                        const tunnels = JSON.parse(data);
+                        const httpsTunnel = tunnels.tunnels?.find((t) => t.proto === 'https');
+                        if (httpsTunnel?.public_url) {
+                            resolve(httpsTunnel.public_url);
+                        }
+                        else {
+                            elizaLogger.warn('No HTTPS tunnel found in ngrok response');
+                            resolve(null);
+                        }
+                    }
+                    catch (error) {
+                        const msg = error instanceof Error ? error.message : String(error);
+                        elizaLogger.error(`Failed to parse ngrok API response: ${msg}`);
+                        resolve(null);
+                    }
+                });
+            })
+                .on('error', (error) => {
+                elizaLogger.error(`Failed to connect to ngrok API: ${error.message}`);
+                resolve(null);
+            });
+        });
+    }
+}
+//# sourceMappingURL=NgrokService.js.map

package/dist/services/NgrokService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NgrokService.js","sourceRoot":"","sources":["../../src/services/NgrokService.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@elizaos/plugin-ngrok",
+  "version": "2.0.0-beta.1",
+  "description": "Ngrok tunnel plugin for elizaOS — third-party backend implementing the @elizaos/plugin-tunnel ITunnelService contract.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc --noCheck -p tsconfig.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "bun run --cwd ../plugin-tunnel build && bun test",
+    "test:unit": "bun test src/__tests__/unit/",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format ."
+  },
+  "keywords": [
+    "elizaos",
+    "plugin",
+    "tunnel",
+    "ngrok",
+    "networking"
+  ],
+  "peerDependencies": {
+    "@elizaos/core": "2.0.0-beta.1",
+    "@elizaos/plugin-tunnel": "2.0.0-beta.1"
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.0-beta.1",
+    "@elizaos/plugin-tunnel": "2.0.0-beta.1",
+    "@ngrok/ngrok": "^1.5.1",
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/bun": "^1.3.8",
+    "@types/node": "^25.1.0",
+    "dotenv": "^17.2.3",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {}
+  }
+}

package/src/__tests__/NgrokTestSuite.ts

@@ -0,0 +1,110 @@
+import type { IAgentRuntime, TestCase } from '@elizaos/core';
+import { NgrokService } from '../services/NgrokService';
+
+export class NgrokTestSuite {
+  name = 'ngrok';
+  tests: TestCase[] = [
+    {
+      name: 'Initialize Ngrok Service',
+      fn: async (runtime: IAgentRuntime) => {
+        // Test service initialization
+        const service = new NgrokService(runtime);
+
+        // Verify service is initialized
+        if (!service) {
+          throw new Error('Failed to initialize Ngrok service');
+        }
+
+        if (!(service instanceof NgrokService)) {
+          throw new Error('Service is not instance of NgrokService');
+        }
+      },
+    },
+    {
+      name: 'Start and Stop Tunnel',
+      fn: async (runtime: IAgentRuntime) => {
+        const service = new NgrokService(runtime);
+
+        // Test starting tunnel
+        const url = await service.startTunnel(3000);
+
+        if (!url?.startsWith('https://')) {
+          throw new Error('Failed to start tunnel or invalid URL returned');
+        }
+
+        // Verify tunnel is active
+        if (!service.isActive()) {
+          throw new Error('Tunnel should be active after starting');
+        }
+
+        // Test getting status
+        const status = service.getStatus();
+        if (!status.active || status.port !== 3000) {
+          throw new Error('Invalid tunnel status');
+        }
+
+        // Test stopping tunnel
+        await service.stopTunnel();
+
+        // Verify tunnel is stopped
+        if (service.isActive()) {
+          throw new Error('Tunnel should not be active after stopping');
+        }
+      },
+    },
+    {
+      name: 'Service Registration',
+      fn: async (runtime: IAgentRuntime) => {
+        // Test that service can be registered and retrieved
+        const _service = new NgrokService(runtime);
+
+        // In a real test, we would register the service with runtime
+        // and then retrieve it to verify registration
+        const serviceType = NgrokService.serviceType;
+        if (serviceType !== 'tunnel') {
+          throw new Error('Service type should be "tunnel"');
+        }
+      },
+    },
+    {
+      name: 'Tunnel Status When Inactive',
+      fn: async (runtime: IAgentRuntime) => {
+        const service = new NgrokService(runtime);
+
+        // Get status when tunnel is not active
+        const status = service.getStatus();
+
+        if (status.active) {
+          throw new Error('Tunnel should not be active initially');
+        }
+
+        if (status.url !== null || status.port !== null) {
+          throw new Error('URL and port should be null when inactive');
+        }
+
+        if (status.provider !== 'ngrok') {
+          throw new Error('Provider should always be "ngrok"');
+        }
+      },
+    },
+    {
+      name: 'Multiple Start Attempts',
+      fn: async (runtime: IAgentRuntime) => {
+        const service = new NgrokService(runtime);
+
+        // Start tunnel
+        const url1 = await service.startTunnel(3000);
+
+        // Try to start again (should return same URL)
+        const url2 = await service.startTunnel(3000);
+
+        if (url1 !== url2) {
+          throw new Error('Starting tunnel twice should return the same URL');
+        }
+
+        // Clean up
+        await service.stopTunnel();
+      },
+    },
+  ];
+}

package/src/__tests__/debug-mock.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'bun:test';
+import { createMockRuntime } from './test-utils';
+
+describe('Debug Mock Runtime', () => {
+  it('should have getSetting method', () => {
+    const runtime = createMockRuntime();
+
+    console.log('Runtime object keys:', Object.keys(runtime));
+    console.log('getSetting method exists:', typeof runtime.getSetting);
+    console.log('getSetting result for NGROK_AUTH_TOKEN:', runtime.getSetting('NGROK_AUTH_TOKEN'));
+
+    expect(typeof runtime.getSetting).toBe('function');
+    expect(runtime.getSetting('NGROK_AUTH_TOKEN')).toBeDefined();
+  });
+});