@kortix/agent-tunnel 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { deriveSigningKey, generateToken, hashToken, signMessage, timingSafeStringEqual, verifyMessageSignature } from './shared/index.js';
+export { A as AgentInfo, a as AuthResult, H as HeartbeatConfig, J as JsonRpcError, b as JsonRpcErrorResponse, c as JsonRpcMessage, d as JsonRpcNotification, e as JsonRpcRequest, f as JsonRpcResponse, g as JsonRpcSuccessResponse, P as PendingRPC, R as RelayRpcOptions, S as SignedJsonRpcNotification, h as SignedJsonRpcRequest, T as TunnelAuthMessage, i as TunnelCapability, j as TunnelErrorCode, k as TunnelErrorCodeValue, l as TunnelMethod, m as TunnelMethods, n as TunnelRelayConfig, o as TunnelRelayEvents, p as TunnelRpcParams, q as TunnelServerConfig } from './types-Dpwrd8Ai.js';
+export { HeartbeatManager, TunnelRelay, TunnelRelayError, TunnelServer, WsHandlerOptions, WsHandlers, createTunnelRouter, createWsHandlers, startTunnelServer } from './server/index.js';
+export { AXElement, TunnelClient, TunnelClientConfig, TunnelClientError, TunnelToolDefinition, TunnelToolParameter, createTunnelTools } from './client/index.js';
+export { Capability, CapabilityRegistry, LocalPermission, PermissionGuard, RpcHandler, TunnelAgent, TunnelConfig, createDesktopCapability, createFilesystemCapability, createShellCapability, loadConfig, validateCommand, validatePath } from './agent/index.js';
+import 'events';
+import 'hono';

package/dist/index.js

