sessioncast-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SessionCast
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# SessionCast CLI
+
+Node.js agent and CLI for [SessionCast](https://sessioncast.io) - a real-time terminal sharing platform.
+
+## Features
+
+### Agent
+- **Auto-discovery**: Automatically detects and connects tmux sessions
+- **Real-time screen capture**: Streams terminal output with gzip compression
+- **Circuit breaker**: Prevents reconnection storms with exponential backoff
+- **Interactive control**: Supports keyboard input, resize, and session management
+- **File viewer**: Cmd+Click on file paths to view files in browser
+
+### CLI Commands
+- `sessioncast login <api-key>` - Authenticate with API key
+- `sessioncast logout` - Clear stored credentials
+- `sessioncast status` - Check authentication status
+- `sessioncast agents` - List registered agents
+- `sessioncast list [agent]` - List tmux sessions
+- `sessioncast send <target> <keys>` - Send keys to a session
+- `sessioncast agent` - Start the agent
+
+## Installation
+
+```bash
+npm install -g sessioncast-cli
+```
+
+## Quick Start
+
+1. **Get your agent token** from [app.sessioncast.io](https://app.sessioncast.io)
+
+2. **Create config file** `~/.sessioncast.yml`:
+
+```yaml
+machineId: my-machine
+relay: wss://relay.sessioncast.io/ws
+token: agt_your_agent_token_here
+```
+
+3. **Start the agent**:
+
+```bash
+sessioncast agent
+```
+
+4. **View your sessions** at [app.sessioncast.io](https://app.sessioncast.io)
+
+## Configuration
+
+Create `~/.sessioncast.yml` or `~/.tmux-remote.yml`:
+
+```yaml
+machineId: my-machine
+relay: wss://relay.sessioncast.io/ws
+token: agt_your_agent_token_here
+
+# Optional: API configuration
+api:
+  enabled: true
+  agentId: "your-agent-uuid"
+
+  exec:
+    enabled: true
+    shell: /bin/bash
+    workingDir: /home/user
+    defaultTimeout: 30000
+
+  llm:
+    enabled: false
+```
+
+### Environment Variables
+
+- `SESSIONCAST_CONFIG` - Custom config file path
+- `TMUX_REMOTE_CONFIG` - Alternative config file path
+
+## Usage
+
+### Start the Agent
+
+```bash
+# Run agent (foreground)
+sessioncast agent
+
+# Run agent (background)
+nohup sessioncast agent > /tmp/sessioncast-agent.log 2>&1 &
+```
+
+### Send Keys to Session
+
+```bash
+# Send text to a session
+sessioncast send my-machine/dev "ls -la"
+
+# Send special keys
+sessioncast send my-machine/dev "Enter"
+```
+
+## Architecture
+
+```
+┌─────────────┐     WebSocket      ┌─────────────┐     WebSocket     ┌─────────────┐
+│   Agent     │ ◄─────────────────► │   Relay     │ ◄────────────────► │   Viewer    │
+│  (Node.js)  │    screen/keys     │  (Server)   │    screen/keys    │   (Web)     │
+└─────────────┘                    └─────────────┘                   └─────────────┘
+      │
+      │ tmux
+      ▼
+┌─────────────┐
+│   tmux      │
+│  sessions   │
+└─────────────┘
+```
+
+## Circuit Breaker
+
+The agent implements a circuit breaker pattern to prevent reconnection storms:
+
+- **Max reconnect attempts**: 5
+- **Base delay**: 1 second
+- **Max delay**: 30 seconds (with exponential backoff + jitter)
+- **Circuit breaker duration**: 2 minutes cooldown after max attempts
+
+## Requirements
+
+- Node.js >= 18
+- tmux installed on the host machine
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- Homepage: https://sessioncast.io
+- Email: devload@sessioncast.io

package/dist/agent/api-client.d.ts

@@ -0,0 +1,27 @@
+import { AgentConfig } from './types';
+export declare class ApiWebSocketClient {
+    private ws;
+    private config;
+    private apiConfig;
+    private commandService;
+    private llmService;
+    private isConnected;
+    private reconnectAttempts;
+    private circuitBreakerOpen;
+    private circuitBreakerResetTime;
+    private reconnectTimer;
+    private destroyed;
+    constructor(config: AgentConfig);
+    start(): void;
+    private connect;
+    private registerAsApiAgent;
+    private handleMessage;
+    private handleExec;
+    private handleLlmChat;
+    private handleSendKeys;
+    private handleListSessions;
+    private sendApiResponse;
+    private send;
+    private scheduleReconnect;
+    stop(): void;
+}

package/dist/agent/api-client.js

@@ -0,0 +1,295 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiWebSocketClient = void 0;
+const ws_1 = __importDefault(require("ws"));
+const exec_service_1 = require("./exec-service");
+const llm_service_1 = require("./llm-service");
+const tmux = __importStar(require("./tmux"));
+const MAX_RECONNECT_ATTEMPTS = 5;
+const BASE_RECONNECT_DELAY_MS = 2000;
+const MAX_RECONNECT_DELAY_MS = 60000;
+const CIRCUIT_BREAKER_DURATION_MS = 120000;
+class ApiWebSocketClient {
+    constructor(config) {
+        this.ws = null;
+        this.isConnected = false;
+        this.reconnectAttempts = 0;
+        this.circuitBreakerOpen = false;
+        this.circuitBreakerResetTime = 0;
+        this.reconnectTimer = null;
+        this.destroyed = false;
+        this.config = config;
+        this.apiConfig = config.api || { enabled: false };
+        this.commandService = new exec_service_1.CommandExecutionService(this.apiConfig.exec);
+        this.llmService = new llm_service_1.LlmService(this.apiConfig.llm);
+    }
+    start() {
+        if (!this.apiConfig.enabled || !this.apiConfig.agentId) {
+            console.log('[API] API client disabled or no agentId configured');
+            return;
+        }
+        // Add jitter to prevent thundering herd
+        const jitter = Math.floor(Math.random() * 2000);
+        console.log(`[API] Starting in ${jitter}ms`);
+        setTimeout(() => this.connect(), jitter);
+    }
+    connect() {
+        if (this.destroyed)
+            return;
+        try {
+            this.ws = new ws_1.default(this.config.relay);
+            this.ws.on('open', () => {
+                this.isConnected = true;
+                this.reconnectAttempts = 0;
+                this.circuitBreakerOpen = false;
+                console.log('[API] Connected to relay');
+                this.registerAsApiAgent();
+            });
+            this.ws.on('message', (data) => {
+                try {
+                    const message = JSON.parse(data.toString());
+                    this.handleMessage(message);
+                }
+                catch (e) {
+                    console.error('[API] Failed to parse message:', e);
+                }
+            });
+            this.ws.on('close', (code, reason) => {
+                this.isConnected = false;
+                console.log(`[API] Disconnected: code=${code}, reason=${reason.toString()}`);
+                if (!this.destroyed) {
+                    this.scheduleReconnect();
+                }
+            });
+            this.ws.on('error', (error) => {
+                console.error('[API] WebSocket error:', error.message);
+            });
+        }
+        catch (error) {
+            console.error('[API] Connection error:', error.message);
+            if (!this.destroyed) {
+                this.scheduleReconnect();
+            }
+        }
+    }
+    registerAsApiAgent() {
+        const meta = {
+            machineId: this.config.machineId,
+            agentId: this.apiConfig.agentId
+        };
+        if (this.config.token) {
+            meta.token = this.config.token;
+        }
+        this.send({
+            type: 'register',
+            role: 'host',
+            session: `api-${this.apiConfig.agentId}`,
+            meta
+        });
+        console.log(`[API] Registered as API agent: ${this.apiConfig.agentId}`);
+    }
+    async handleMessage(message) {
+        switch (message.type) {
+            case 'exec':
+                await this.handleExec(message);
+                break;
+            case 'llm_chat':
+                await this.handleLlmChat(message);
+                break;
+            case 'send_keys':
+                await this.handleSendKeys(message);
+                break;
+            case 'list_sessions':
+                await this.handleListSessions(message);
+                break;
+        }
+    }
+    async handleExec(message) {
+        const meta = message.meta;
+        if (!meta?.requestId)
+            return;
+        try {
+            const payload = meta.payload ? JSON.parse(meta.payload) : {};
+            const { command, cwd, timeout, sessionId } = payload;
+            console.log(`[API] exec: command=${command}, cwd=${cwd}, timeout=${timeout}`);
+            const result = await this.commandService.executeCommand(command, cwd, timeout, sessionId);
+            this.sendApiResponse(meta.requestId, result);
+        }
+        catch (error) {
+            this.sendApiResponse(meta.requestId, {
+                exitCode: -1,
+                stdout: '',
+                stderr: `Error: ${error.message}`,
+                duration: 0
+            });
+        }
+    }
+    async handleLlmChat(message) {
+        const meta = message.meta;
+        if (!meta?.requestId)
+            return;
+        try {
+            const payload = meta.payload ? JSON.parse(meta.payload) : {};
+            const { model, messages, temperature, max_tokens, stream } = payload;
+            console.log(`[API] llm_chat: model=${model}, messages=${messages?.length || 0}`);
+            const result = await this.llmService.chat(model, messages, temperature, max_tokens, stream);
+            this.sendApiResponse(meta.requestId, result);
+        }
+        catch (error) {
+            this.sendApiResponse(meta.requestId, {
+                error: {
+                    message: error.message,
+                    type: 'internal_error'
+                }
+            });
+        }
+    }
+    async handleSendKeys(message) {
+        const meta = message.meta;
+        if (!meta?.requestId)
+            return;
+        try {
+            const payload = meta.payload ? JSON.parse(meta.payload) : {};
+            const { target, keys, enter = true } = payload;
+            if (!target || !keys) {
+                this.sendApiResponse(meta.requestId, {
+                    success: false,
+                    error: 'target and keys are required'
+                });
+                return;
+            }
+            console.log(`[API] send_keys: target=${target}, keys=${keys}, enter=${enter}`);
+            const success = tmux.sendKeys(target, keys, enter);
+            this.sendApiResponse(meta.requestId, { success, target });
+        }
+        catch (error) {
+            this.sendApiResponse(meta.requestId, {
+                success: false,
+                error: error.message
+            });
+        }
+    }
+    async handleListSessions(message) {
+        const meta = message.meta;
+        if (!meta?.requestId)
+            return;
+        try {
+            console.log('[API] list_sessions');
+            const sessions = tmux.listSessions();
+            this.sendApiResponse(meta.requestId, { sessions });
+        }
+        catch (error) {
+            this.sendApiResponse(meta.requestId, {
+                sessions: [],
+                error: error.message
+            });
+        }
+    }
+    sendApiResponse(requestId, response) {
+        this.send({
+            type: 'api_response',
+            meta: {
+                requestId,
+                payload: JSON.stringify(response)
+            }
+        });
+    }
+    send(message) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN) {
+            return false;
+        }
+        try {
+            this.ws.send(JSON.stringify(message));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    scheduleReconnect() {
+        if (this.destroyed)
+            return;
+        // Check circuit breaker
+        if (this.circuitBreakerOpen) {
+            const now = Date.now();
+            if (now < this.circuitBreakerResetTime) {
+                const remainingSeconds = Math.ceil((this.circuitBreakerResetTime - now) / 1000);
+                console.log(`[API] Circuit breaker open. Retry in ${remainingSeconds} seconds`);
+                this.reconnectTimer = setTimeout(() => this.scheduleReconnect(), this.circuitBreakerResetTime - now);
+                return;
+            }
+            else {
+                console.log('[API] Circuit breaker reset');
+                this.circuitBreakerOpen = false;
+                this.reconnectAttempts = 0;
+            }
+        }
+        this.reconnectAttempts++;
+        if (this.reconnectAttempts > MAX_RECONNECT_ATTEMPTS) {
+            console.error(`[API] Max reconnect attempts reached. Circuit breaker active for ${CIRCUIT_BREAKER_DURATION_MS / 1000}s`);
+            this.circuitBreakerOpen = true;
+            this.circuitBreakerResetTime = Date.now() + CIRCUIT_BREAKER_DURATION_MS;
+            this.reconnectAttempts = 0;
+            this.reconnectTimer = setTimeout(() => this.scheduleReconnect(), CIRCUIT_BREAKER_DURATION_MS);
+            return;
+        }
+        const delay = Math.min(BASE_RECONNECT_DELAY_MS * Math.pow(2, this.reconnectAttempts - 1), MAX_RECONNECT_DELAY_MS);
+        const jitter = Math.random() * delay * 0.5;
+        const reconnectDelay = Math.floor(delay + jitter);
+        console.log(`[API] Reconnecting in ${reconnectDelay}ms (attempt ${this.reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})`);
+        this.reconnectTimer = setTimeout(() => {
+            if (!this.isConnected && !this.destroyed) {
+                this.connect();
+            }
+        }, reconnectDelay);
+    }
+    stop() {
+        console.log('[API] Stopping');
+        this.destroyed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+}
+exports.ApiWebSocketClient = ApiWebSocketClient;

package/dist/agent/exec-service.d.ts

@@ -0,0 +1,6 @@
+import { ExecConfig, ExecResult } from './types';
+export declare class CommandExecutionService {
+    private config;
+    constructor(config?: ExecConfig);
+    executeCommand(command: string, cwd?: string, timeout?: number, sessionId?: string): Promise<ExecResult>;
+}

package/dist/agent/exec-service.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandExecutionService = void 0;
+const child_process_1 = require("child_process");
+class CommandExecutionService {
+    constructor(config) {
+        this.config = config || {
+            enabled: false,
+            shell: '/bin/bash',
+            defaultTimeout: 30000
+        };
+    }
+    async executeCommand(command, cwd, timeout, sessionId) {
+        const startTime = Date.now();
+        if (!this.config.enabled) {
+            return {
+                exitCode: -1,
+                stdout: '',
+                stderr: 'Command execution is disabled on this agent',
+                duration: 0
+            };
+        }
+        // Check allowed commands if configured
+        if (this.config.allowedCommands && this.config.allowedCommands.length > 0) {
+            const allowed = this.config.allowedCommands.some(pattern => command.startsWith(pattern) || new RegExp(pattern).test(command));
+            if (!allowed) {
+                return {
+                    exitCode: -1,
+                    stdout: '',
+                    stderr: 'Command not in allowed list',
+                    duration: 0
+                };
+            }
+        }
+        const timeoutMs = timeout ?? this.config.defaultTimeout;
+        const workingDir = cwd ?? this.config.workingDir;
+        const shell = this.config.shell || '/bin/bash';
+        return new Promise((resolve) => {
+            try {
+                // If sessionId is provided, run in tmux session
+                if (sessionId) {
+                    try {
+                        (0, child_process_1.execSync)(`tmux send-keys -t "${sessionId}" "${escapeForShell(command)}" Enter`, {
+                            stdio: 'pipe',
+                            timeout: timeoutMs
+                        });
+                        resolve({
+                            exitCode: 0,
+                            stdout: 'Command sent to tmux session',
+                            stderr: '',
+                            duration: Date.now() - startTime
+                        });
+                    }
+                    catch (error) {
+                        resolve({
+                            exitCode: -1,
+                            stdout: '',
+                            stderr: error.message || 'Failed to send to tmux',
+                            duration: Date.now() - startTime
+                        });
+                    }
+                    return;
+                }
+                // Direct shell execution
+                const child = (0, child_process_1.spawn)(shell, ['-c', command], {
+                    cwd: workingDir || undefined,
+                    stdio: ['pipe', 'pipe', 'pipe']
+                });
+                let stdout = '';
+                let stderr = '';
+                let killed = false;
+                const timer = setTimeout(() => {
+                    killed = true;
+                    child.kill('SIGKILL');
+                }, timeoutMs);
+                child.stdout.on('data', (data) => {
+                    stdout += data.toString();
+                });
+                child.stderr.on('data', (data) => {
+                    stderr += data.toString();
+                });
+                child.on('close', (code) => {
+                    clearTimeout(timer);
+                    const duration = Date.now() - startTime;
+                    if (killed) {
+                        resolve({
+                            exitCode: -1,
+                            stdout: '',
+                            stderr: `Command timed out after ${timeoutMs}ms`,
+                            duration
+                        });
+                    }
+                    else {
+                        resolve({
+                            exitCode: code ?? -1,
+                            stdout,
+                            stderr,
+                            duration
+                        });
+                    }
+                });
+                child.on('error', (error) => {
+                    clearTimeout(timer);
+                    resolve({
+                        exitCode: -1,
+                        stdout: '',
+                        stderr: `Execution error: ${error.message}`,
+                        duration: Date.now() - startTime
+                    });
+                });
+            }
+            catch (error) {
+                resolve({
+                    exitCode: -1,
+                    stdout: '',
+                    stderr: `Execution error: ${error.message}`,
+                    duration: Date.now() - startTime
+                });
+            }
+        });
+    }
+}
+exports.CommandExecutionService = CommandExecutionService;
+function escapeForShell(str) {
+    return str.replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`');
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types';
+export * from './tmux';
+export * from './websocket';
+export * from './session-handler';
+export * from './exec-service';
+export * from './llm-service';
+export * from './api-client';
+export * from './runner';

package/dist/agent/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./tmux"), exports);
+__exportStar(require("./websocket"), exports);
+__exportStar(require("./session-handler"), exports);
+__exportStar(require("./exec-service"), exports);
+__exportStar(require("./llm-service"), exports);
+__exportStar(require("./api-client"), exports);
+__exportStar(require("./runner"), exports);

package/dist/agent/llm-service.d.ts

@@ -0,0 +1,9 @@
+import { LlmConfig, LlmMessage, LlmResponse } from './types';
+export declare class LlmService {
+    private config;
+    constructor(config?: LlmConfig);
+    chat(model?: string, messages?: LlmMessage[], temperature?: number, maxTokens?: number, stream?: boolean): Promise<LlmResponse>;
+    private callOllama;
+    private convertOllamaToOpenAiFormat;
+    private callOpenAi;
+}