@elizaos/plugin-tunnel 2.0.0-beta.1

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2C,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAOrF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,MAwB1B,CAAC;AAEF,eAAe,YAAY,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,KAAK,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC5F,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+import { elizaLogger, promoteSubactionsToActions } from '@elizaos/core';
+import { TunnelTestSuite } from './__tests__/TunnelTestSuite';
+import { tunnelAction } from './actions/tunnel';
+import { tunnelStateProvider } from './providers/tunnel-state';
+import { checkTailscaleInstalled, LocalTunnelService } from './services/LocalTunnelService';
+import { tunnelSlotIsFree } from './types';
+/**
+ * Local Tailscale-CLI tunnel plugin.
+ *
+ * Registers `serviceType = "tunnel"` ONLY when:
+ *  1. No other tunnel service has already claimed the slot (first-active-wins
+ *     across plugin-tunnel, plugin-elizacloud, plugin-ngrok), AND
+ *  2. The `tailscale` CLI is on PATH.
+ *
+ * The Eliza Cloud (headscale) tunnel lives in `@elizaos/plugin-elizacloud`.
+ * Ngrok lives in `@elizaos/plugin-ngrok`. Enable as many as you like — only
+ * one will bind.
+ */
+export const tunnelPlugin = {
+    name: 'tunnel',
+    description: 'Local Tailscale-CLI tunnel backend (serve / funnel). Coexists with plugin-elizacloud and plugin-ngrok via first-active-wins registration.',
+    actions: [...promoteSubactionsToActions(tunnelAction)],
+    providers: [tunnelStateProvider],
+    tests: [new TunnelTestSuite()],
+    init: async (_config, runtime) => {
+        if (!tunnelSlotIsFree(runtime)) {
+            elizaLogger.info('[plugin-tunnel] another tunnel service already registered — skipping LocalTunnelService');
+            return;
+        }
+        const installed = await checkTailscaleInstalled();
+        if (!installed) {
+            elizaLogger.info('[plugin-tunnel] tailscale CLI not found on PATH — skipping LocalTunnelService');
+            return;
+        }
+        elizaLogger.info('[plugin-tunnel] registering LocalTunnelService for serviceType="tunnel"');
+        await runtime.registerService(LocalTunnelService);
+    },
+};
+export default tunnelPlugin;
+export { tunnelAction } from './actions/tunnel';
+export { validateTunnelConfig } from './environment';
+export { tunnelStateProvider } from './providers/tunnel-state';
+// Public surface for consumers and sibling tunnel plugins.
+export { checkTailscaleInstalled, LocalTunnelService } from './services/LocalTunnelService';
+export { getTunnelService, tunnelSlotIsFree, } from './types';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,0BAA0B,EAAe,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAW;IAClC,IAAI,EAAE,QAAQ;IACd,WAAW,EACT,2IAA2I;IAC7I,OAAO,EAAE,CAAC,GAAG,0BAA0B,CAAC,YAAY,CAAC,CAAC;IACtD,SAAS,EAAE,CAAC,mBAAmB,CAAC;IAChC,KAAK,EAAE,CAAC,IAAI,eAAe,EAAE,CAAC;IAC9B,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QAC/B,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/B,WAAW,CAAC,IAAI,CACd,yFAAyF,CAC1F,CAAC;YACF,OAAO;QACT,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,uBAAuB,EAAE,CAAC;QAClD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,WAAW,CAAC,IAAI,CACd,+EAA+E,CAChF,CAAC;YACF,OAAO;QACT,CAAC;QACD,WAAW,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;QAC5F,MAAM,OAAO,CAAC,eAAe,CAAC,kBAAkB,CAAC,CAAC;IACpD,CAAC;CACF,CAAC;AAEF,eAAe,YAAY,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAqB,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,2DAA2D;AAC3D,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC5F,OAAO,EACL,gBAAgB,EAIhB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/providers/tunnel-state.d.ts

