@elizaos/plugin-tunnel 2.0.0-beta.1

package/src/actions/start-tunnel.ts

@@ -0,0 +1,117 @@
+import {
+  type ActionResult,
+  elizaLogger,
+  type HandlerCallback,
+  type IAgentRuntime,
+  type Memory,
+  ModelType,
+  type State,
+} from '@elizaos/core';
+import { z } from 'zod';
+import { getTunnelService } from '../types';
+
+const portPayloadSchema = z.object({
+  port: z.union([z.number(), z.string().regex(/^\d+$/)]).transform((value) => {
+    const num = typeof value === 'string' ? Number.parseInt(value, 10) : value;
+    return num;
+  }),
+});
+
+const PORT_PROMPT_TEMPLATE = `Respond with a JSON object containing the port number to start the tunnel on.
+The user said: "{{userMessage}}"
+
+Extract the port number from their message, or use the default port 3000 if not specified.
+
+Response format:
+\`\`\`json
+{ "port": 3000 }
+\`\`\``;
+
+const DEFAULT_PORT = 3000;
+
+function isValidPort(value: number): boolean {
+  return Number.isInteger(value) && value >= 1 && value <= 65535;
+}
+
+function parsePort(value: string): number {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    const result = portPayloadSchema.safeParse(parsed);
+    if (result.success && isValidPort(result.data.port)) return result.data.port;
+  } catch {
+    // fall through
+  }
+  const match = value.match(/\b(\d{1,5})\b/);
+  const captured = match?.[1];
+  if (!captured) return DEFAULT_PORT;
+  const num = Number.parseInt(captured, 10);
+  return isValidPort(num) ? num : DEFAULT_PORT;
+}
+
+export async function handleStartTunnel(
+  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. Configure plugin-tunnel, plugin-elizacloud, or plugin-ngrok.',
+      });
+    }
+    return { success: false, error: 'tunnel service unavailable' };
+  }
+
+  if (tunnelService.isActive()) {
+    if (callback) {
+      await callback({
+        text: 'Tunnel is already active. Stop the existing tunnel before starting a new one.',
+      });
+    }
+    return { success: false, error: 'tunnel already active' };
+  }
+
+  elizaLogger.info('[start-tunnel] starting tunnel');
+
+  let port: number | undefined;
+  const explicitPort = options?.port;
+  if (typeof explicitPort === 'number' && isValidPort(explicitPort)) {
+    port = explicitPort;
+  } else if (typeof explicitPort === 'string' && /^\d+$/.test(explicitPort)) {
+    const parsed = Number.parseInt(explicitPort, 10);
+    if (isValidPort(parsed)) port = parsed;
+  }
+
+  if (port === undefined) {
+    const userMessage = message.content.text ?? '';
+    const portResponse = await runtime.useModel(ModelType.TEXT_SMALL, {
+      prompt: PORT_PROMPT_TEMPLATE.replace('{{userMessage}}', userMessage),
+      temperature: 0.3,
+    });
+    port = parsePort(String(portResponse));
+  }
+
+  const url = await tunnelService.startTunnel(port);
+  const publicUrl = typeof url === 'string' ? url : tunnelService.getUrl();
+  const status = tunnelService.getStatus();
+
+  if (callback) {
+    await callback({
+      text: `Tunnel started (${status.provider}).\n\nURL: ${publicUrl ?? 'unknown'}\nLocal port: ${port}`,
+    });
+  }
+
+  return {
+    success: true,
+    text: `Tunnel started on port ${port}`,
+    data: {
+      action: 'tunnel_started',
+      tunnelUrl: publicUrl ?? '',
+      port,
+      provider: status.provider,
+    },
+  };
+}

package/src/actions/stop-tunnel.ts

@@ -0,0 +1,58 @@
+import {
+  type ActionResult,
+  elizaLogger,
+  type HandlerCallback,
+  type IAgentRuntime,
+  type Memory,
+  type State,
+} from '@elizaos/core';
+import { getTunnelService } from '../types';
+
+export async function handleStopTunnel(
+  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' };
+  }
+
+  if (!tunnelService.isActive()) {
+    elizaLogger.warn('[stop-tunnel] no active tunnel to stop');
+    if (callback) {
+      await callback({ text: 'No tunnel is currently running.' });
+    }
+    return {
+      success: true,
+      text: 'no active tunnel',
+      data: { action: 'tunnel_not_active' },
+    };
+  }
+
+  const status = tunnelService.getStatus();
+  const previousUrl = status.url;
+  const previousPort = status.port;
+
+  await tunnelService.stopTunnel();
+
+  if (callback) {
+    await callback({
+      text: `Tunnel stopped.\n\nWas running on port: ${previousPort}\nPrevious URL: ${previousUrl}`,
+    });
+  }
+  return {
+    success: true,
+    text: `Tunnel stopped (was on port ${previousPort})`,
+    data: {
+      action: 'tunnel_stopped',
+      previousUrl: previousUrl ?? '',
+      previousPort: previousPort ?? 0,
+    },
+  };
+}