@@ -0,0 +1,55 @@
+import {
+  deriveSigningKey,
+  signMessage,
+  verifyMessageSignature,
+  generateToken,
+  hashToken,
+  timingSafeStringEqual,
+  TunnelErrorCode,
+  TunnelMethods
+} from "./shared";
+import { TunnelRelay, TunnelRelayError } from "./server";
+import { HeartbeatManager } from "./server";
+import { createWsHandlers } from "./server";
+import { createTunnelRouter } from "./server";
+import { startTunnelServer } from "./server";
+import { TunnelClient, TunnelClientError } from "./client";
+import { createTunnelTools } from "./client";
+import { TunnelAgent } from "./agent";
+import { loadConfig } from "./agent";
+import { CapabilityRegistry } from "./agent";
+import { createFilesystemCapability } from "./agent";
+import { createShellCapability } from "./agent";
+import { createDesktopCapability } from "./agent";
+import { PermissionGuard } from "./agent";
+import { validateCommand } from "./agent";
+import { validatePath } from "./agent";
+export {
+  CapabilityRegistry,
+  HeartbeatManager,
+  PermissionGuard,
+  TunnelAgent,
+  TunnelClient,
+  TunnelClientError,
+  TunnelErrorCode,
+  TunnelMethods,
+  TunnelRelay,
+  TunnelRelayError,
+  createDesktopCapability,
+  createFilesystemCapability,
+  createShellCapability,
+  createTunnelRouter,
+  createTunnelTools,
+  createWsHandlers,
+  deriveSigningKey,
+  generateToken,
+  hashToken,
+  loadConfig,
+  signMessage,
+  startTunnelServer,
+  timingSafeStringEqual,
+  validateCommand,
+  validatePath,
+  verifyMessageSignature
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// ─── Shared: Types + Crypto ─────────────────────────────────────────────────\nexport {\n  deriveSigningKey,\n  signMessage,\n  verifyMessageSignature,\n  generateToken,\n  hashToken,\n  timingSafeStringEqual,\n  TunnelErrorCode,\n  TunnelMethods,\n} from './shared';\n\nexport type {\n  JsonRpcRequest,\n  JsonRpcSuccessResponse,\n  JsonRpcErrorResponse,\n  JsonRpcError,\n  JsonRpcResponse,\n  JsonRpcNotification,\n  JsonRpcMessage,\n  SignedJsonRpcRequest,\n  SignedJsonRpcNotification,\n  PendingRPC,\n  TunnelRpcParams,\n  RelayRpcOptions,\n  AgentInfo,\n  TunnelRelayEvents,\n  TunnelRelayConfig,\n  HeartbeatConfig,\n  TunnelServerConfig,\n  TunnelAuthMessage,\n  AuthResult,\n  TunnelCapability,\n  TunnelMethod,\n  TunnelErrorCodeValue,\n} from './shared';\n\n// ─── Server: Relay ──────────────────────────────────────────────────────────\nexport { TunnelRelay, TunnelRelayError } from './server';\nexport { HeartbeatManager } from './server';\nexport { createWsHandlers } from './server';\nexport type { WsHandlers, WsHandlerOptions } from './server';\nexport { createTunnelRouter } from './server';\nexport { startTunnelServer } from './server';\nexport type { TunnelServer } from './server';\n\n// ─── Client: SDK ────────────────────────────────────────────────────────────\nexport { TunnelClient, TunnelClientError } from './client';\nexport type { TunnelClientConfig, AXElement } from './client';\nexport { createTunnelTools } from './client';\nexport type { TunnelToolDefinition, TunnelToolParameter } from './client';\n\n// ─── Agent: Local Machine ───────────────────────────────────────────────────\nexport { TunnelAgent } from './agent';\nexport { loadConfig, type TunnelConfig } from './agent';\nexport { CapabilityRegistry } from './agent';\nexport type { Capability, RpcHandler } from './agent';\nexport { createFilesystemCapability } from './agent';\nexport { createShellCapability } from './agent';\nexport { createDesktopCapability } from './agent';\nexport { PermissionGuard } from './agent';\nexport type { LocalPermission } from './agent';\nexport { validateCommand } from './agent';\nexport { validatePath } from './agent';\n"],"mappings":"AACA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA4BP,SAAS,aAAa,wBAAwB;AAC9C,SAAS,wBAAwB;AACjC,SAAS,wBAAwB;AAEjC,SAAS,0BAA0B;AACnC,SAAS,yBAAyB;AAIlC,SAAS,cAAc,yBAAyB;AAEhD,SAAS,yBAAyB;AAIlC,SAAS,mBAAmB;AAC5B,SAAS,kBAAqC;AAC9C,SAAS,0BAA0B;AAEnC,SAAS,kCAAkC;AAC3C,SAAS,6BAA6B;AACtC,SAAS,+BAA+B;AACxC,SAAS,uBAAuB;AAEhC,SAAS,uBAAuB;AAChC,SAAS,oBAAoB;","names":[]}

package/dist/server/index.d.ts

@@ -0,0 +1,89 @@
+import { EventEmitter } from 'events';
+import { n as TunnelRelayConfig, o as TunnelRelayEvents, A as AgentInfo, R as RelayRpcOptions, H as HeartbeatConfig, a as AuthResult, q as TunnelServerConfig } from '../types-Dpwrd8Ai.js';
+import { Hono } from 'hono';
+
+declare class TunnelRelay extends EventEmitter {
+    private agents;
+    private pendingRPCs;
+    private config;
+    onAuthorizeRPC?: (tunnelId: string, method: string, params: Record<string, unknown>) => Promise<boolean>;
+    constructor(config?: TunnelRelayConfig);
+    emitEvent<K extends keyof TunnelRelayEvents>(event: K, data: TunnelRelayEvents[K]): boolean;
+    registerAgent(tunnelId: string, ws: WebSocket, signingKey: string, metadata?: Record<string, unknown>): void;
+    unregisterAgent(tunnelId: string): void;
+    isConnected(tunnelId: string): boolean;
+    getConnectedCount(): number;
+    getConnectedAgents(): Map<string, AgentInfo>;
+    getAgentMetadata(tunnelId: string): Record<string, unknown> | undefined;
+    handleAgentMessage(tunnelId: string, raw: string | Buffer): void;
+    relayRPC(tunnelId: string, method: string, params: Record<string, unknown>, options?: RelayRpcOptions): Promise<unknown>;
+    sendNotification(tunnelId: string, method: string, params?: Record<string, unknown>): boolean;
+    shutdown(): void;
+}
+declare class TunnelRelayError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+
+declare class HeartbeatManager {
+    private states;
+    private intervalHandle;
+    private relay;
+    private intervalMs;
+    private maxMissed;
+    constructor(relay: TunnelRelay, config?: HeartbeatConfig);
+    start(): void;
+    stop(): void;
+    register(tunnelId: string): void;
+    unregister(tunnelId: string): void;
+    recordPong(tunnelId: string): void;
+    private tick;
+}
+
+interface WsHandlerOptions {
+    heartbeat?: HeartbeatManager;
+    maxMessageSize?: number;
+    onAuthenticate?: (tunnelId: string, token: string) => Promise<AuthResult | null>;
+    authTimeoutMs?: number;
+}
+interface WsHandlers {
+    onOpen(tunnelId: string, ws: WebSocket): void;
+    onMessage(tunnelId: string, message: string | Buffer): void;
+    onClose(tunnelId: string): void;
+}
+declare function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): WsHandlers;
+
+declare function createTunnelRouter(relay: TunnelRelay, onAuthorizeHTTP?: (req: Request) => Promise<boolean>): Hono;
+
+/**
+ * Standalone tunnel server — one function call to get a working relay.
+ *
+ * Usage:
+ *   import { startTunnelServer } from 'agent-tunnel';
+ *   const server = startTunnelServer({ port: 8080, onAuthenticate: ... });
+ *
+ * Agents connect via: ws://localhost:8080/ws?tunnelId=yyy
+ * Then send { type: "auth", token: "tnl_xxx" } as the first message.
+ * Your app calls relay.relayRPC(tunnelId, method, params) to reach the agent.
+ */
+
+interface TunnelServer {
+    app: Hono;
+    relay: TunnelRelay;
+    heartbeat: HeartbeatManager;
+    wsHandlers: ReturnType<typeof createWsHandlers>;
+    stop: () => void;
+}
+/**
+ * Start a tunnel relay server. Handles everything:
+ * - HTTP routes for connections list + RPC
+ * - WebSocket upgrades on /ws for agent connections
+ * - Heartbeat ping/pong
+ * - HMAC signing key derivation via onAuthenticate hook
+ *
+ * Requires Bun runtime for WebSocket server support.
+ */
+declare function startTunnelServer(config?: TunnelServerConfig): TunnelServer;
+
+export { HeartbeatManager, TunnelRelay, TunnelRelayError, type TunnelServer, type WsHandlerOptions, type WsHandlers, createTunnelRouter, createWsHandlers, startTunnelServer };