@@ -0,0 +1,12 @@
+import type { Provider } from '@elizaos/core';
+/**
+ * Surfaces the active tunnel's status into the model's state. Renders a
+ * one-line text summary and exposes the raw status object via `data`.
+ *
+ * Backend-agnostic — works with whichever tunnel implementation
+ * (`LocalTunnelService` here, `CloudTunnelService` in plugin-elizacloud,
+ * the ngrok service, etc.) won the `serviceType="tunnel"` slot.
+ */
+export declare const tunnelStateProvider: Provider;
+export default tunnelStateProvider;
+//# sourceMappingURL=tunnel-state.d.ts.map

package/dist/providers/tunnel-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-state.d.ts","sourceRoot":"","sources":["../../src/providers/tunnel-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAgCjC,CAAC;AAEF,eAAe,mBAAmB,CAAC"}

package/dist/providers/tunnel-state.js

@@ -0,0 +1,43 @@
+import { getTunnelService } from '../types';
+/**
+ * Surfaces the active tunnel's status into the model's state. Renders a
+ * one-line text summary and exposes the raw status object via `data`.
+ *
+ * Backend-agnostic — works with whichever tunnel implementation
+ * (`LocalTunnelService` here, `CloudTunnelService` in plugin-elizacloud,
+ * the ngrok service, etc.) won the `serviceType="tunnel"` slot.
+ */
+export const tunnelStateProvider = {
+    name: 'TUNNEL_STATE',
+    description: 'Current tunnel status: active flag, public URL, local port, provider, backend.',
+    descriptionCompressed: 'Tunnel: active/url/port/provider/backend',
+    contexts: ['devtools', 'system'],
+    relevanceKeywords: ['tunnel', 'tailscale', 'headscale', 'ngrok', 'serve', 'funnel', 'expose'],
+    position: 200,
+    get: async (runtime, _message) => {
+        const svc = getTunnelService(runtime);
+        if (!svc) {
+            return {
+                text: 'No tunnel service is registered.',
+                data: {
+                    active: false,
+                    available: false,
+                },
+            };
+        }
+        const status = svc.getStatus();
+        const text = status.active
+            ? `Tunnel ACTIVE — ${status.url ?? 'unknown URL'} (port ${status.port}, ${status.provider}${status.backend ? `/${status.backend}` : ''})`
+            : `Tunnel idle (${status.provider} ready).`;
+        return {
+            text,
+            data: {
+                available: true,
+                ...status,
+                startedAt: status.startedAt ? status.startedAt.toISOString() : null,
+            },
+        };
+    },
+};
+export default tunnelStateProvider;
+//# sourceMappingURL=tunnel-state.js.map

package/dist/providers/tunnel-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-state.js","sourceRoot":"","sources":["../../src/providers/tunnel-state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAa;IAC3C,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,gFAAgF;IAC7F,qBAAqB,EAAE,0CAA0C;IACjE,QAAQ,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;IAChC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC;IAC7F,QAAQ,EAAE,GAAG;IAEb,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO;gBACL,IAAI,EAAE,kCAAkC;gBACxC,IAAI,EAAE;oBACJ,MAAM,EAAE,KAAK;oBACb,SAAS,EAAE,KAAK;iBACjB;aACF,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM;YACxB,CAAC,CAAC,mBAAmB,MAAM,CAAC,GAAG,IAAI,aAAa,UAAU,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG;YACzI,CAAC,CAAC,gBAAgB,MAAM,CAAC,QAAQ,UAAU,CAAC;QAC9C,OAAO;YACL,IAAI;YACJ,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI;gBACf,GAAG,MAAM;gBACT,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;aACpE;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,mBAAmB,CAAC"}

package/dist/services/LocalTunnelService.d.ts

