pinggy 0.4.9 → 0.5.1

package/dist/index.d.cts

@@ -82,16 +82,19 @@ interface RemoteManagementState {
  * @singleton
  */
 
+type TunnelOrigin = "app" | "cli" | "remote";
 interface ManagedTunnel {
     tunnelid: string;
     configId: string;
     tunnelName?: string;
+    origin: TunnelOrigin;
     instance: TunnelInstance;
     tunnelConfig?: TunnelConfigurationV1;
     serveWorker?: Worker | null;
     warnings?: Warning[];
     serve?: string;
     isStopped?: boolean;
+    isStopping?: boolean;
     createdAt?: string;
     startedAt?: string | null;
     stoppedAt?: string | null;
@@ -121,6 +124,7 @@ interface TunnelUpdateConfig extends TunnelConfigurationV1 {
     serve?: string;
 }
 type StatsListener = (tunnelId: string, stats: TunnelUsageType) => void;
+type StoppedListener = (tunnelId: string) => void;
 type ErrorListener = (tunnelId: string, errorMsg: string, isFatal: boolean) => void;
 type PollingErrorListener = (tunnelId: string, errorMsg: string) => void;
 type DisconnectListener = (tunnelId: string, error: string, messages: string[]) => void;
@@ -131,7 +135,7 @@ type ReconnectingListener = (tunnelId: string, retryCnt: number) => void;
 type ReconnectionCompletedListener = (tunnelId: string, urls: string[]) => void;
 type ReconnectionFailedListener = (tunnelId: string, retryCnt: number) => void;
 interface ITunnelManager {
-    createTunnel(config: TunnelCreationConfig, buildConfig?: boolean): Promise<ManagedTunnel>;
+    createTunnel(config: TunnelCreationConfig, origin?: TunnelOrigin): Promise<ManagedTunnel>;
     startTunnel(tunnelId: string): Promise<string[]>;
     stopTunnel(tunnelId: string): {
         configId: string;
@@ -152,12 +156,15 @@ interface ITunnelManager {
     registerStatsListener(tunnelId: string, listener: StatsListener): Promise<[string, string]>;
     registerErrorListener(tunnelId: string, listener: ErrorListener): Promise<string>;
     registerPollingErrorListener(tunnelId: string, listener: PollingErrorListener): Promise<string>;
-    registerWorkerErrorListner(tunnelId: string, listener: TunnelWorkerErrorListner): void;
+    registerWorkerErrorListner(tunnelId: string, listener: TunnelWorkerErrorListner): Promise<string>;
+    deregisterWorkerErrorListener(tunnelId: string, listenerId: string): void;
     registerStartListener(tunnelId: string, listener: StartListener): Promise<string>;
     deregisterErrorListener(tunnelId: string, listenerId: string): void;
     deregisterPollingErrorListener(tunnelId: string, listenerId: string): void;
     registerDisconnectListener(tunnelId: string, listener: DisconnectListener): Promise<string>;
     deregisterDisconnectListener(tunnelId: string, listenerId: string): void;
+    registerStoppedListener(tunnelId: string, listener: StoppedListener): Promise<string>;
+    deregisterStoppedListener(tunnelId: string, listenerId: string): void;
     deregisterStatsListener(tunnelId: string, listenerId: string): void;
     getLocalserverTlsInfo(tunnelId: string): Promise<string | boolean>;
     removeStoppedTunnelByTunnelId(tunnelId: string): boolean;
@@ -180,6 +187,7 @@ declare class TunnelManager implements ITunnelManager {
     private tunnelErrorListeners;
     private tunnelPollingErrorListeners;
     private tunnelDisconnectListeners;
+    private tunnelStoppedListeners;
     private tunnelWorkerErrorListeners;
     private tunnelStartListeners;
     private tunnelWillReconnectListeners;
@@ -200,7 +208,7 @@ declare class TunnelManager implements ITunnelManager {
      * @returns {ManagedTunnel} A new managed tunnel instance containing the tunnel details,
      *                          status information, and statistics
      */
-    createTunnel(config: TunnelCreationConfig): Promise<ManagedTunnel>;
+    createTunnel(config: TunnelCreationConfig, origin?: TunnelOrigin): Promise<ManagedTunnel>;
     /**
      * Internal method to create a tunnel with an already-processed configuration.
      * This is used by createTunnel, restartTunnel, and updateConfig to avoid config processing.
@@ -228,6 +236,7 @@ declare class TunnelManager implements ITunnelManager {
         configId: string;
         tunnelid: string;
     };
+    private notifyStoppedListeners;
     /**
      * Get all public URLs for a tunnel
      */
@@ -237,6 +246,17 @@ declare class TunnelManager implements ITunnelManager {
      * @returns An array of all TunnelStatus objects
      */
     getAllTunnels(): Promise<TunnelList[]>;
+    /**
+     * Re-apply the given log level to every live tunnel's worker JS logger.
+     * Native libpinggy level is fixed at worker init and cannot be re-pathed
+     * or re-levelled at runtime without restarting the tunnel.
+     */
+    applyLogLevelToActiveTunnels(level: string): void;
+    /**
+     * Tunnel IDs whose ManagedTunnel is currently alive (not stopped, no fatal error).
+     * Cheap, synchronous, suitable for hot paths like /logs/paths.
+     */
+    getActiveTunnelIds(): Set<string>;
     /**
      * Get status of a tunnel
      */
@@ -317,7 +337,8 @@ declare class TunnelManager implements ITunnelManager {
     registerErrorListener(tunnelId: string, listener: ErrorListener): Promise<string>;
     registerPollingErrorListener(tunnelId: string, listener: PollingErrorListener): Promise<string>;
     registerDisconnectListener(tunnelId: string, listener: DisconnectListener): Promise<string>;
-    registerWorkerErrorListner(tunnelId: string, listener: TunnelWorkerErrorListner): Promise<void>;
+    registerWorkerErrorListner(tunnelId: string, listener: TunnelWorkerErrorListner): Promise<string>;
+    deregisterWorkerErrorListener(tunnelId: string, listenerId: string): void;
     registerStartListener(tunnelId: string, listener: StartListener): Promise<string>;
     registerWillReconnectListener(tunnelId: string, listener: WillReconnectListener): Promise<string>;
     registerReconnectingListener(tunnelId: string, listener: ReconnectingListener): Promise<string>;
@@ -333,6 +354,8 @@ declare class TunnelManager implements ITunnelManager {
     deregisterErrorListener(tunnelId: string, listenerId: string): void;
     deregisterPollingErrorListener(tunnelId: string, listenerId: string): void;
     deregisterDisconnectListener(tunnelId: string, listenerId: string): void;
+    registerStoppedListener(tunnelId: string, listener: StoppedListener): Promise<string>;
+    deregisterStoppedListener(tunnelId: string, listenerId: string): void;
     deregisterWillReconnectListener(tunnelId: string, listenerId: string): void;
     deregisterReconnectingListener(tunnelId: string, listenerId: string): void;
     deregisterReconnectionCompletedListener(tunnelId: string, listenerId: string): void;
@@ -544,13 +567,13 @@ declare const TunnelConfigV1Schema: z.ZodObject<{
     forwarding: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodObject<{
         listenAddress: z.ZodOptional<z.ZodString>;
         address: z.ZodString;
-        type: z.ZodOptional<z.ZodEnum<{
+        type: z.ZodEnum<{
             http: TunnelType.Http;
             tcp: TunnelType.Tcp;
             tls: TunnelType.Tls;
             udp: TunnelType.Udp;
             tlstcp: TunnelType.TlsTcp;
-        }>>;
+        }>;
     }, z.core.$strip>>]>;
     ipWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
     basicAuth: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -577,6 +600,219 @@ declare const TunnelConfigV1Schema: z.ZodObject<{
 }, z.core.$strip>;
 type TunnelConfigV1 = z.infer<typeof TunnelConfigV1Schema>;
 
+/**
+ * Typed IPC route contract shared by IPCClient (caller) and IPCServer (handler).
+ * Each `Route` constant binds a `METHOD PATH` string used over the wire; the
+ * `IPCRoutes` map binds that same key to its request and response shapes.
+ *
+ * Adding a route: add an entry to `Route`, then a matching key in `IPCRoutes`.
+ * Both sides will fail to compile until the new handler is wired up.
+ */
+
+declare const Route: {
+    readonly Ping: "GET /ping";
+    readonly ListTunnels: "GET /tunnels";
+    readonly ListTunnelsV1: "GET /tunnels-v1";
+    readonly StartTunnel: "POST /tunnels/start";
+    readonly StartTunnelConfig: "POST /tunnels/start-config";
+    readonly StartTunnelV1: "POST /tunnels/start-v1";
+    readonly StopTunnel: "POST /tunnels/stop";
+    readonly RestartTunnel: "POST /tunnels/restart";
+    readonly UpdateConfig: "POST /tunnels/update-config";
+    readonly UpdateConfigV2: "POST /tunnels/update-config-v2";
+    readonly RemoveStopped: "POST /tunnels/remove-stopped";
+    readonly Shutdown: "POST /shutdown";
+    readonly GetLogLevel: "GET /loglevel";
+    readonly SetLogLevel: "POST /loglevel";
+    readonly GetTunnelLogging: "GET /config/tunnel-logging";
+    readonly SetTunnelLogging: "POST /config/tunnel-logging";
+    readonly GetLogPaths: "GET /logs/paths";
+};
+declare const ParamRoute: {
+    readonly GetTunnel: "GET /tunnels/:id";
+    readonly GetTunnelStats: "GET /tunnels/:id/stats";
+    readonly ResolveLogPath: "GET /logs/resolve";
+};
+interface PingResponse {
+    status: string;
+    pid: number;
+    uptime: number;
+}
+type ListTunnelsResponse = (TunnelResponseV2 & {
+    mode?: SessionMode;
+})[] | ErrorResponse;
+interface LogPathEntry {
+    tunnelId?: string;
+    name?: string;
+    origin: TunnelOrigin;
+    path: string;
+    mtime: number;
+    running: boolean;
+}
+interface LogPathsResponse {
+    daemon: string;
+    tunnels: LogPathEntry[];
+}
+type ResolveLogPathResponse = {
+    status: "running" | "historical";
+    path: string;
+    tunnelId?: string;
+    name?: string;
+    origin: TunnelOrigin;
+    running: boolean;
+} | {
+    status: "config-only";
+    name: string;
+    configId: string;
+} | {
+    status: "not-found";
+};
+interface ShutdownResponse {
+    status: string;
+    errors: string[];
+}
+type LogLevel = "debug" | "info" | "error";
+declare const SessionMode: {
+    readonly Foreground: "foreground";
+    readonly Detached: "detached";
+};
+type SessionMode = typeof SessionMode[keyof typeof SessionMode];
+type IPCRoutes = {
+    [Route.Ping]: {
+        req: void;
+        res: PingResponse;
+    };
+    [Route.ListTunnels]: {
+        req: void;
+        res: ListTunnelsResponse;
+    };
+    [Route.ListTunnelsV1]: {
+        req: void;
+        res: TunnelResponse[] | ErrorResponse;
+    };
+    [Route.StartTunnel]: {
+        req: {
+            name: string;
+            mode: SessionMode;
+        };
+        res: TunnelResponseV2 | ErrorResponse;
+    };
+    [Route.StartTunnelConfig]: {
+        req: {
+            config: TunnelConfigV1;
+            mode: SessionMode;
+            noWait?: boolean;
+        };
+        res: TunnelResponseV2 | ErrorResponse;
+    };
+    [Route.StartTunnelV1]: {
+        req: {
+            config: TunnelConfig;
+            mode: SessionMode;
+            noWait?: boolean;
+        };
+        res: TunnelResponse | ErrorResponse;
+    };
+    [Route.StopTunnel]: {
+        req: {
+            tunnelid: string;
+        };
+        res: TunnelResponse | ErrorResponse;
+    };
+    [Route.RestartTunnel]: {
+        req: {
+            tunnelid: string;
+        };
+        res: TunnelResponse | ErrorResponse;
+    };
+    [Route.UpdateConfig]: {
+        req: {
+            config: TunnelConfig;
+            noWait?: boolean;
+        };
+        res: TunnelResponse | ErrorResponse;
+    };
+    [Route.UpdateConfigV2]: {
+        req: {
+            config: TunnelConfigV1;
+            noWait?: boolean;
+        };
+        res: TunnelResponseV2 | ErrorResponse;
+    };
+    [Route.RemoveStopped]: {
+        req: {
+            tunnelid?: string;
+            configId?: string;
+        };
+        res: {
+            result: boolean | ErrorResponse;
+        };
+    };
+    [Route.Shutdown]: {
+        req: Record<string, never>;
+        res: ShutdownResponse;
+    };
+    [Route.GetLogLevel]: {
+        req: void;
+        res: {
+            level: LogLevel;
+        };
+    };
+    [Route.SetLogLevel]: {
+        req: {
+            level: LogLevel;
+        };
+        res: {
+            level: LogLevel;
+            appliedTo: string;
+        };
+    };
+    [Route.GetTunnelLogging]: {
+        req: void;
+        res: {
+            enabled: boolean;
+        };
+    };
+    [Route.SetTunnelLogging]: {
+        req: {
+            enabled: boolean;
+        };
+        res: {
+            enabled: boolean;
+        };
+    };
+    [Route.GetLogPaths]: {
+        req: void;
+        res: LogPathsResponse;
+    };
+};
+type RouteKey = keyof IPCRoutes;
+type RouteRes<K extends RouteKey> = IPCRoutes[K]["res"];
+/**
+ * Parameterized routes don't fit the static `METHOD PATH` key shape.
+ * Kept as a small parallel registry.
+ */
+type ParameterizedRoutes = {
+    [ParamRoute.GetTunnel]: {
+        params: {
+            tunnelId: string;
+        };
+        res: TunnelResponse | ErrorResponse;
+    };
+    [ParamRoute.GetTunnelStats]: {
+        params: {
+            tunnelId: string;
+        };
+        res: TunnelUsageType[] | ErrorResponse;
+    };
+    [ParamRoute.ResolveLogPath]: {
+        params: {
+            q: string;
+        };
+        res: ResolveLogPathResponse;
+    };
+};
+
 interface TunnelResponse {
     tunnelid: string;
     remoteurls: string[];
@@ -591,6 +827,7 @@ interface TunnelResponseV2 {
     status: Status;
     stats: TunnelUsageType;
     greetmsg?: string;
+    mode?: SessionMode;
 }
 interface TunnelHandler {
     handleStart(config: TunnelConfig, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
@@ -604,7 +841,7 @@ interface TunnelHandler {
     handleRestart(tunnelid: string, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
     handleRegisterStatsListener(tunnelid: string, listener: (tunnelId: string, stats: TunnelUsageType) => void): void;
     handleUnregisterStatsListener(tunnelid: string, listnerId: string): void;
-    handleGetTunnelStats(tunnelid: string): TunnelUsageType[] | ErrorResponse;
+    handleGetTunnelStats(tunnelid: string): Promise<TunnelUsageType[] | ErrorResponse>;
     handleRegisterDisconnectListener(tunnelid: string, listener: DisconnectListener): void;
     handleRemoveStoppedTunnelByTunnelId(tunnelId: string): boolean | ErrorResponse;
     handleRemoveStoppedTunnelByConfigId(configId: string): boolean | ErrorResponse;
@@ -618,8 +855,8 @@ declare class TunnelOperations implements TunnelHandler {
     private buildTunnelResponse;
     private buildTunnelResponseV2;
     private error;
-    handleStart(config: TunnelConfig, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
-    handleStartV2(config: TunnelConfigV1, noWait?: boolean): Promise<TunnelResponseV2 | ErrorResponse>;
+    handleStart(config: TunnelConfig, noWait?: boolean, origin?: TunnelOrigin): Promise<TunnelResponse | ErrorResponse>;
+    handleStartV2(config: TunnelConfigV1, noWait?: boolean, origin?: TunnelOrigin): Promise<TunnelResponseV2 | ErrorResponse>;
     handleUpdateConfig(config: TunnelConfig, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
     handleUpdateConfigV2(config: TunnelConfigV1, noWait?: boolean): Promise<TunnelResponseV2 | ErrorResponse>;
     handleListV2(): Promise<TunnelResponseV2[] | ErrorResponse>;
@@ -629,12 +866,235 @@ declare class TunnelOperations implements TunnelHandler {
     handleRestart(tunnelid: string, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
     handleRegisterStatsListener(tunnelid: string, listener: (tunnelId: string, stats: TunnelUsageType) => void): void;
     handleUnregisterStatsListener(tunnelid: string, listnerId: string): void;
-    handleGetTunnelStats(tunnelid: string): TunnelUsageType[] | ErrorResponse;
+    handleGetTunnelStats(tunnelid: string): Promise<TunnelUsageType[] | ErrorResponse>;
     handleRegisterDisconnectListener(tunnelid: string, listener: DisconnectListener): void;
     handleRemoveStoppedTunnelByConfigId(configId: string): boolean | ErrorResponse;
     handleRemoveStoppedTunnelByTunnelId(tunnelId: string): boolean | ErrorResponse;
 }
 
+type ClientOrigin = "app" | "cli" | "remote";
+declare class IPCClient {
+    private port;
+    private origin;
+    constructor(port: number, origin?: ClientOrigin);
+    ping(timeoutMs?: number): Promise<PingResponse>;
+    listTunnels(): Promise<RouteRes<typeof Route.ListTunnels>>;
+    getTunnel(tunnelId: string): Promise<ParameterizedRoutes[typeof ParamRoute.GetTunnel]["res"]>;
+    getTunnelStats(tunnelId: string): Promise<TunnelUsageType[] | ErrorResponse>;
+    startTunnel(name: string, mode: SessionMode): Promise<TunnelResponseV2 | ErrorResponse>;
+    startTunnelWithConfig(config: TunnelConfigV1, mode: SessionMode, noWait?: boolean): Promise<TunnelResponseV2 | ErrorResponse>;
+    stopTunnel(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
+    restartTunnel(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
+    startTunnelV1(config: TunnelConfig, mode: SessionMode, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
+    listTunnelsV1(): Promise<TunnelResponse[] | ErrorResponse>;
+    updateConfig(config: TunnelConfig, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
+    updateConfigV2(config: TunnelConfigV1, noWait?: boolean): Promise<TunnelResponseV2 | ErrorResponse>;
+    removeStoppedTunnel(opts: {
+        tunnelid?: string;
+        configId?: string;
+    }): Promise<{
+        result: boolean | ErrorResponse;
+    }>;
+    shutdown(): Promise<ShutdownResponse>;
+    getLogLevel(): Promise<{
+        level: LogLevel;
+    }>;
+    setLogLevel(level: LogLevel): Promise<{
+        level: LogLevel;
+        appliedTo: string;
+    }>;
+    getTunnelLogging(): Promise<{
+        enabled: boolean;
+    }>;
+    setTunnelLogging(enabled: boolean): Promise<{
+        enabled: boolean;
+    }>;
+    getLogPaths(): Promise<LogPathsResponse>;
+    resolveLogPath(q: string): Promise<ResolveLogPathResponse>;
+    /**
+     * Get the WebSocket URL for event streaming.
+     */
+    getWsUrl(): string;
+    getPort(): number;
+    private call;
+    private request;
+}
+
+type StatsCallback = (tunnelId: string, stats: TunnelUsageType) => void;
+type DisconnectCallback = (tunnelId: string, error: string, messages: string[]) => void;
+type ReconnectingCallback = (tunnelId: string, retryCnt: number) => void;
+type ReconnectedCallback = (tunnelId: string, urls: string[]) => void;
+type ReconnectionFailedCallback = (tunnelId: string, retryCnt: number) => void;
+type ErrorCallback = (tunnelId: string, message: string, isFatal: boolean) => void;
+type UrlReadyCallback = (tunnelId: string, urls: string[]) => void;
+type WorkerErrorCallback = (tunnelId: string, message: string) => void;
+type WillReconnectCallback = (tunnelId: string, error: string, messages: string[]) => void;
+type StoppedCallback = (tunnelId: string) => void;
+type SubscriptionMode = SessionMode;
+type SubscriptionInfo = {
+    mode: SubscriptionMode;
+};
+declare class WsStream {
+    private getWsUrl;
+    private ws;
+    private wsReady;
+    private wsResolve;
+    private subscribedTunnels;
+    private callbacks;
+    private openListeners;
+    private closeListeners;
+    constructor(getWsUrl: () => string);
+    ensureOpen(): Promise<void>;
+    /** Send a normal close (1000). Use for user-initiated shutdown. */
+    closeNormally(): void;
+    /** Hard kill the socket. Use when daemon is known dead. */
+    terminate(): void;
+    isOpen(): boolean;
+    subscribe(tunnelId: string, mode?: SubscriptionMode): Promise<void>;
+    /**
+     * Remove the local subscription. Sends an unsubscribe frame if the socket
+     * is still open; if not, the daemon cleans up server-side when the session
+     * closes. Returns true if the caller had this subscription.
+     */
+    unsubscribe(tunnelId: string): boolean;
+    hasSubscriptions(): boolean;
+    subscriptionCount(): number;
+    /** Snapshot of current subscriptions, for the reconnect path to replay. */
+    snapshotSubscriptions(): Array<[string, SubscriptionInfo]>;
+    /**
+     * Re-open the WS (fresh socket) and re-subscribe a previously captured set.
+     * Clears existing state first so ensureOpen builds a new connection.
+     */
+    restoreSubscriptions(snapshot: Array<[string, SubscriptionInfo]>): Promise<void>;
+    onOpen(cb: () => void): void;
+    onClose(cb: (code: number) => void): void;
+    onStats(cb: StatsCallback): void;
+    onDisconnect(cb: DisconnectCallback): void;
+    onReconnecting(cb: ReconnectingCallback): void;
+    onReconnected(cb: ReconnectedCallback): void;
+    onReconnectionFailed(cb: ReconnectionFailedCallback): void;
+    onError(cb: ErrorCallback): void;
+    onUrlReady(cb: UrlReadyCallback): void;
+    onWorkerError(cb: WorkerErrorCallback): void;
+    onWillReconnect(cb: WillReconnectCallback): void;
+    onStopped(cb: StoppedCallback): void;
+    private handleMessage;
+}
+
+/**
+ * DaemonHealth: monitors liveness of the daemon process and decides when
+ * to declare it lost. Two signals drive it:
+ *
+ *   1. WS abnormal close → triggers a short reconnect loop (3 × 1s).
+ *      During the loop we verify daemon.json still points to the same PID
+ *      we connected to; a PID change means the daemon was respawned and
+ *      the previous session is unrecoverable.
+ *   2. Heartbeat ping every 5s → after 2 consecutive failures the daemon
+ *      is treated as hung; no reconnect (it won't help).
+ *
+ * Subscriptions are owned by WsStream. DaemonHealth asks it to snapshot
+ * and restore them across a successful reconnect.
+ */
+
+type DaemonLostReason = "dead" | "respawned" | "hung" | "heartbeat";
+type DaemonLostCallback = (reason: DaemonLostReason, detail?: string) => void;
+type DaemonReconnectingCallback = (attempt: number, max: number) => void;
+type DaemonReconnectedCallback = () => void;
+declare class DaemonHealth {
+    private getIpc;
+    private stream;
+    private originalPid;
+    private lost;
+    private reconnecting;
+    private heartbeatTimer;
+    private lostCallbacks;
+    private reconnectingCallbacks;
+    private reconnectedCallbacks;
+    constructor(getIpc: () => IPCClient | null, stream: WsStream);
+    bindPid(pid: number): void;
+    isLost(): boolean;
+    onLost(cb: DaemonLostCallback): void;
+    onReconnecting(cb: DaemonReconnectingCallback): void;
+    onReconnected(cb: DaemonReconnectedCallback): void;
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    private attemptReconnect;
+    private triggerLost;
+}
+
+/**
+ * TunnelClient: public facade for tunnel operations via the daemon.
+ * Used by both CLI and App. Mirrors TunnelOperations interface but routes
+ * all operations through the daemon process via HTTP + WebSocket.
+ *
+ * Composes three helpers:
+ *   - IPCClient    : HTTP request/response (start, stop, list, restart, log, …)
+ *   - WsStream     : WebSocket lifecycle, per-tunnel subscriptions, event dispatch
+ *   - DaemonHealth : heartbeat, reconnect on transient WS drops, daemon-lost events
+ */
+
+interface TunnelClientOptions {
+    origin?: ClientOrigin;
+}
+declare class TunnelClient {
+    private ipc;
+    private origin;
+    private stream;
+    health: DaemonHealth;
+    constructor(options?: TunnelClientOptions);
+    ensureDaemon(): Promise<void>;
+    static forRemoteManagement(): Promise<TunnelClient>;
+    /**
+     * Close the WebSocket connection and cleanup.
+     */
+    close(): void;
+    ping(): Promise<{
+        status: string;
+        pid: number;
+        uptime: number;
+    }>;
+    handleStartV2(config: object, noWait?: boolean, mode?: SessionMode): Promise<TunnelResponseV2 | ErrorResponse>;
+    handleStart(config: object, noWait?: boolean, mode?: SessionMode): Promise<TunnelResponse | ErrorResponse>;
+    handleUpdateConfig(config: object, noWait?: boolean): Promise<TunnelResponse | ErrorResponse>;
+    handleUpdateConfigV2(config: object, noWait?: boolean): Promise<TunnelResponseV2 | ErrorResponse>;
+    handleStop(tunnelId: string): Promise<TunnelResponse | ErrorResponse>;
+    handleListV2(): Promise<TunnelResponseV2[] | ErrorResponse>;
+    handleList(): Promise<TunnelResponse[] | ErrorResponse>;
+    handleRemoveStoppedTunnelByTunnelId(tunnelId: string): boolean | ErrorResponse;
+    handleRemoveStoppedTunnelByConfigId(configId: string): boolean | ErrorResponse;
+    handleGet(tunnelId: string): Promise<TunnelResponse | ErrorResponse>;
+    handleRestart(tunnelId: string): Promise<TunnelResponse | ErrorResponse>;
+    shutdown(): Promise<void>;
+    getLogLevel(): Promise<string>;
+    setLogLevel(level: "debug" | "info" | "error"): Promise<void>;
+    getTunnelLogging(): Promise<boolean>;
+    setTunnelLogging(enabled: boolean): Promise<void>;
+    getLogPaths(): Promise<LogPathsResponse>;
+    resolveLogPath(q: string): Promise<ResolveLogPathResponse>;
+    restart(tunnelId: string): Promise<void>;
+    attach(tunnelId: string, mode?: SubscriptionMode): Promise<void>;
+    detach(tunnelId: string): void;
+    onStats(cb: StatsCallback): void;
+    onDisconnect(cb: DisconnectCallback): void;
+    onReconnecting(cb: ReconnectingCallback): void;
+    onReconnected(cb: ReconnectedCallback): void;
+    onReconnectionFailed(cb: ReconnectionFailedCallback): void;
+    onError(cb: ErrorCallback): void;
+    onUrlReady(cb: UrlReadyCallback): void;
+    onWorkerError(cb: WorkerErrorCallback): void;
+    onWillReconnect(cb: WillReconnectCallback): void;
+    onStopped(cb: StoppedCallback): void;
+    onDaemonLost(cb: DaemonLostCallback): void;
+    onDaemonReconnecting(cb: DaemonReconnectingCallback): void;
+    onDaemonReconnected(cb: DaemonReconnectedCallback): void;
+    isDaemonLost(): boolean;
+    handleRegisterStatsListener(tunnelId: string, listener: (tunnelId: string, stats: TunnelUsageType) => void): void;
+    handleRegisterDisconnectListener(tunnelId: string, listener: (tunnelId: string, error: string, messages: string[]) => void): void;
+    handleUnregisterStatsListener(_tunnelId: string, _listenerId: string): void;
+    handleGetTunnelStats(tunnelId: string): Promise<TunnelUsageType[] | ErrorResponse>;
+    private assertClient;
+}
+
 interface BaseLogConfig {
     level?: string;
     filePath?: string;
@@ -656,12 +1116,12 @@ declare class RemoteManagementUnauthorizedError extends Error {
  * - On other failures: retry every 15 seconds
  * - Keep running until closed or SIGINT
  */
-declare function initiateRemoteManagement(remoteManagementConfig: RemoteManagementConfig): Promise<RemoteManagementState>;
+declare function initiateRemoteManagement(remoteManagementConfig: RemoteManagementConfig, tunnelHandler?: TunnelHandler): Promise<RemoteManagementState>;
 declare function closeRemoteManagement(timeoutMs?: number): Promise<RemoteManagementState>;
 /**
  * Start remote management loop in background; returns after first connection attempt.
  */
-declare function startRemoteManagement(remoteManagementConfig: RemoteManagementConfig): Promise<RemoteManagementState>;
+declare function startRemoteManagement(remoteManagementConfig: RemoteManagementConfig, tunnelHandler?: TunnelHandler): Promise<RemoteManagementState>;
 declare function getRemoteManagementState(): RemoteManagementState;
 
-export { type AdditionalForwarding, type DisconnectListener, type ErrorListener, type FinalConfig, type ITunnelManager, type ManagedTunnel, type ReconnectingListener, type ReconnectionCompletedListener, type ReconnectionFailedListener, RemoteManagementUnauthorizedError, type StartListener, type StatsListener, type Status, TunnelErrorCodeType, type TunnelList, TunnelManager, TunnelOperations, type TunnelResponse, TunnelStateType, type TunnelStatus, TunnelWarningCode, type TunnelWorkerErrorListner, type Warning, type WillReconnectListener, closeRemoteManagement, enablePackageLogging, getRemoteManagementState, initiateRemoteManagement, startRemoteManagement };
+export { type AdditionalForwarding, type DisconnectListener, type ErrorListener, type FinalConfig, type ITunnelManager, type ManagedTunnel, type ReconnectingListener, type ReconnectionCompletedListener, type ReconnectionFailedListener, RemoteManagementUnauthorizedError, type StartListener, type StatsListener, type Status, TunnelClient, TunnelErrorCodeType, type TunnelList, TunnelManager, TunnelOperations, type TunnelResponse, TunnelStateType, type TunnelStatus, TunnelWarningCode, type TunnelWorkerErrorListner, type Warning, type WillReconnectListener, closeRemoteManagement, enablePackageLogging, getRemoteManagementState, initiateRemoteManagement, startRemoteManagement };