package/src/actions/tunnel.ts

@@ -0,0 +1,193 @@
+/**
+ * @module tunnel
+ * @description Single dispatcher action that fans out to the active
+ * tunnel-service implementation. The action's name is `TUNNEL`; legacy
+ * `TAILSCALE`-prefixed action names are kept as `similes` so older
+ * characters and callers still resolve.
+ *
+ * Sub-ops (selected via the `action` parameter-enum):
+ *   - start  -> handleStartTunnel    (optional `port`, defaults to 3000)
+ *   - stop   -> handleStopTunnel     (no parameters)
+ *   - status -> handleGetTunnelStatus (no parameters)
+ *
+ * The handler accepts both call shapes:
+ *   1. `{ action, ...subParams }`
+ *   2. `{ parameters: { action, parameters: { ...subParams } } }` (LLM extraction)
+ */
+
+import type {
+  Action,
+  ActionResult,
+  HandlerCallback,
+  IAgentRuntime,
+  Memory,
+  State,
+} from '@elizaos/core';
+import { getTunnelService } from '../types';
+import { handleGetTunnelStatus } from './get-tunnel-status';
+import { handleStartTunnel } from './start-tunnel';
+import { handleStopTunnel } from './stop-tunnel';
+
+const SUPPORTED_OPS = ['start', 'stop', 'status'] as const;
+
+function pickRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function resolveDispatch(options: Record<string, unknown> | undefined): {
+  action: string | null;
+  subOptions: Record<string, unknown>;
+} {
+  if (!options) {
+    return { action: null, subOptions: {} };
+  }
+  const nested = pickRecord(options.parameters);
+  const actionSource = nested ?? options;
+  const rawAction = actionSource.action ?? actionSource.subaction ?? actionSource.op;
+  const action = typeof rawAction === 'string' ? rawAction.toLowerCase() : null;
+
+  let subOptions: Record<string, unknown>;
+  if (nested) {
+    const innerParams = pickRecord(nested.parameters);
+    if (innerParams) {
+      subOptions = { ...innerParams };
+    } else {
+      const {
+        action: _omitAction,
+        subaction: _omitSubaction,
+        op: _omitOp,
+        parameters: _omitParams,
+        ...rest
+      } = nested;
+      subOptions = rest;
+    }
+  } else {
+    const { action: _omitAction, subaction: _omitSubaction, op: _omitOp, ...rest } = options;
+    subOptions = rest;
+  }
+
+  return { action, subOptions };
+}
+
+export const tunnelAction: Action = {
+  name: 'TUNNEL',
+  similes: [
+    // Legacy action names kept so existing characters/transcripts still resolve.
+    'TAILSCALE',
+    'START_TAILSCALE',
+    'STOP_TAILSCALE',
+    'GET_TAILSCALE_STATUS',
+    'START_TUNNEL',
+    'OPEN_TUNNEL',
+    'CREATE_TUNNEL',
+    'TAILSCALE_UP',
+    'STOP_TUNNEL',
+    'CLOSE_TUNNEL',
+    'TAILSCALE_DOWN',
+    'TAILSCALE_STATUS',
+    'CHECK_TUNNEL',
+    'TUNNEL_INFO',
+    'TUNNEL_STATUS',
+  ],
+  description:
+    'Tunnel operations dispatched by `action`: start, stop, status. The `start` action accepts an optional `port` (defaults to 3000); `stop` and `status` take no parameters. Backed by whichever tunnel plugin is active (local Tailscale CLI, Eliza Cloud headscale, or ngrok).',
+
+  parameters: [
+    {
+      name: 'action',
+      description: 'Which tunnel sub-operation to run. One of: start, stop, status.',
+      required: true,
+      schema: {
+        type: 'string',
+        enum: [...SUPPORTED_OPS],
+      },
+    },
+    {
+      name: 'parameters',
+      description:
+        'Parameters forwarded to the selected sub-op. For `start`, optionally `{ port: number }`. `stop` and `status` take no parameters.',
+      required: false,
+      schema: { type: 'object' },
+    },
+  ],
+
+  validate: async (runtime: IAgentRuntime): Promise<boolean> => {
+    return Boolean(getTunnelService(runtime));
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    options?: Record<string, unknown>,
+    callback?: HandlerCallback
+  ): Promise<ActionResult> => {
+    const { action, subOptions } = resolveDispatch(options);
+
+    if (!action) {
+      const err = `TUNNEL requires action=start|stop|status`;
+      if (callback) await callback({ text: err });
+      return { success: false, error: err };
+    }
+
+    switch (action) {
+      case 'start':
+        return handleStartTunnel(runtime, message, state, subOptions, callback);
+      case 'stop':
+        return handleStopTunnel(runtime, message, state, subOptions, callback);
+      case 'status':
+        return handleGetTunnelStatus(runtime, message, state, subOptions, callback);
+      default: {
+        const err = `Unknown TUNNEL action "${action}". Supported: ${SUPPORTED_OPS.join(', ')}`;
+        if (callback) await callback({ text: err });
+        return { success: false, error: err };
+      }
+    }
+  },
+
+  examples: [
+    [
+      {
+        name: '{{user1}}',
+        content: { text: 'Start a tunnel on port 8080' },
+      },
+      {
+        name: '{{agentName}}',
+        content: {
+          text: 'Tunnel started (tailscale).\n\nURL: https://device.tail-scale.ts.net\nLocal port: 8080',
+          actions: ['TUNNEL'],
+        },
+      },
+    ],
+    [
+      {
+        name: '{{user1}}',
+        content: { text: 'Stop the tunnel' },
+      },
+      {
+        name: '{{agentName}}',
+        content: {
+          text: 'Tunnel stopped.',
+          actions: ['TUNNEL'],
+        },
+      },
+    ],
+    [
+      {
+        name: '{{user1}}',
+        content: { text: 'What is the tunnel status?' },
+      },
+      {
+        name: '{{agentName}}',
+        content: {
+          text: '✅ tunnel active (tailscale).',
+          actions: ['TUNNEL'],
+        },
+      },
+    ],
+  ],
+};
+
+export default tunnelAction;