@@ -0,0 +1,37 @@
+import { type IAgentRuntime, Service } from '@elizaos/core';
+import type { ITunnelService, TunnelStatus } from '../types';
+export declare function checkTailscaleInstalled(): Promise<boolean>;
+/**
+ * Tunnel service backed by the locally-installed `tailscale` CLI.
+ *
+ * The user is responsible for `tailscale up` (i.e. authenticating with
+ * Tailscale's coordination server, OR with a self-hosted headscale via
+ * `--login-server`). This service just calls `tailscale serve` / `tailscale
+ * funnel` to expose a port and reads `tailscale status --json` to learn the
+ * tailnet DNS name.
+ *
+ * Coexists with `@elizaos/plugin-elizacloud`'s cloud tunnel and
+ * `@elizaos/plugin-ngrok` — only the first one to register `serviceType="tunnel"`
+ * wins. This service registers itself only if the `tailscale` binary is on
+ * `PATH`, gating out machines that have no Tailscale install.
+ */
+export declare class LocalTunnelService extends Service implements ITunnelService {
+    static serviceType: string;
+    readonly capabilityDescription = "Tunnel via the locally-installed `tailscale` CLI (serve / funnel). User authenticates separately with `tailscale up`.";
+    private tunnelUrl;
+    private tunnelPort;
+    private startedAt;
+    private isShuttingDown;
+    private useFunnel;
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    startTunnel(port?: number): Promise<string | undefined>;
+    stopTunnel(): Promise<void>;
+    getUrl(): string | null;
+    isActive(): boolean;
+    getStatus(): TunnelStatus;
+    private fetchSelfDnsName;
+    private cleanup;
+}
+//# sourceMappingURL=LocalTunnelService.d.ts.map

package/dist/services/LocalTunnelService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalTunnelService.d.ts","sourceRoot":"","sources":["../../src/services/LocalTunnelService.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGzE,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AA2C7D,wBAAgB,uBAAuB,IAAI,OAAO,CAAC,OAAO,CAAC,CAM1D;AAaD;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,SAAQ,OAAQ,YAAW,cAAc;IACvE,OAAgB,WAAW,SAAY;IACvC,QAAQ,CAAC,qBAAqB,2HAC4F;IAE1H,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;WAEJ,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAM/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAwDvD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBjC,MAAM,IAAI,MAAM,GAAG,IAAI;IAIvB,QAAQ,IAAI,OAAO;IAInB,SAAS,IAAI,YAAY;YAWX,gBAAgB;IAgB9B,OAAO,CAAC,OAAO;CAMhB"}