package/dist/server/index.js

@@ -0,0 +1,14 @@
+import { TunnelRelay, TunnelRelayError } from "./relay";
+import { HeartbeatManager } from "./heartbeat";
+import { createWsHandlers } from "./ws-handler";
+import { createTunnelRouter } from "./routes";
+import { startTunnelServer } from "./server";
+export {
+  HeartbeatManager,
+  TunnelRelay,
+  TunnelRelayError,
+  createTunnelRouter,
+  createWsHandlers,
+  startTunnelServer
+};
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/index.ts"],"sourcesContent":["export { TunnelRelay, TunnelRelayError } from './relay';\nexport { HeartbeatManager } from './heartbeat';\nexport { createWsHandlers } from './ws-handler';\nexport type { WsHandlers, WsHandlerOptions } from './ws-handler';\nexport { createTunnelRouter } from './routes';\nexport { startTunnelServer } from './server';\nexport type { TunnelServer } from './server';\n"],"mappings":"AAAA,SAAS,aAAa,wBAAwB;AAC9C,SAAS,wBAAwB;AACjC,SAAS,wBAAwB;AAEjC,SAAS,0BAA0B;AACnC,SAAS,yBAAyB;","names":[]}

package/dist/shared/index.d.ts

@@ -0,0 +1,10 @@
+export { A as AgentInfo, a as AuthResult, H as HeartbeatConfig, J as JsonRpcError, b as JsonRpcErrorResponse, c as JsonRpcMessage, d as JsonRpcNotification, e as JsonRpcRequest, f as JsonRpcResponse, g as JsonRpcSuccessResponse, P as PendingRPC, R as RelayRpcOptions, S as SignedJsonRpcNotification, h as SignedJsonRpcRequest, T as TunnelAuthMessage, i as TunnelCapability, j as TunnelErrorCode, k as TunnelErrorCodeValue, l as TunnelMethod, m as TunnelMethods, n as TunnelRelayConfig, o as TunnelRelayEvents, p as TunnelRpcParams, q as TunnelServerConfig } from '../types-Dpwrd8Ai.js';
+
+declare function deriveSigningKey(token: string, secret: string): string;
+declare function signMessage(signingKey: string, payload: string, nonce: number): string;
+declare function verifyMessageSignature(signingKey: string, payload: string, nonce: number, signature: string): boolean;
+declare function generateToken(prefix?: string): string;
+declare function hashToken(token: string, secret: string): string;
+declare function timingSafeStringEqual(a: string, b: string): boolean;
+
+export { deriveSigningKey, generateToken, hashToken, signMessage, timingSafeStringEqual, verifyMessageSignature };

