whale-code 6.4.0 → 6.5.0

package/dist/node/gateway-client.js

@@ -0,0 +1,201 @@
+/**
+ * Gateway Client — connects whale-node to the server's local-agent-gateway WebSocket.
+ *
+ * Authenticates with the node's API key, handles ping/pong keepalive,
+ * routes incoming exec/cluster_command messages, responds with results.
+ * Auto-reconnects on disconnect with exponential backoff.
+ */
+import { WebSocket } from "ws";
+import { EventEmitter } from "node:events";
+import os from "node:os";
+export class GatewayClient extends EventEmitter {
+    ws = null;
+    config;
+    reconnectDelay = 1000;
+    maxReconnectDelay = 60_000;
+    running = false;
+    agentId = null;
+    commandHandlers = new Map();
+    binaryHandler = null;
+    constructor(config) {
+        super();
+        this.config = config;
+    }
+    /**
+     * Register a handler for a specific command type (e.g. "exec", "cluster_command").
+     */
+    onCommand(type, handler) {
+        this.commandHandlers.set(type, handler);
+    }
+    /**
+     * Connect to the server's WebSocket gateway.
+     */
+    start() {
+        this.running = true;
+        this.connect();
+    }
+    /**
+     * Disconnect and stop reconnecting.
+     */
+    stop() {
+        this.running = false;
+        if (this.ws) {
+            this.ws.close(1000, "Node shutting down");
+            this.ws = null;
+        }
+    }
+    /**
+     * Register a handler for binary messages (portal frames).
+     */
+    onBinary(handler) {
+        this.binaryHandler = handler;
+    }
+    /**
+     * Send raw binary data over the WebSocket (for portal frames).
+     */
+    sendBinary(data) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(data);
+        }
+    }
+    /**
+     * Send a JSON message over the WebSocket.
+     */
+    sendJson(msg) {
+        this.send(msg);
+    }
+    get isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    // ============================================================================
+    // INTERNAL
+    // ============================================================================
+    connect() {
+        if (!this.running)
+            return;
+        // Convert https:// to wss:// and http:// to ws://
+        const wsUrl = this.config.serverUrl
+            .replace(/^https:\/\//, "wss://")
+            .replace(/^http:\/\//, "ws://")
+            + "/agent/ws";
+        try {
+            this.ws = new WebSocket(wsUrl);
+        }
+        catch (err) {
+            console.error(`[gateway] Failed to create WebSocket:`, err.message);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws.on("open", () => {
+            console.log(`[gateway] Connected to ${wsUrl}`);
+            this.reconnectDelay = 1000; // Reset backoff
+            // Send auth
+            this.send({
+                type: "auth",
+                api_key: this.config.apiKey,
+                capabilities: this.config.capabilities || [],
+                platform: process.platform,
+                hostname: os.hostname(),
+                version: this.config.version || "1.0.0",
+            });
+        });
+        this.ws.on("message", async (raw, isBinary) => {
+            // Handle binary messages (portal frames)
+            if (isBinary || (Buffer.isBuffer(raw) && raw.length > 0 && raw[0] === 0x01)) {
+                const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+                if (this.binaryHandler) {
+                    this.binaryHandler(buf);
+                }
+                return;
+            }
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            // Handle auth response
+            if (msg.type === "authenticated") {
+                this.agentId = msg.agent_id;
+                console.log(`[gateway] Authenticated as agent ${this.agentId}`);
+                this.emit("connected", this.agentId);
+                return;
+            }
+            // Handle ping from server
+            if (msg.type === "ping") {
+                this.send({ type: "pong" });
+                return;
+            }
+            // Handle errors
+            if (msg.type === "error") {
+                console.error(`[gateway] Server error: ${msg.error}`);
+                this.emit("error", msg.error);
+                return;
+            }
+            // Handle commands (exec, cluster_command, tool_exec, discover)
+            const handler = this.commandHandlers.get(msg.type);
+            if (handler) {
+                if (msg.request_id) {
+                    // Request-response pattern
+                    try {
+                        const result = await handler(msg);
+                        if (result !== null) {
+                            this.send({
+                                type: "result",
+                                request_id: msg.request_id,
+                                success: true,
+                                ...result,
+                            });
+                        }
+                    }
+                    catch (err) {
+                        this.send({
+                            type: "result",
+                            request_id: msg.request_id,
+                            success: false,
+                            error: err.message,
+                        });
+                    }
+                }
+                else {
+                    // Fire-and-forget pattern (portal messages)
+                    handler(msg).catch(() => { });
+                }
+                return;
+            }
+            // Unknown message type
+            if (msg.type && msg.type !== "error") {
+                console.log(`[gateway] Unhandled message type: ${msg.type}`);
+            }
+        });
+        this.ws.on("close", (code, reason) => {
+            console.log(`[gateway] Disconnected (code=${code} reason=${reason?.toString() || "none"})`);
+            this.agentId = null;
+            this.emit("disconnected", code, reason?.toString());
+            this.scheduleReconnect();
+        });
+        this.ws.on("error", (err) => {
+            // Suppress ECONNREFUSED spam — the reconnect handles it
+            if (err.code !== "ECONNREFUSED") {
+                console.error(`[gateway] WebSocket error: ${err.message}`);
+            }
+        });
+    }
+    scheduleReconnect() {
+        if (!this.running)
+            return;
+        setTimeout(() => {
+            if (this.running) {
+                this.connect();
+            }
+        }, this.reconnectDelay);
+        // Exponential backoff
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
+    }
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+}

package/dist/node/portal/clipboard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ClipboardChannel — clipboard sync between nodes.
+ *
+ * macOS: pbcopy / pbpaste via child_process
+ * Modes: push (one-shot send), pull (one-shot receive), sync (bidirectional)
+ */
+import type { PortalStream } from "./stream.js";
+import type { SynClipboard } from "./protocol.js";
+import type { PortalSession } from "./session.js";
+/**
+ * Send local clipboard to remote node (one-shot).
+ */
+export declare function pushClipboard(session: PortalSession): Promise<void>;
+/**
+ * Get clipboard from remote node (one-shot).
+ */
+export declare function pullClipboard(session: PortalSession): Promise<string>;
+/**
+ * Start bidirectional clipboard sync.
+ * Returns a cleanup function to stop syncing.
+ */
+export declare function syncClipboard(session: PortalSession): Promise<{
+    cleanup: () => void;
+}>;
+/**
+ * Handle an incoming clipboard stream on the target node.
+ */
+export declare function handleClipboard(stream: PortalStream, meta: SynClipboard): void;

package/dist/node/portal/clipboard.js

@@ -0,0 +1,183 @@
+/**
+ * ClipboardChannel — clipboard sync between nodes.
+ *
+ * macOS: pbcopy / pbpaste via child_process
+ * Modes: push (one-shot send), pull (one-shot receive), sync (bidirectional)
+ */
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+const SYNC_POLL_MS = 500;
+// ============================================================================
+// CLIPBOARD I/O (macOS)
+// ============================================================================
+function readClipboard() {
+    try {
+        if (process.platform === "darwin") {
+            return execSync("pbpaste", { encoding: "utf-8", timeout: 2000 });
+        }
+        // Linux xclip fallback
+        return execSync("xclip -selection clipboard -o", { encoding: "utf-8", timeout: 2000 });
+    }
+    catch {
+        return "";
+    }
+}
+function writeClipboard(text) {
+    try {
+        if (process.platform === "darwin") {
+            execSync("pbcopy", { input: text, timeout: 2000 });
+        }
+        else {
+            execSync("xclip -selection clipboard", { input: text, timeout: 2000 });
+        }
+    }
+    catch {
+        // best effort
+    }
+}
+function hashContent(text) {
+    return createHash("md5").update(text).digest("hex");
+}
+// ============================================================================
+// INITIATOR SIDE
+// ============================================================================
+/**
+ * Send local clipboard to remote node (one-shot).
+ */
+export async function pushClipboard(session) {
+    const stream = session.openStream({ channel: "clipboard", mode: "push" });
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error("Clipboard open timed out")), 5000);
+        session.once("stream:ack", (s) => {
+            if (s.streamId === stream.streamId) {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+    });
+    const content = readClipboard();
+    stream.write(Buffer.from(content));
+    stream.end();
+}
+/**
+ * Get clipboard from remote node (one-shot).
+ */
+export async function pullClipboard(session) {
+    const stream = session.openStream({ channel: "clipboard", mode: "pull" });
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error("Clipboard open timed out")), 5000);
+        session.once("stream:ack", (s) => {
+            if (s.streamId === stream.streamId) {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+    });
+    return new Promise((resolve) => {
+        const chunks = [];
+        stream.on("data", (chunk) => chunks.push(chunk));
+        stream.on("end", () => {
+            const content = Buffer.concat(chunks).toString();
+            writeClipboard(content);
+            resolve(content);
+        });
+    });
+}
+/**
+ * Start bidirectional clipboard sync.
+ * Returns a cleanup function to stop syncing.
+ */
+export async function syncClipboard(session) {
+    const stream = session.openStream({ channel: "clipboard", mode: "sync" });
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error("Clipboard sync timed out")), 5000);
+        session.once("stream:ack", (s) => {
+            if (s.streamId === stream.streamId) {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+    });
+    let lastHash = hashContent(readClipboard());
+    let running = true;
+    // Poll local clipboard and send changes
+    const pollTimer = setInterval(() => {
+        if (!running)
+            return;
+        const content = readClipboard();
+        const hash = hashContent(content);
+        if (hash !== lastHash) {
+            lastHash = hash;
+            if (!stream.destroyed) {
+                stream.write(Buffer.from(content));
+            }
+        }
+    }, SYNC_POLL_MS);
+    // Receive remote clipboard changes
+    stream.on("data", (data) => {
+        const content = data.toString();
+        const hash = hashContent(content);
+        if (hash !== lastHash) {
+            lastHash = hash;
+            writeClipboard(content);
+        }
+    });
+    const cleanup = () => {
+        running = false;
+        clearInterval(pollTimer);
+        if (!stream.destroyed)
+            stream.end();
+    };
+    stream.on("end", cleanup);
+    stream.on("error", cleanup);
+    return { cleanup };
+}
+// ============================================================================
+// TARGET SIDE
+// ============================================================================
+/**
+ * Handle an incoming clipboard stream on the target node.
+ */
+export function handleClipboard(stream, meta) {
+    if (meta.mode === "push") {
+        // Receive clipboard content and write locally
+        const chunks = [];
+        stream.on("data", (chunk) => chunks.push(chunk));
+        stream.on("end", () => {
+            writeClipboard(Buffer.concat(chunks).toString());
+        });
+        return;
+    }
+    if (meta.mode === "pull") {
+        // Send local clipboard content
+        const content = readClipboard();
+        stream.write(Buffer.from(content));
+        stream.end();
+        return;
+    }
+    // Sync mode — bidirectional
+    let lastHash = hashContent(readClipboard());
+    const pollTimer = setInterval(() => {
+        const content = readClipboard();
+        const hash = hashContent(content);
+        if (hash !== lastHash) {
+            lastHash = hash;
+            if (!stream.destroyed) {
+                stream.write(Buffer.from(content));
+            }
+        }
+    }, SYNC_POLL_MS);
+    stream.on("data", (data) => {
+        const content = data.toString();
+        const hash = hashContent(content);
+        if (hash !== lastHash) {
+            lastHash = hash;
+            writeClipboard(content);
+        }
+    });
+    const cleanup = () => {
+        clearInterval(pollTimer);
+    };
+    stream.on("end", cleanup);
+    stream.on("error", cleanup);
+}