package/dist/services/LocalTunnelService.js

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import { elizaLogger, Service } from '@elizaos/core';
+import { z } from 'zod';
+import { validateTunnelConfig } from '../environment';
+const tailscaleStatusPeerSchema = z.object({
+    DNSName: z.string().optional(),
+    Online: z.boolean().optional(),
+});
+const tailscaleStatusSchema = z.object({
+    Self: z
+        .object({
+        DNSName: z.string().optional(),
+    })
+        .optional(),
+    MagicDNSSuffix: z.string().optional(),
+    Peer: z.record(z.string(), tailscaleStatusPeerSchema).optional(),
+});
+function runCommand(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        const out = [];
+        const err = [];
+        child.stdout?.on('data', (chunk) => out.push(chunk));
+        child.stderr?.on('data', (chunk) => err.push(chunk));
+        child.on('error', reject);
+        child.on('exit', (code) => resolve({
+            code,
+            stdout: Buffer.concat(out).toString('utf8'),
+            stderr: Buffer.concat(err).toString('utf8'),
+        }));
+    });
+}
+export function checkTailscaleInstalled() {
+    return new Promise((resolve) => {
+        const proc = spawn('which', ['tailscale']);
+        proc.on('exit', (code) => resolve(code === 0));
+        proc.on('error', () => resolve(false));
+    });
+}
+function parseTailscaleStatus(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const result = tailscaleStatusSchema.safeParse(raw);
+    return result.success ? result.data : null;
+}
+/**
+ * Tunnel service backed by the locally-installed `tailscale` CLI.
+ *
+ * The user is responsible for `tailscale up` (i.e. authenticating with
+ * Tailscale's coordination server, OR with a self-hosted headscale via
+ * `--login-server`). This service just calls `tailscale serve` / `tailscale
+ * funnel` to expose a port and reads `tailscale status --json` to learn the
+ * tailnet DNS name.
+ *
+ * Coexists with `@elizaos/plugin-elizacloud`'s cloud tunnel and
+ * `@elizaos/plugin-ngrok` — only the first one to register `serviceType="tunnel"`
+ * wins. This service registers itself only if the `tailscale` binary is on
+ * `PATH`, gating out machines that have no Tailscale install.
+ */
+export class LocalTunnelService extends Service {
+    static serviceType = 'tunnel';
+    capabilityDescription = 'Tunnel via the locally-installed `tailscale` CLI (serve / funnel). User authenticates separately with `tailscale up`.';
+    tunnelUrl = null;
+    tunnelPort = null;
+    startedAt = null;
+    isShuttingDown = false;
+    useFunnel = false;
+    static async start(runtime) {
+        const service = new LocalTunnelService(runtime);
+        await service.start();
+        return service;
+    }
+    async start() {
+        elizaLogger.info('[LocalTunnelService] starting');
+        const installed = await checkTailscaleInstalled();
+        if (!installed) {
+            throw new Error('tailscale is not installed. Install from https://tailscale.com/download or run: brew install tailscale');
+        }
+    }
+    async stop() {
+        await this.stopTunnel();
+    }
+    async startTunnel(port) {
+        if (this.isActive()) {
+            elizaLogger.warn('[LocalTunnelService] tunnel already running');
+            return this.tunnelUrl ?? undefined;
+        }
+        if (port === undefined || port === null) {
+            elizaLogger.warn('[LocalTunnelService] startTunnel called without a port — service active but no tunnel started');
+            return;
+        }
+        if (port < 1 || port > 65535) {
+            throw new Error('Invalid port number');
+        }
+        const config = await validateTunnelConfig(this.runtime);
+        this.useFunnel = config.TUNNEL_FUNNEL;
+        elizaLogger.info(`[LocalTunnelService] starting tunnel on port ${port} (funnel=${this.useFunnel})`);
+        if (this.useFunnel) {
+            const result = await runCommand('tailscale', ['funnel', String(port)]);
+            if (result.code !== 0) {
+                throw new Error(`tailscale funnel exited with code ${result.code}: ${result.stderr.trim()}`);
+            }
+        }
+        else {
+            const result = await runCommand('tailscale', [
+                'serve',
+                '--bg',
+                '--https=443',
+                `localhost:${port}`,
+            ]);
+            if (result.code !== 0) {
+                throw new Error(`tailscale serve exited with code ${result.code}: ${result.stderr.trim()}`);
+            }
+        }
+        const dnsName = await this.fetchSelfDnsName();
+        if (!dnsName) {
+            throw new Error('tailscale serve started but no DNSName resolved from `tailscale status --json`');
+        }
+        this.tunnelUrl = `https://${dnsName}`;
+        this.tunnelPort = port;
+        this.startedAt = new Date();
+        elizaLogger.info(`[LocalTunnelService] tunnel started: ${this.tunnelUrl}`);
+        return this.tunnelUrl;
+    }
+    async stopTunnel() {
+        if (!this.isActive()) {
+            elizaLogger.warn('[LocalTunnelService] no active tunnel to stop');
+            return;
+        }
+        this.isShuttingDown = true;
+        elizaLogger.info('[LocalTunnelService] stopping tunnel');
+        if (this.useFunnel) {
+            await runCommand('tailscale', ['funnel', 'reset']);
+        }
+        else {
+            await runCommand('tailscale', ['serve', 'reset']);
+        }
+        this.cleanup();
+        this.isShuttingDown = false;
+        elizaLogger.info('[LocalTunnelService] tunnel stopped');
+    }
+    getUrl() {
+        return this.tunnelUrl;
+    }
+    isActive() {
+        return this.tunnelUrl !== null && !this.isShuttingDown;
+    }
+    getStatus() {
+        return {
+            active: this.isActive(),
+            url: this.tunnelUrl,
+            port: this.tunnelPort,
+            startedAt: this.startedAt,
+            provider: 'tailscale',
+            backend: 'local-cli',
+        };
+    }
+    async fetchSelfDnsName() {
+        const result = await runCommand('tailscale', ['status', '--json']);
+        if (result.code !== 0) {
+            elizaLogger.error(`[LocalTunnelService] tailscale status failed: ${result.stderr.trim()}`);
+            return null;
+        }
+        const status = parseTailscaleStatus(result.stdout);
+        if (!status) {
+            elizaLogger.error('[LocalTunnelService] tailscale status returned malformed JSON');
+            return null;
+        }
+        const raw = status.Self?.DNSName;
+        if (!raw)
+            return null;
+        return raw.replace(/\.$/, '');
+    }
+    cleanup() {
+        this.tunnelUrl = null;
+        this.tunnelPort = null;
+        this.startedAt = null;
+        this.useFunnel = false;
+    }
+}
+//# sourceMappingURL=LocalTunnelService.js.map