package/dist/shared/index.js

@@ -0,0 +1,20 @@
+import {
+  deriveSigningKey,
+  signMessage,
+  verifyMessageSignature,
+  generateToken,
+  hashToken,
+  timingSafeStringEqual
+} from "./crypto";
+import { TunnelErrorCode, TunnelMethods } from "./types";
+export {
+  TunnelErrorCode,
+  TunnelMethods,
+  deriveSigningKey,
+  generateToken,
+  hashToken,
+  signMessage,
+  timingSafeStringEqual,
+  verifyMessageSignature
+};
+//# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/index.ts"],"sourcesContent":["export {\n  deriveSigningKey,\n  signMessage,\n  verifyMessageSignature,\n  generateToken,\n  hashToken,\n  timingSafeStringEqual,\n} from './crypto';\n\nexport type {\n  JsonRpcRequest,\n  JsonRpcSuccessResponse,\n  JsonRpcErrorResponse,\n  JsonRpcError,\n  JsonRpcResponse,\n  JsonRpcNotification,\n  JsonRpcMessage,\n  SignedJsonRpcRequest,\n  SignedJsonRpcNotification,\n  PendingRPC,\n  TunnelRpcParams,\n  RelayRpcOptions,\n  AgentInfo,\n  TunnelRelayEvents,\n  TunnelRelayConfig,\n  HeartbeatConfig,\n  TunnelServerConfig,\n  TunnelAuthMessage,\n  AuthResult,\n  TunnelCapability,\n  TunnelMethod,\n  TunnelErrorCodeValue,\n} from './types';\n\nexport { TunnelErrorCode, TunnelMethods } from './types';\n"],"mappings":"AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA2BP,SAAS,iBAAiB,qBAAqB;","names":[]}

package/dist/types-Dpwrd8Ai.d.ts