package/src/environment.ts

@@ -0,0 +1,74 @@
+import type { IAgentRuntime } from '@elizaos/core';
+import { z } from 'zod';
+
+/**
+ * Local-CLI tunnel config. The cloud-backed (headscale) flavor lives in
+ * `@elizaos/plugin-elizacloud`; this package only configures the local
+ * `tailscale` CLI.
+ *
+ * `TUNNEL_*` env vars are the canonical names. `TAILSCALE_*` are accepted
+ * as aliases for one release window so existing `.env` files keep working.
+ */
+export const tunnelEnvSchema = z.object({
+  TUNNEL_TAGS: z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .transform((value) => {
+      if (Array.isArray(value)) return value.filter((tag) => tag.length > 0);
+      if (typeof value === 'string' && value.length > 0)
+        return value
+          .split(',')
+          .map((tag) => tag.trim())
+          .filter((tag) => tag.length > 0);
+      return ['tag:eliza-tunnel'];
+    })
+    .default(['tag:eliza-tunnel']),
+  TUNNEL_FUNNEL: z
+    .union([z.string(), z.boolean()])
+    .optional()
+    .transform((value) => value === true || value === 'true' || value === '1')
+    .default(false),
+  TUNNEL_DEFAULT_PORT: z
+    .union([z.string(), z.number()])
+    .optional()
+    .transform((value) => {
+      if (value === undefined || value === '') return 3000;
+      const num = typeof value === 'string' ? Number.parseInt(value, 10) : value;
+      if (Number.isNaN(num) || num <= 0 || num > 65535) return 3000;
+      return num;
+    })
+    .default(3000),
+});
+
+export type TunnelConfig = z.infer<typeof tunnelEnvSchema>;
+
+function readSetting(runtime: IAgentRuntime, key: string): string | undefined {
+  const value = runtime.getSetting(key);
+  if (value === null || value === undefined) return undefined;
+  return String(value);
+}
+
+/**
+ * Read `TUNNEL_<KEY>` first, then fall back to the legacy `TAILSCALE_<KEY>`.
+ */
+function readWithLegacy(
+  runtime: IAgentRuntime,
+  newKey: string,
+  legacyKey: string
+): string | undefined {
+  return (
+    readSetting(runtime, newKey) ??
+    readSetting(runtime, legacyKey) ??
+    process.env[newKey] ??
+    process.env[legacyKey]
+  );
+}
+
+export async function validateTunnelConfig(runtime: IAgentRuntime): Promise<TunnelConfig> {
+  const config = {
+    TUNNEL_TAGS: readWithLegacy(runtime, 'TUNNEL_TAGS', 'TAILSCALE_TAGS'),
+    TUNNEL_FUNNEL: readWithLegacy(runtime, 'TUNNEL_FUNNEL', 'TAILSCALE_FUNNEL'),
+    TUNNEL_DEFAULT_PORT: readWithLegacy(runtime, 'TUNNEL_DEFAULT_PORT', 'TAILSCALE_DEFAULT_PORT'),
+  };
+  return tunnelEnvSchema.parse(config);
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+import { elizaLogger, promoteSubactionsToActions, type Plugin } 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: Plugin = {
+  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 { type TunnelConfig, 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,
+  type ITunnelService,
+  type TunnelProvider,
+  type TunnelStatus,
+  tunnelSlotIsFree,
+} from './types';

package/src/providers/tunnel-state.ts

@@ -0,0 +1,46 @@
+import type { Provider } from '@elizaos/core';
+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: Provider = {
+  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;