package/dist/services/LocalTunnelService.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Tunnel-service contract shared across all elizaOS tunnel plugins.
+ *
+ * All tunnel plugins (`@elizaos/plugin-tunnel`, `@elizaos/plugin-elizacloud`'s
+ * cloud tunnel, `@elizaos/plugin-ngrok`) register under
+ * `serviceType = "tunnel"` so consumers stay backend-agnostic via
+ * `runtime.getService("tunnel")`. The runtime returns the FIRST registered
+ * service for a given type, so plugins coordinate via conditional
+ * registration: each plugin's `init` only registers if its credentials are
+ * present and no other tunnel service has already claimed the slot.
+ */
+import type { IAgentRuntime } from '@elizaos/core';
+declare module '@elizaos/core' {
+    interface ServiceTypeRegistry {
+        TUNNEL: 'tunnel';
+    }
+}
+export type TunnelProvider = 'tailscale' | 'headscale' | 'ngrok';
+export interface TunnelStatus {
+    active: boolean;
+    url: string | null;
+    port: number | null;
+    startedAt: Date | null;
+    provider: TunnelProvider;
+    /** Optional human label distinguishing backend variants (e.g. "local-cli", "eliza-cloud-headscale"). */
+    backend?: string;
+}
+export interface ITunnelService {
+    startTunnel(port?: number): Promise<string | undefined>;
+    stopTunnel(): Promise<void>;
+    getUrl(): string | null;
+    isActive(): boolean;
+    getStatus(): TunnelStatus;
+}
+/**
+ * Backend-agnostic accessor. Returns the first registered service that
+ * implements the tunnel contract; returns null if nothing is registered or
+ * the registered service doesn't satisfy the shape (defensive guard against
+ * an unrelated service registering under "tunnel").
+ */
+export declare function getTunnelService(runtime: IAgentRuntime): ITunnelService | null;
+/**
+ * True iff no tunnel service has claimed `serviceType="tunnel"` yet.
+ * Used by tunnel plugins' `init` hooks to coordinate "first active wins".
+ */
+export declare function tunnelSlotIsFree(runtime: IAgentRuntime): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAW,MAAM,eAAe,CAAC;AAE5D,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,mBAAmB;QAC3B,MAAM,EAAE,QAAQ,CAAC;KAClB;CACF;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,wGAAwG;IACxG,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,IAAI,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,IAAI,OAAO,CAAC;IACpB,SAAS,IAAI,YAAY,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,GAAG,IAAI,CAO9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAEhE"}