@@ -0,0 +1,194 @@
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcSuccessResponse {
+    jsonrpc: '2.0';
+    id: string;
+    result: unknown;
+}
+interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: string;
+    error: JsonRpcError;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+}
+type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+declare const TunnelErrorCode: {
+    readonly PERMISSION_DENIED: -32000;
+    readonly CAPABILITY_NOT_REGISTERED: -32001;
+    readonly TIMEOUT: -32002;
+    readonly LOCAL_ERROR: -32003;
+    readonly NOT_CONNECTED: -32004;
+    readonly EXPIRED: -32005;
+    readonly RATE_LIMITED: -32006;
+    readonly AUTH_FAILED: -32007;
+};
+type TunnelErrorCodeValue = (typeof TunnelErrorCode)[keyof typeof TunnelErrorCode];
+type TunnelCapability = 'filesystem' | 'shell' | 'network' | 'apps' | 'hardware' | 'desktop' | 'gpu';
+declare const TunnelMethods: {
+    readonly 'fs.read': "filesystem";
+    readonly 'fs.write': "filesystem";
+    readonly 'fs.list': "filesystem";
+    readonly 'fs.stat': "filesystem";
+    readonly 'fs.delete': "filesystem";
+    readonly 'shell.exec': "shell";
+    readonly 'desktop.screenshot': "desktop";
+    readonly 'desktop.mouse.click': "desktop";
+    readonly 'desktop.mouse.move': "desktop";
+    readonly 'desktop.mouse.drag': "desktop";
+    readonly 'desktop.mouse.scroll': "desktop";
+    readonly 'desktop.mouse.position': "desktop";
+    readonly 'desktop.keyboard.type': "desktop";
+    readonly 'desktop.keyboard.key': "desktop";
+    readonly 'desktop.window.list': "desktop";
+    readonly 'desktop.window.focus': "desktop";
+    readonly 'desktop.window.resize': "desktop";
+    readonly 'desktop.window.close': "desktop";
+    readonly 'desktop.window.minimize': "desktop";
+    readonly 'desktop.app.launch': "desktop";
+    readonly 'desktop.app.quit': "desktop";
+    readonly 'desktop.app.list': "desktop";
+    readonly 'desktop.clipboard.read': "desktop";
+    readonly 'desktop.clipboard.write': "desktop";
+    readonly 'desktop.screen.info': "desktop";
+    readonly 'desktop.cursor.image': "desktop";
+    readonly 'desktop.ax.tree': "desktop";
+    readonly 'desktop.ax.action': "desktop";
+    readonly 'desktop.ax.set_value': "desktop";
+    readonly 'desktop.ax.focus': "desktop";
+    readonly 'desktop.ax.search': "desktop";
+    readonly 'net.request': "network";
+    readonly 'net.port_forward.start': "network";
+    readonly 'net.port_forward.stop': "network";
+    readonly 'tunnel.ping': null;
+    readonly 'tunnel.pong': null;
+    readonly 'tunnel.permission.revoked': null;
+    readonly 'tunnel.permissions.sync': null;
+    readonly 'tunnel.token.rotated': null;
+};
+type TunnelMethod = keyof typeof TunnelMethods;
+interface PendingRPC {
+    resolve: (value: unknown) => void;
+    reject: (error: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+    method: string;
+    tunnelId: string;
+    startedAt: number;
+}
+interface SignedJsonRpcRequest extends JsonRpcRequest {
+    _sig: string;
+    _nonce: number;
+}
+interface SignedJsonRpcNotification extends JsonRpcNotification {
+    _sig: string;
+    _nonce: number;
+}
+interface TunnelRpcParams {
+    capability: TunnelCapability;
+    operation: string;
+    args: Record<string, unknown>;
+    permissionId?: string;
+}
+interface RelayRpcOptions {
+    timeoutMs?: number;
+}
+/** Public agent info — does NOT expose signing key. */
+interface AgentInfo {
+    tunnelId: string;
+    connectedAt: number;
+    metadata?: Record<string, unknown>;
+}
+interface TunnelRelayEvents {
+    'agent:connect': {
+        tunnelId: string;
+        metadata?: Record<string, unknown>;
+    };
+    'agent:disconnect': {
+        tunnelId: string;
+    };
+    'agent:timeout': {
+        tunnelId: string;
+    };
+    'rpc:request': {
+        tunnelId: string;
+        method: string;
+        requestId: string;
+    };
+    'rpc:response': {
+        tunnelId: string;
+        method: string;
+        requestId: string;
+        durationMs: number;
+    };
+    'rpc:error': {
+        tunnelId: string;
+        method: string;
+        requestId: string;
+        error: Error;
+    };
+    'connection:replaced': {
+        tunnelId: string;
+    };
+    'message:pong': {
+        tunnelId: string;
+        params?: Record<string, unknown>;
+    };
+    'message:raw': {
+        tunnelId: string;
+        message: unknown;
+    };
+}
+interface TunnelRelayConfig {
+    rpcTimeoutMs?: number;
+    maxWsMessageSize?: number;
+}
+interface HeartbeatConfig {
+    intervalMs?: number;
+    maxMissed?: number;
+}
+/** Auth handshake message sent by agent as first WS message. */
+interface TunnelAuthMessage {
+    type: 'auth';
+    token: string;
+}
+/** Result returned by onAuthenticate hook on success. */
+interface AuthResult {
+    signingKey: string;
+    metadata?: Record<string, unknown>;
+}
+interface TunnelServerConfig {
+    port?: number;
+    relay?: TunnelRelayConfig;
+    heartbeat?: HeartbeatConfig;
+    /**
+     * Called when an agent sends its auth handshake.
+     * Return { signingKey, metadata } to accept, or null to reject.
+     * If not provided, all connections are rejected.
+     */
+    onAuthenticate?: (tunnelId: string, token: string) => Promise<AuthResult | null>;
+    /**
+     * Called before relaying an RPC to the agent.
+     * Return false to deny. If not provided, all RPCs are allowed.
+     */
+    onAuthorizeRPC?: (tunnelId: string, method: string, params: Record<string, unknown>) => Promise<boolean>;
+    /**
+     * Called before handling HTTP requests to relay routes (/connections, /rpc).
+     * Return false to deny. If not provided, routes are open.
+     */
+    onAuthorizeHTTP?: (req: Request) => Promise<boolean>;
+}
+
+export { type AgentInfo as A, type HeartbeatConfig as H, type JsonRpcError as J, type PendingRPC as P, type RelayRpcOptions as R, type SignedJsonRpcNotification as S, type TunnelAuthMessage as T, type AuthResult as a, type JsonRpcErrorResponse as b, type JsonRpcMessage as c, type JsonRpcNotification as d, type JsonRpcRequest as e, type JsonRpcResponse as f, type JsonRpcSuccessResponse as g, type SignedJsonRpcRequest as h, type TunnelCapability as i, TunnelErrorCode as j, type TunnelErrorCodeValue as k, type TunnelMethod as l, TunnelMethods as m, type TunnelRelayConfig as n, type TunnelRelayEvents as o, type TunnelRpcParams as p, type TunnelServerConfig as q };

package/package.json

@@ -1,34 +1,54 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Tunnel relay between cloud AI agents and local machines — server relay, local agent, client SDK, JSON-RPC, HMAC signing",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./shared": "./src/shared/index.ts",
-    "./server": "./src/server/index.ts",
-    "./client": "./src/client/index.ts",
-    "./client/cli": "./src/client/cli.ts",
-    "./agent": "./src/agent/index.ts"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./shared": {
+      "import": "./dist/shared/index.js",
+      "types": "./dist/shared/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server/index.js",
+      "types": "./dist/server/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client/index.js",
+      "types": "./dist/client/index.d.ts"
+    },
+    "./agent": {
+      "import": "./dist/agent/index.js",
+      "types": "./dist/agent/index.d.ts"
+    }
   },
   "bin": {
-    "agent-tunnel": "src/agent/cli.ts",
-    "agent-tunnel-cli": "src/client/cli.ts"
+    "agent-tunnel": "dist/agent-cli.js",
+    "agent-tunnel-cli": "dist/client-cli.js"
   },
   "files": [
+    "dist/",
     "src/"
   ],
   "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "hono": "^4.4.0"
