@kortix/agent-tunnel 0.1.0

package/src/client/tunnel-client.ts

@@ -0,0 +1,270 @@
+export interface TunnelClientConfig {
+  apiUrl: string;
+  token: string;
+  tunnelId?: string;
+  cacheTtlMs?: number;
+}
+
+export class TunnelClientError extends Error {
+  constructor(
+    public readonly code: number,
+    message: string,
+    public readonly requestId?: string,
+    public readonly isPermissionRequest = false,
+  ) {
+    super(message);
+    this.name = 'TunnelClientError';
+  }
+}
+
+export class TunnelClient {
+  private apiUrl: string;
+  private token: string;
+  private explicitTunnelId: string | undefined;
+  private cachedTunnelId: string | null = null;
+  private cacheTimestamp = 0;
+  private cacheTtlMs: number;
+
+  readonly fs: FsNamespace;
+  readonly shell: ShellNamespace;
+  readonly desktop: DesktopNamespace;
+
+  constructor(config: TunnelClientConfig) {
+    this.apiUrl = config.apiUrl.replace(/\/+$/, '');
+    this.token = config.token;
+    this.explicitTunnelId = config.tunnelId;
+    this.cacheTtlMs = config.cacheTtlMs ?? 10_000;
+
+    this.fs = new FsNamespace(this);
+    this.shell = new ShellNamespace(this);
+    this.desktop = new DesktopNamespace(this);
+  }
+
+  async rpc(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    const tunnelId = await this.resolveTunnelId();
+
+    const res = await fetch(`${this.apiUrl}/rpc/${tunnelId}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+      },
+      body: JSON.stringify({ method, params }),
+    });
+
+    const data = (await res.json()) as Record<string, unknown>;
+
+    if (!res.ok) {
+      if (res.status === 404) this.cachedTunnelId = null;
+
+      throw new TunnelClientError(
+        (data.code as number) ?? -1,
+        (data.error as string) ?? `HTTP ${res.status}`,
+        data.requestId as string | undefined,
+        res.status === 403 && !!data.requestId,
+      );
+    }
+
+    return data.result;
+  }
+
+  async rpcWithPermissionFlow(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    try {
+      return await this.rpc(method, params);
+    } catch (err) {
+      if (err instanceof TunnelClientError && err.isPermissionRequest) {
+        return `Permission required. A permission request (${err.requestId}) has been sent to the user for approval. The user needs to approve this request before you can access their local machine. Please inform the user and try again after they approve.`;
+      }
+      throw err;
+    }
+  }
+
+  async getConnections(): Promise<Array<Record<string, unknown>>> {
+    const res = await fetch(`${this.apiUrl}/connections`, {
+      headers: {
+        ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+      },
+    });
+
+    if (!res.ok) {
+      throw new TunnelClientError(-1, `Failed to list connections: HTTP ${res.status}`);
+    }
+
+    return (await res.json()) as Array<Record<string, unknown>>;
+  }
+
+  async resolveTunnelId(): Promise<string> {
+    if (this.explicitTunnelId) return this.explicitTunnelId;
+
+    if (this.cachedTunnelId && (Date.now() - this.cacheTimestamp) < this.cacheTtlMs) {
+      return this.cachedTunnelId;
+    }
+
+    const res = await fetch(`${this.apiUrl}/connections`, {
+      headers: {
+        ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+      },
+    });
+
+    if (res.ok) {
+      const connections = (await res.json()) as Array<{ tunnelId: string; isLive?: boolean }>;
+      const online = connections.find((c) => c.isLive);
+      if (online) {
+        this.cachedTunnelId = online.tunnelId;
+        this.cacheTimestamp = Date.now();
+        return online.tunnelId;
+      }
+      if (connections.length > 0) {
+        this.cachedTunnelId = connections[0].tunnelId;
+        this.cacheTimestamp = Date.now();
+        return connections[0].tunnelId;
+      }
+    }
+
+    this.cachedTunnelId = null;
+    throw new TunnelClientError(
+      -1,
+      'No tunnel connection found. The user needs to set up Agent Tunnel first:\n' +
+      '1. Create a tunnel connection\n' +
+      '2. Run `npx @kortix/agent-tunnel connect` on their local machine',
+    );
+  }
+}
+
+class FsNamespace {
+  constructor(private client: TunnelClient) {}
+
+  async read(path: string, encoding = 'utf-8'): Promise<{ content: string; size: number; path: string }> {
+    return (await this.client.rpc('fs.read', { path, encoding })) as any;
+  }
+
+  async write(path: string, content: string, encoding = 'utf-8'): Promise<{ path: string; size: number }> {
+    return (await this.client.rpc('fs.write', { path, content, encoding })) as any;
+  }
+
+  async list(path: string, recursive = false): Promise<{ entries: Array<{ name: string; path: string; isDirectory: boolean; isFile: boolean }>; count: number }> {
+    return (await this.client.rpc('fs.list', { path, recursive })) as any;
+  }
+
+  async stat(path: string): Promise<Record<string, unknown>> {
+    return (await this.client.rpc('fs.stat', { path })) as any;
+  }
+
+  async delete(path: string): Promise<Record<string, unknown>> {
+    return (await this.client.rpc('fs.delete', { path })) as any;
+  }
+}
+
+class ShellNamespace {
+  constructor(private client: TunnelClient) {}
+
+  async exec(
+    command: string,
+    args: string[] = [],
+    options?: { cwd?: string; timeout?: number },
+  ): Promise<{ exitCode: number | null; signal: string | null; stdout: string; stderr: string; stdoutTruncated: boolean; stderrTruncated: boolean }> {
+    return (await this.client.rpc('shell.exec', {
+      command,
+      args,
+      cwd: options?.cwd,
+      timeout: options?.timeout,
+    })) as any;
+  }
+}
+
+class DesktopNamespace {
+  constructor(private client: TunnelClient) {}
+
+  async screenshot(params?: { region?: { x: number; y: number; width: number; height: number }; windowId?: number }): Promise<{ image: string; width: number; height: number; format?: string }> {
+    return (await this.client.rpc('desktop.screenshot', params ?? {})) as any;
+  }
+
+  async click(params: { x: number; y: number; button?: string; clicks?: number; modifiers?: string[] }): Promise<unknown> {
+    return this.client.rpc('desktop.mouse.click', params);
+  }
+
+  async type(text: string, delay?: number): Promise<unknown> {
+    return this.client.rpc('desktop.keyboard.type', { text, delay });
+  }
+
+  async key(keys: string[]): Promise<unknown> {
+    return this.client.rpc('desktop.keyboard.key', { keys });
+  }
+
+  async mouseMove(x: number, y: number): Promise<unknown> {
+    return this.client.rpc('desktop.mouse.move', { x, y });
+  }
+
+  async mouseDrag(fromX: number, fromY: number, toX: number, toY: number, button?: string): Promise<unknown> {
+    return this.client.rpc('desktop.mouse.drag', { fromX, fromY, toX, toY, button });
+  }
+
+  async mouseScroll(x: number, y: number, deltaX?: number, deltaY?: number): Promise<unknown> {
+    return this.client.rpc('desktop.mouse.scroll', { x, y, deltaX, deltaY });
+  }
+
+  async windowList(): Promise<{ windows: Array<{ id: number; app: string; title: string; bounds: { x: number; y: number; width: number; height: number }; minimized: boolean }> }> {
+    return (await this.client.rpc('desktop.window.list', {})) as any;
+  }
+
+  async windowFocus(windowId: number): Promise<unknown> {
+    return this.client.rpc('desktop.window.focus', { windowId });
+  }
+
+  async appLaunch(app: string): Promise<unknown> {
+    return this.client.rpc('desktop.app.launch', { app });
+  }
+
+  async appQuit(app: string): Promise<unknown> {
+    return this.client.rpc('desktop.app.quit', { app });
+  }
+
+  async clipboardRead(): Promise<{ text: string }> {
+    return (await this.client.rpc('desktop.clipboard.read', {})) as any;
+  }
+
+  async clipboardWrite(text: string): Promise<unknown> {
+    return this.client.rpc('desktop.clipboard.write', { text });
+  }
+
+  async screenInfo(): Promise<{ width: number; height: number; scaleFactor: number }> {
+    return (await this.client.rpc('desktop.screen.info', {})) as any;
+  }
+
+  async cursorImage(radius?: number): Promise<{ image: string; width: number; height: number; format?: string }> {
+    return (await this.client.rpc('desktop.cursor.image', { radius })) as any;
+  }
+
+  async axTree(params?: { pid?: number; maxDepth?: number; roles?: string[] }): Promise<{ root: AXElement; elementCount: number }> {
+    return (await this.client.rpc('desktop.ax.tree', params ?? {})) as any;
+  }
+
+  async axAction(elementId: string, action: string, pid?: number): Promise<Record<string, unknown>> {
+    return (await this.client.rpc('desktop.ax.action', { elementId, action, pid })) as any;
+  }
+
+  async axSetValue(elementId: string, value: string, pid?: number): Promise<Record<string, unknown>> {
+    return (await this.client.rpc('desktop.ax.set_value', { elementId, value, pid })) as any;
+  }
+
+  async axFocus(elementId: string, pid?: number): Promise<Record<string, unknown>> {
+    return (await this.client.rpc('desktop.ax.focus', { elementId, pid })) as any;
+  }
+
+  async axSearch(query: string, params?: { role?: string; pid?: number; maxResults?: number }): Promise<{ elements: AXElement[] }> {
+    return (await this.client.rpc('desktop.ax.search', { query, ...params })) as any;
+  }
+}
+
+export interface AXElement {
+  id: string;
+  role: string;
+  title: string;
+  value: string;
+  description: string;
+  bounds: { x: number; y: number; width: number; height: number };
+  children: AXElement[];
+  actions: string[];
+  enabled: boolean;
+  focused: boolean;
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+// ─── Shared: Types + Crypto ─────────────────────────────────────────────────
+export {
+  deriveSigningKey,
+  signMessage,
+  verifyMessageSignature,
+  generateToken,
+  hashToken,
+  timingSafeStringEqual,
+  TunnelErrorCode,
+  TunnelMethods,
+} from './shared';
+
+export type {
+  JsonRpcRequest,
+  JsonRpcSuccessResponse,
+  JsonRpcErrorResponse,
+  JsonRpcError,
+  JsonRpcResponse,
+  JsonRpcNotification,
+  JsonRpcMessage,
+  SignedJsonRpcRequest,
+  SignedJsonRpcNotification,
+  PendingRPC,
+  TunnelRpcParams,
+  RelayRpcOptions,
+  AgentInfo,
+  TunnelRelayEvents,
+  TunnelRelayConfig,
+  HeartbeatConfig,
+  TunnelServerConfig,
+  TunnelCapability,
+  TunnelMethod,
+  TunnelErrorCodeValue,
+} from './shared';
+
+// ─── Server: Relay ──────────────────────────────────────────────────────────
+export { TunnelRelay, TunnelRelayError } from './server';
+export { HeartbeatManager } from './server';
+export { createWsHandlers } from './server';
+export type { WsHandlers, WsHandlerOptions } from './server';
+export { createTunnelRouter } from './server';
+export { startTunnelServer } from './server';
+export type { TunnelServer } from './server';
+
+// ─── Client: SDK ────────────────────────────────────────────────────────────
+export { TunnelClient, TunnelClientError } from './client';
+export type { TunnelClientConfig, AXElement } from './client';
+export { createTunnelTools } from './client';
+export type { TunnelToolDefinition, TunnelToolParameter } from './client';
+
+// ─── Agent: Local Machine ───────────────────────────────────────────────────
+export { TunnelAgent } from './agent';
+export { loadConfig, type TunnelConfig } from './agent';
+export { CapabilityRegistry } from './agent';
+export type { Capability, RpcHandler } from './agent';
+export { createFilesystemCapability } from './agent';
+export { createShellCapability } from './agent';
+export { createDesktopCapability } from './agent';
+export { PermissionGuard } from './agent';
+export type { LocalPermission } from './agent';
+export { validateCommand } from './agent';
+export { validatePath } from './agent';

package/src/server/heartbeat.ts

@@ -0,0 +1,84 @@
+import type { TunnelRelay } from './relay';
+import type { HeartbeatConfig } from '../shared/types';
+
+interface HeartbeatState {
+  missedPongs: number;
+  lastPongAt: number;
+}
+
+const DEFAULT_INTERVAL_MS = 30_000;
+const DEFAULT_MAX_MISSED = 3;
+
+export class HeartbeatManager {
+  private states = new Map<string, HeartbeatState>();
+  private intervalHandle: ReturnType<typeof setInterval> | null = null;
+  private relay: TunnelRelay;
+  private intervalMs: number;
+  private maxMissed: number;
+
+  constructor(relay: TunnelRelay, config?: HeartbeatConfig) {
+    this.relay = relay;
+    this.intervalMs = config?.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.maxMissed = config?.maxMissed ?? DEFAULT_MAX_MISSED;
+  }
+
+  start(): void {
+    if (this.intervalHandle) return;
+
+    this.intervalHandle = setInterval(
+      () => this.tick(),
+      this.intervalMs,
+    );
+
+    console.log(`[tunnel-heartbeat] Started (interval: ${this.intervalMs}ms, max missed: ${this.maxMissed})`);
+  }
+
+  stop(): void {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = null;
+    }
+    this.states.clear();
+    console.log('[tunnel-heartbeat] Stopped');
+  }
+
+  register(tunnelId: string): void {
+    this.states.set(tunnelId, {
+      missedPongs: 0,
+      lastPongAt: Date.now(),
+    });
+  }
+
+  unregister(tunnelId: string): void {
+    this.states.delete(tunnelId);
+  }
+
+  recordPong(tunnelId: string): void {
+    const state = this.states.get(tunnelId);
+    if (state) {
+      state.missedPongs = 0;
+      state.lastPongAt = Date.now();
+    }
+  }
+
+  private tick(): void {
+    for (const [tunnelId, state] of this.states) {
+      const sent = this.relay.sendNotification(tunnelId, 'tunnel.ping', {
+        timestamp: Date.now(),
+      });
+
+      if (!sent) {
+        this.states.delete(tunnelId);
+        continue;
+      }
+
+      state.missedPongs++;
+
+      if (state.missedPongs >= this.maxMissed) {
+        console.warn(`[tunnel-heartbeat] Agent ${tunnelId} missed ${state.missedPongs} pongs — timing out`);
+        this.relay.emitEvent('agent:timeout', { tunnelId });
+        this.states.delete(tunnelId);
+      }
+    }
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,7 @@
+export { TunnelRelay, TunnelRelayError } from './relay';
+export { HeartbeatManager } from './heartbeat';
+export { createWsHandlers } from './ws-handler';
+export type { WsHandlers, WsHandlerOptions } from './ws-handler';
+export { createTunnelRouter } from './routes';
+export { startTunnelServer } from './server';
+export type { TunnelServer } from './server';

package/src/server/relay.ts

@@ -0,0 +1,266 @@
+import { EventEmitter } from 'events';
+import { signMessage } from '../shared/crypto';
+import {
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  type JsonRpcNotification,
+  type PendingRPC,
+  type RelayRpcOptions,
+  type AgentInfo,
+  type TunnelRelayConfig,
+  type TunnelRelayEvents,
+  TunnelErrorCode,
+} from '../shared/types';
+
+interface AgentConnection {
+  ws: WebSocket;
+  signingKey: string;
+  nonce: number;
+  connectedAt: number;
+  metadata?: Record<string, unknown>;
+}
+
+const DEFAULT_RPC_TIMEOUT_MS = 30_000;
+
+export class TunnelRelay extends EventEmitter {
+  private agents = new Map<string, AgentConnection>();
+  private pendingRPCs = new Map<string, PendingRPC>();
+  private config: Required<TunnelRelayConfig>;
+
+  constructor(config?: TunnelRelayConfig) {
+    super();
+    this.config = {
+      rpcTimeoutMs: config?.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+      maxWsMessageSize: config?.maxWsMessageSize ?? 5 * 1024 * 1024,
+    };
+  }
+
+  emitEvent<K extends keyof TunnelRelayEvents>(event: K, data: TunnelRelayEvents[K]): boolean {
+    return this.emit(event, data);
+  }
+
+  registerAgent(
+    tunnelId: string,
+    ws: WebSocket,
+    signingKey: string,
+    metadata?: Record<string, unknown>,
+  ): void {
+    const existing = this.agents.get(tunnelId);
+    if (existing) {
+      try { existing.ws.close(1000, 'replaced by new connection'); } catch {}
+      this.emitEvent('connection:replaced', { tunnelId });
+    }
+
+    this.agents.set(tunnelId, { ws, signingKey, nonce: 0, connectedAt: Date.now(), metadata });
+    this.emitEvent('agent:connect', { tunnelId, metadata });
+    console.log(`[tunnel-relay] Agent registered: ${tunnelId} (total: ${this.agents.size})`);
+  }
+
+  unregisterAgent(tunnelId: string): void {
+    this.agents.delete(tunnelId);
+
+    for (const [requestId, pending] of this.pendingRPCs) {
+      if (pending.tunnelId === tunnelId) {
+        clearTimeout(pending.timer);
+        pending.reject(new TunnelRelayError(
+          TunnelErrorCode.NOT_CONNECTED,
+          'Agent disconnected while RPC was pending',
+        ));
+        this.pendingRPCs.delete(requestId);
+      }
+    }
+
+    this.emitEvent('agent:disconnect', { tunnelId });
+    console.log(`[tunnel-relay] Agent unregistered: ${tunnelId} (total: ${this.agents.size})`);
+  }
+
+  isConnected(tunnelId: string): boolean {
+    return this.agents.has(tunnelId);
+  }
+
+  getConnectedCount(): number {
+    return this.agents.size;
+  }
+
+  getConnectedAgents(): Map<string, AgentInfo> {
+    const result = new Map<string, AgentInfo>();
+    for (const [tunnelId, conn] of this.agents) {
+      result.set(tunnelId, {
+        tunnelId,
+        signingKey: conn.signingKey,
+        connectedAt: conn.connectedAt,
+        metadata: conn.metadata,
+      });
+    }
+    return result;
+  }
+
+  getAgentMetadata(tunnelId: string): Record<string, unknown> | undefined {
+    return this.agents.get(tunnelId)?.metadata;
+  }
+
+  handleAgentMessage(tunnelId: string, raw: string | Buffer): void {
+    let msg: JsonRpcResponse;
+    try {
+      msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf-8'));
+    } catch {
+      console.warn(`[tunnel-relay] Invalid JSON from agent ${tunnelId}`);
+      return;
+    }
+
+    if ('method' in msg && (msg as any).method === 'tunnel.pong') {
+      this.emitEvent('message:pong', { tunnelId, params: (msg as any).params });
+      return;
+    }
+
+    if (!('id' in msg) || !msg.id) {
+      this.emitEvent('message:raw', { tunnelId, message: msg });
+      return;
+    }
+
+    const pending = this.pendingRPCs.get(msg.id);
+    if (!pending) {
+      return;
+    }
+
+    clearTimeout(pending.timer);
+    this.pendingRPCs.delete(msg.id);
+
+    const durationMs = Date.now() - pending.startedAt;
+
+    if ('error' in msg && msg.error) {
+      const error = new TunnelRelayError(msg.error.code, msg.error.message, msg.error.data);
+      this.emitEvent('rpc:error', {
+        tunnelId,
+        method: pending.method,
+        requestId: msg.id,
+        error,
+      });
+      pending.reject(error);
+    } else {
+      this.emitEvent('rpc:response', {
+        tunnelId,
+        method: pending.method,
+        requestId: msg.id,
+        durationMs,
+      });
+      pending.resolve((msg as any).result);
+    }
+  }
+
+  async relayRPC(
+    tunnelId: string,
+    method: string,
+    params: Record<string, unknown>,
+    options?: RelayRpcOptions,
+  ): Promise<unknown> {
+    const agent = this.agents.get(tunnelId);
+    if (!agent) {
+      throw new TunnelRelayError(
+        TunnelErrorCode.NOT_CONNECTED,
+        `Tunnel agent ${tunnelId} is not connected`,
+      );
+    }
+
+    const requestId = crypto.randomUUID();
+    const timeoutMs = options?.timeoutMs ?? this.config.rpcTimeoutMs;
+
+    const request: JsonRpcRequest = {
+      jsonrpc: '2.0',
+      id: requestId,
+      method,
+      params,
+    };
+
+    const nonce = ++agent.nonce;
+    const payload = JSON.stringify(request);
+    const sig = signMessage(agent.signingKey, payload, nonce);
+    const signedRequest = { ...request, _sig: sig, _nonce: nonce };
+
+    this.emitEvent('rpc:request', { tunnelId, method, requestId });
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRPCs.delete(requestId);
+        const error = new TunnelRelayError(
+          TunnelErrorCode.TIMEOUT,
+          `RPC timeout after ${timeoutMs}ms for ${method}`,
+        );
+        this.emitEvent('rpc:error', { tunnelId, method, requestId, error });
+        reject(error);
+      }, timeoutMs);
+
+      this.pendingRPCs.set(requestId, {
+        resolve,
+        reject,
+        timer,
+        method,
+        tunnelId,
+        startedAt: Date.now(),
+      });
+
+      try {
+        agent.ws.send(JSON.stringify(signedRequest));
+      } catch (err) {
+        clearTimeout(timer);
+        this.pendingRPCs.delete(requestId);
+        reject(new TunnelRelayError(
+          TunnelErrorCode.NOT_CONNECTED,
+          `Failed to send RPC to agent: ${err}`,
+        ));
+      }
+    });
+  }
+
+  sendNotification(tunnelId: string, method: string, params?: Record<string, unknown>): boolean {
+    const agent = this.agents.get(tunnelId);
+    if (!agent) return false;
+
+    const notification: JsonRpcNotification = {
+      jsonrpc: '2.0',
+      method,
+      params,
+    };
+
+    const nonce = ++agent.nonce;
+    const payload = JSON.stringify(notification);
+    const sig = signMessage(agent.signingKey, payload, nonce);
+    const signedNotification = { ...notification, _sig: sig, _nonce: nonce };
+
+    try {
+      agent.ws.send(JSON.stringify(signedNotification));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  shutdown(): void {
+    for (const [_requestId, pending] of this.pendingRPCs) {
+      clearTimeout(pending.timer);
+      pending.reject(new TunnelRelayError(
+        TunnelErrorCode.NOT_CONNECTED,
+        'Tunnel relay shutting down',
+      ));
+    }
+    this.pendingRPCs.clear();
+
+    for (const [_tunnelId, agent] of this.agents) {
+      try { agent.ws.close(1001, 'server shutting down'); } catch {}
+    }
+    this.agents.clear();
+
+    console.log('[tunnel-relay] Shutdown complete');
+  }
+}
+
+export class TunnelRelayError extends Error {
+  constructor(
+    public readonly code: number,
+    message: string,
+    public readonly data?: unknown,
+  ) {
+    super(message);
+    this.name = 'TunnelRelayError';
+  }
+}