package/dist/node/portal/discovery.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Portal Discovery — find online nodes in the user's store.
+ *
+ * Queries the nodes table via the server API. Nodes with a heartbeat
+ * within the last 2 minutes are considered online.
+ */
+export interface DiscoveredNode {
+    id: string;
+    name: string;
+    hostname: string;
+    platform: string;
+    status: "online" | "offline";
+    last_heartbeat: string;
+    capabilities: string[];
+}
+export interface DiscoveryOptions {
+    serverUrl: string;
+    apiKey: string;
+    storeId: string;
+    includeOffline?: boolean;
+}
+/**
+ * Discover nodes in the same store via the server's heartbeat-based status.
+ */
+export declare function discoverNodes(opts: DiscoveryOptions): Promise<DiscoveredNode[]>;
+/**
+ * Find a specific node by name or partial match.
+ */
+export declare function findNode(name: string, opts: DiscoveryOptions): Promise<DiscoveredNode | null>;

package/dist/node/portal/discovery.js

@@ -0,0 +1,61 @@
+/**
+ * Portal Discovery — find online nodes in the user's store.
+ *
+ * Queries the nodes table via the server API. Nodes with a heartbeat
+ * within the last 2 minutes are considered online.
+ */
+/**
+ * Discover nodes in the same store via the server's heartbeat-based status.
+ */
+export async function discoverNodes(opts) {
+    const url = `${opts.serverUrl}/nodes?store_id=${opts.storeId}`;
+    const res = await fetch(url, {
+        headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        throw new Error(`Discovery failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json();
+    if (!data.success || !data.nodes) {
+        throw new Error(data.error || "No nodes found");
+    }
+    const now = Date.now();
+    const ONLINE_THRESHOLD_MS = 2 * 60 * 1000; // 2 minutes
+    const nodes = data.nodes.map((n) => {
+        const lastHb = n.last_heartbeat ? new Date(n.last_heartbeat).getTime() : 0;
+        const isOnline = n.status === "online" && (now - lastHb) < ONLINE_THRESHOLD_MS;
+        return {
+            id: n.id,
+            name: n.name || n.hostname || "unnamed",
+            hostname: n.hardware?.hostname || n.hostname || "unknown",
+            platform: n.hardware?.os || n.platform || "unknown",
+            status: isOnline ? "online" : "offline",
+            last_heartbeat: n.last_heartbeat || "",
+            capabilities: n.capabilities || [],
+        };
+    });
+    if (!opts.includeOffline) {
+        return nodes.filter(n => n.status === "online");
+    }
+    return nodes;
+}
+/**
+ * Find a specific node by name or partial match.
+ */
+export async function findNode(name, opts) {
+    const nodes = await discoverNodes({ ...opts, includeOffline: false });
+    const lower = name.toLowerCase();
+    // Exact match on name or hostname
+    const exact = nodes.find(n => n.name.toLowerCase() === lower ||
+        n.hostname.toLowerCase() === lower);
+    if (exact)
+        return exact;
+    // Partial match
+    const partial = nodes.find(n => n.name.toLowerCase().includes(lower) ||
+        n.hostname.toLowerCase().includes(lower));
+    return partial || null;
+}

package/dist/node/portal/forward.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ForwardChannel — TCP port forwarding over portal streams.
+ *
+ * Local forward: net.createServer on local port → pipe to portal stream → remote net.connect
+ * Remote expose: reverse of above
+ */
+import { type Server } from "node:net";
+import type { PortalStream } from "./stream.js";
+import type { SynForward } from "./protocol.js";
+import type { PortalSession } from "./session.js";
+export interface ForwardInfo {
+    localPort: number;
+    remotePort: number;
+    connections: number;
+    server: Server;
+}
+/**
+ * Forward a local port to a remote port on the target node.
+ * Returns a ForwardInfo with the local server.
+ */
+export declare function startForward(session: PortalSession, localPort: number, remotePort: number, description?: string): Promise<ForwardInfo>;
+/**
+ * Handle an incoming port forward stream on the target node.
+ * Connects to the local port and pipes data.
+ */
+export declare function handleForward(stream: PortalStream, meta: SynForward): void;
+/**
+ * Stop a port forward.
+ */
+export declare function stopForward(info: ForwardInfo): Promise<void>;

package/dist/node/portal/forward.js

@@ -0,0 +1,90 @@
+/**
+ * ForwardChannel — TCP port forwarding over portal streams.
+ *
+ * Local forward: net.createServer on local port → pipe to portal stream → remote net.connect
+ * Remote expose: reverse of above
+ */
+import { createServer, connect } from "node:net";
+// ============================================================================
+// INITIATOR SIDE — local port → remote port
+// ============================================================================
+/**
+ * Forward a local port to a remote port on the target node.
+ * Returns a ForwardInfo with the local server.
+ */
+export async function startForward(session, localPort, remotePort, description) {
+    let connections = 0;
+    const server = createServer((socket) => {
+        connections++;
+        // Open a new stream for each TCP connection
+        const stream = session.openStream({
+            channel: "forward",
+            remotePort,
+            description,
+        });
+        // Pipe bidirectionally
+        socket.pipe(stream);
+        stream.pipe(socket);
+        socket.on("error", () => {
+            if (!stream.destroyed)
+                stream.destroy();
+        });
+        stream.on("error", () => {
+            if (!socket.destroyed)
+                socket.destroy();
+        });
+        socket.on("close", () => {
+            if (!stream.destroyed)
+                stream.end();
+            connections--;
+        });
+        stream.on("close", () => {
+            if (!socket.destroyed)
+                socket.end();
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.listen(localPort, "127.0.0.1", () => resolve());
+        server.on("error", reject);
+    });
+    return { localPort, remotePort, connections, server };
+}
+// ============================================================================
+// TARGET SIDE — handle incoming forward stream
+// ============================================================================
+/**
+ * Handle an incoming port forward stream on the target node.
+ * Connects to the local port and pipes data.
+ */
+export function handleForward(stream, meta) {
+    const socket = connect(meta.remotePort, "127.0.0.1");
+    socket.on("connect", () => {
+        socket.pipe(stream);
+        stream.pipe(socket);
+    });
+    socket.on("error", (err) => {
+        if (!stream.destroyed) {
+            stream.destroy(new Error(`Connection to port ${meta.remotePort} failed: ${err.message}`));
+        }
+    });
+    stream.on("error", () => {
+        if (!socket.destroyed)
+            socket.destroy();
+    });
+    socket.on("close", () => {
+        if (!stream.destroyed)
+            stream.end();
+    });
+    stream.on("close", () => {
+        if (!socket.destroyed)
+            socket.end();
+    });
+}
+/**
+ * Stop a port forward.
+ */
+export function stopForward(info) {
+    return new Promise((resolve) => {
+        info.server.close(() => resolve());
+    });
+}

package/dist/node/portal/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PortalManager — coordinator for portal connections.
+ *
+ * Manages portal sessions, handles incoming requests on the target side,
+ * and provides the public API used by the CLI and runtime.
+ */
+import { EventEmitter } from "node:events";
+import type { GatewayClient } from "../gateway-client.js";
+import type { NodeConfig } from "../config.js";
+import type { ScreenCaptureService } from "../remote-desktop/index.js";
+import { PortalSession } from "./session.js";
+export interface PortalManagerConfig {
+    nodeConfig: NodeConfig;
+    gateway: GatewayClient;
+    screenCapture?: ScreenCaptureService | null;
+    receiveDir?: string;
+    autoAcceptAdmins?: boolean;
+    maxSessions?: number;
+}
+export declare class PortalManager extends EventEmitter {
+    private config;
+    private sessions;
+    private gateway;
+    constructor(config: PortalManagerConfig);
+    /**
+     * Open a portal to a target node.
+     * Returns a PortalSession that can be used to open streams.
+     */
+    connect(targetNodeId: string, capabilities: string[]): Promise<PortalSession>;
+    /**
+     * Get all active sessions.
+     */
+    getSessions(): Array<ReturnType<PortalSession["getInfo"]>>;
+    /**
+     * Close a session by ID.
+     */
+    closeSession(sessionId: string): boolean;
+    /**
+     * Close all sessions.
+     */
+    closeAll(): void;
+    private setupHandlers;
+    private handlePortalRequest;
+    private handleIncomingStream;
+    private routeBinaryFrame;
+    private sendJson;
+}