package/dist/types.js

@@ -0,0 +1,34 @@
+/**
+ * Tunnel-service contract shared across all elizaOS tunnel plugins.
+ *
+ * All tunnel plugins (`@elizaos/plugin-tunnel`, `@elizaos/plugin-elizacloud`'s
+ * cloud tunnel, `@elizaos/plugin-ngrok`) register under
+ * `serviceType = "tunnel"` so consumers stay backend-agnostic via
+ * `runtime.getService("tunnel")`. The runtime returns the FIRST registered
+ * service for a given type, so plugins coordinate via conditional
+ * registration: each plugin's `init` only registers if its credentials are
+ * present and no other tunnel service has already claimed the slot.
+ */
+/**
+ * Backend-agnostic accessor. Returns the first registered service that
+ * implements the tunnel contract; returns null if nothing is registered or
+ * the registered service doesn't satisfy the shape (defensive guard against
+ * an unrelated service registering under "tunnel").
+ */
+export function getTunnelService(runtime) {
+    const service = runtime.getService('tunnel');
+    if (!service)
+        return null;
+    if (typeof service.startTunnel !== 'function') {
+        return null;
+    }
+    return service;
+}
+/**
+ * True iff no tunnel service has claimed `serviceType="tunnel"` yet.
+ * Used by tunnel plugins' `init` hooks to coordinate "first active wins".
+ */
+export function tunnelSlotIsFree(runtime) {
+    return runtime.getService('tunnel') === null;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8BH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,OAAQ,OAAmC,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAmC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,OAAO,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@elizaos/plugin-tunnel",
+  "version": "2.0.0-beta.1",
+  "description": "Tunnel plugin for elizaOS — local Tailscale CLI backend (serve/funnel). Pair with @elizaos/plugin-elizacloud for the hosted headscale backend.",
+  "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 test",
+    "test:unit": "bun test src/__tests__/",
+    "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",
+    "tailscale",
+    "networking"
+  ],
+  "peerDependencies": {
+    "@elizaos/core": "2.0.0-beta.1"
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.0-beta.1",
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/bun": "^1.3.8",
+    "@types/node": "^25.1.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {}
+  }
+}

package/src/__tests__/TunnelTestSuite.ts

@@ -0,0 +1,46 @@
+import type { IAgentRuntime, TestCase, TestSuite } from '@elizaos/core';
+import { tunnelAction } from '../actions/tunnel';
+import { tunnelStateProvider } from '../providers/tunnel-state';
+import { LocalTunnelService } from '../services/LocalTunnelService';
+
+export class TunnelTestSuite implements TestSuite {
+  name = 'tunnel';
+  tests: TestCase[] = [
+    {
+      name: 'LocalTunnelService — service-type contract',
+      fn: (_runtime: IAgentRuntime) => {
+        if (LocalTunnelService.serviceType !== 'tunnel') {
+          throw new Error('LocalTunnelService.serviceType must be "tunnel"');
+        }
+      },
+    },
+    {
+      name: 'tunnelAction — name and op enum',
+      fn: (_runtime: IAgentRuntime) => {
+        if (tunnelAction.name !== 'TUNNEL') {
+          throw new Error(`tunnelAction.name must be "TUNNEL", got ${tunnelAction.name}`);
+        }
+        const opParam = tunnelAction.parameters?.find((p) => p.name === 'op');
+        if (!opParam) throw new Error('tunnelAction must declare an `op` parameter');
+        const enumVals = (opParam.schema as { enum?: unknown[] } | undefined)?.enum;
+        if (!Array.isArray(enumVals)) throw new Error('op parameter must declare a string enum');
+        for (const expected of ['start', 'stop', 'status']) {
+          if (!enumVals.includes(expected)) {
+            throw new Error(`op enum missing "${expected}"`);
+          }
+        }
+      },
+    },
+    {
+      name: 'TUNNEL_STATE provider — name and shape',
+      fn: (_runtime: IAgentRuntime) => {
+        if (tunnelStateProvider.name !== 'TUNNEL_STATE') {
+          throw new Error(`tunnelStateProvider.name must be "TUNNEL_STATE"`);
+        }
+        if (typeof tunnelStateProvider.get !== 'function') {
+          throw new Error('tunnelStateProvider must define get()');
+        }
+      },
+    },
+  ];
+}