+    "hono": "^4.4.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",
+    "@types/ws": "^8.5.13",
+    "tsup": "^8.4.0",
     "typescript": "^5.4.0"
   },
   "keywords": ["tunnel", "relay", "websocket", "json-rpc", "hmac", "agent", "sdk"],

package/src/agent/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+import '../node-ws-polyfill';
 import { loadConfig, type TunnelConfig } from './config';
 import { TunnelAgent } from './agent';
 import { CapabilityRegistry } from './capabilities/index';

package/src/client/cli.ts

@@ -1,8 +1,7 @@
-#!/usr/bin/env bun
 /**
  * Agent Tunnel CLI — interact with the user's local machine via Agent Tunnel.
  *
- * Usage: bun run cli.ts <command> [args as JSON]
+ * Usage: agent-tunnel-cli <command> [args as JSON]
  *
  * Commands:
  *   status                                          — list all tunnel connections
@@ -58,7 +57,9 @@ const FALLBACK_API_URL = "http://localhost:8008";
 function getApiBase(): string {
   const raw = getEnv("TUNNEL_API_URL") || FALLBACK_API_URL;
   const url = raw.startsWith("http") ? raw : FALLBACK_API_URL;
-  return url.replace(/\/+$/, "");
+  // Strip /v1/router suffix — TUNNEL_API_URL sometimes includes the router path
+  // but the CLI appends its own /v1/tunnel path.
+  return url.replace(/\/+$/, "").replace(/\/v1\/router\/?$/, "");
 }
 
 const client = new TunnelClient({
@@ -619,7 +620,7 @@ const [cmd, rawArgs] = process.argv.slice(2);
 
 if (!cmd) {
   console.error(
-    `Usage: bun run cli.ts <command> [args as JSON]\n\nAvailable: ${ALL_COMMANDS.join(" | ")}`
+    `Usage: agent-tunnel-cli <command> [args as JSON]\n\nAvailable: ${ALL_COMMANDS.join(" | ")}`
   );
   process.exit(1);
 }

package/src/node-ws-polyfill.ts

@@ -0,0 +1,17 @@
+/**
+ * WebSocket polyfill for Node.js < 22.
+ * If global WebSocket is already available (Node 22+, Bun, browsers), this is a no-op.
+ * Otherwise, it loads the `ws` package and assigns it to globalThis.WebSocket.
+ */
+if (typeof globalThis.WebSocket === 'undefined') {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const ws = require('ws');
+    globalThis.WebSocket = ws.default || ws;
+  } catch {
+    console.error(
+      '[agent-tunnel] WebSocket is not available. Install the "ws" package or use Node.js 22+.',
+    );
+    process.exit(1);
+  }
+}