package/src/__tests__/unit/local-tunnel-service.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { tunnelAction } from '../../actions/tunnel';
+import { tunnelStateProvider } from '../../providers/tunnel-state';
+import { LocalTunnelService } from '../../services/LocalTunnelService';
+
+describe('plugin-tunnel exports', () => {
+  it('LocalTunnelService registers under serviceType="tunnel"', () => {
+    expect(LocalTunnelService.serviceType).toBe('tunnel');
+  });
+
+  it('TUNNEL action exposes start/stop/status enum and similes', () => {
+    expect(tunnelAction.name).toBe('TUNNEL');
+    const opParam = tunnelAction.parameters?.find((p) => p.name === 'action');
+    expect(opParam).toBeDefined();
+    expect((opParam?.schema as { enum?: string[] }).enum).toEqual(['start', 'stop', 'status']);
+    expect(tunnelAction.similes).toEqual(expect.arrayContaining(['TAILSCALE', 'START_TUNNEL']));
+  });
+
+  it('TUNNEL_STATE provider has get() and is named correctly', () => {
+    expect(tunnelStateProvider.name).toBe('TUNNEL_STATE');
+    expect(typeof tunnelStateProvider.get).toBe('function');
+  });
+});

package/src/actions/get-tunnel-status.ts

@@ -0,0 +1,60 @@
+import {
+  type ActionResult,
+  elizaLogger,
+  type HandlerCallback,
+  type IAgentRuntime,
+  type Memory,
+  type State,
+} from '@elizaos/core';
+import { getTunnelService } from '../types';
+
+function formatUptime(startedAt: Date): string {
+  const ms = Date.now() - startedAt.getTime();
+  const minutes = Math.floor(ms / 60_000);
+  const hours = Math.floor(minutes / 60);
+  if (hours > 0) {
+    return `${hours} hour${hours === 1 ? '' : 's'}, ${minutes % 60} minute${minutes % 60 === 1 ? '' : 's'}`;
+  }
+  return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
+
+export async function handleGetTunnelStatus(
+  runtime: IAgentRuntime,
+  _message?: Memory,
+  _state?: State,
+  _options?: Record<string, unknown>,
+  callback?: HandlerCallback
+): Promise<ActionResult> {
+  const tunnelService = getTunnelService(runtime);
+  if (!tunnelService) {
+    if (callback) {
+      await callback({ text: 'Tunnel service is not available.' });
+    }
+    return { success: false, error: 'tunnel service unavailable' };
+  }
+
+  elizaLogger.info('[get-tunnel-status] reading status');
+  const status = tunnelService.getStatus();
+  const uptime = status.startedAt ? formatUptime(status.startedAt) : 'N/A';
+
+  const responseText = status.active
+    ? `✅ tunnel active (${status.provider}).\n\nURL: ${status.url}\nLocal port: ${status.port}\nUptime: ${uptime}`
+    : '❌ No active tunnel. Say "start tunnel on port [PORT]" to start one.';
+
+  if (callback) {
+    await callback({ text: responseText });
+  }
+  return {
+    success: true,
+    text: responseText,
+    data: {
+      action: 'tunnel_status',
+      active: status.active,
+      url: status.url ?? '',
+      port: status.port ?? 0,
+      provider: status.provider,
+      backend: status.backend ?? '',
+      uptime,
+    },
+  };
+}