ats-daemon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MFS-code
+
+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,89 @@
+# ats-daemon
+
+Companion daemon for [Agent Testing Suite](https://github.com/MFS-code/ralph-testing-suite). Runs on your local machine, connects to the cloud server, manages Docker containers for agent test runs, and streams results back in real time.
+
+## Prerequisites
+
+- **Node.js 20+**
+- **Docker** installed and running (Docker Desktop or Docker Engine)
+- The `agent-runner:latest` Docker image built locally (see [setup instructions](https://github.com/MFS-code/ralph-testing-suite#quick-start))
+
+## Installation
+
+```bash
+npm install -g ats-daemon
+```
+
+## Usage
+
+1. Open the Agent Testing Suite web UI
+2. Create a test run and copy the pairing token
+3. Run the daemon:
+
+```bash
+ats-daemon --token <YOUR_PAIRING_TOKEN>
+```
+
+The daemon will:
+- Verify Docker is installed and running
+- Connect to the server via WebSocket
+- Wait for test commands
+- Spin up Docker containers for each agent setup
+- Stream container output back to the server for live metrics
+
+## Options
+
+```
+USAGE:
+  ats-daemon --token <TOKEN> [OPTIONS]
+
+REQUIRED:
+  --token <TOKEN>     Pairing token from the web UI
+
+OPTIONS:
+  --server <URL>      Server URL (default: ws://localhost:3001)
+  --help, -h          Show this help message
+  --version, -v       Show version
+```
+
+## API Keys
+
+API keys can be provided in two ways:
+
+1. **Environment variables** on the machine running the daemon:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+export GOOGLE_API_KEY=AI...
+export CURSOR_API_KEY=...
+ats-daemon --token abc123
+```
+
+2. **Via the web UI** -- keys entered in the browser are forwarded to the daemon over the WebSocket connection and injected into containers. They are never persisted on the server.
+
+Keys from the web UI take precedence over local environment variables.
+
+## What It Does
+
+The daemon is a thin orchestration layer:
+
+- Receives test configurations (setup files, model choice, instance count) from the server
+- Creates isolated Docker containers using the `agent-runner` image
+- Mounts setup files into each container
+- Streams container stdout/stderr back to the server line-by-line
+- Reports container lifecycle events (started, stopped, crashed, OOM)
+- Enforces resource limits (4GB memory, 2 CPUs, 100 PIDs per container)
+- Handles graceful shutdown on SIGINT/SIGTERM
+
+## Security
+
+- Containers run with enforced resource limits (memory, CPU, PIDs)
+- Setup files are written to a temp directory with path traversal protection
+- API keys are only held in memory, never written to disk by the daemon
+- Containers use an isolated Docker network (`agent-network`)
+- The daemon connects outbound to the server (no inbound ports needed)
+
+## License
+
+MIT

package/dist/connection.d.ts

@@ -0,0 +1,37 @@
+/**
+ * WebSocket Client - connects the daemon to the cloud server
+ *
+ * Handles:
+ * - Outbound connection to server (user's machine -> cloud)
+ * - Automatic reconnection with exponential backoff
+ * - Sending daemon events (container output, status changes)
+ * - Receiving server commands (start test, stop instance, etc.)
+ */
+import type { ServerToDaemonMessage, DaemonToServerMessage } from './shared/protocol.js';
+export interface ConnectionConfig {
+    /** Server URL (e.g., wss://my-server.example.com or ws://localhost:3001) */
+    serverUrl: string;
+    /** Pairing token from the web UI */
+    token: string;
+    /** Which API keys are available locally */
+    localApiKeys: {
+        anthropic: boolean;
+        openai: boolean;
+        google: boolean;
+        cursor: boolean;
+    };
+}
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+export interface ServerConnection {
+    /** Current connection state */
+    state: ConnectionState;
+    /** Send a message to the server */
+    send: (message: DaemonToServerMessage) => void;
+    /** Register a handler for incoming server commands */
+    onCommand: (handler: (message: ServerToDaemonMessage) => void) => void;
+    /** Register a handler for connection state changes */
+    onStateChange: (handler: (state: ConnectionState) => void) => void;
+    /** Gracefully close the connection */
+    close: () => void;
+}
+export declare function connectToServer(config: ConnectionConfig): ServerConnection;

package/dist/connection.js

@@ -0,0 +1,153 @@
+/**
+ * WebSocket Client - connects the daemon to the cloud server
+ *
+ * Handles:
+ * - Outbound connection to server (user's machine -> cloud)
+ * - Automatic reconnection with exponential backoff
+ * - Sending daemon events (container output, status changes)
+ * - Receiving server commands (start test, stop instance, etc.)
+ */
+import WebSocket from 'ws';
+import { DAEMON_WS_PATH, PROTOCOL_VERSION } from './shared/protocol.js';
+import { getDockerStatus } from './docker/checker.js';
+import os from 'os';
+// ---------------------------------------------------------------------------
+// Connection implementation
+// ---------------------------------------------------------------------------
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 30000;
+const HEARTBEAT_INTERVAL_MS = 15000;
+export function connectToServer(config) {
+    let ws = null;
+    let state = 'disconnected';
+    let reconnectAttempt = 0;
+    let reconnectTimer = null;
+    let heartbeatTimer = null;
+    let intentionalClose = false;
+    const startTime = Date.now();
+    const commandHandlers = [];
+    const stateHandlers = [];
+    function setState(newState) {
+        if (state === newState)
+            return;
+        state = newState;
+        for (const handler of stateHandlers) {
+            try {
+                handler(newState);
+            }
+            catch { /* ignore handler errors */ }
+        }
+    }
+    function send(message) {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(message));
+        }
+    }
+    async function buildHello() {
+        const dockerStatus = await getDockerStatus();
+        return {
+            type: 'daemon_hello',
+            daemonVersion: PROTOCOL_VERSION,
+            docker: {
+                installed: dockerStatus.installed,
+                running: dockerStatus.running,
+                version: dockerStatus.version,
+            },
+            localApiKeys: config.localApiKeys,
+            platform: os.platform(),
+            arch: os.arch(),
+        };
+    }
+    function startHeartbeat() {
+        stopHeartbeat();
+        heartbeatTimer = setInterval(() => {
+            const pong = {
+                type: 'daemon_pong',
+                timestamp: Date.now(),
+                uptimeMs: Date.now() - startTime,
+                activeContainers: 0, // Will be updated by the caller
+            };
+            send(pong);
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    function stopHeartbeat() {
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+        }
+    }
+    function connect() {
+        if (intentionalClose)
+            return;
+        setState('connecting');
+        const url = `${config.serverUrl}${DAEMON_WS_PATH}?token=${encodeURIComponent(config.token)}`;
+        ws = new WebSocket(url);
+        ws.on('open', async () => {
+            console.log('[DAEMON] Connected to server');
+            reconnectAttempt = 0;
+            setState('connected');
+            // Send hello
+            const hello = await buildHello();
+            send(hello);
+            startHeartbeat();
+        });
+        ws.on('message', (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                for (const handler of commandHandlers) {
+                    try {
+                        handler(message);
+                    }
+                    catch (err) {
+                        console.error('[DAEMON] Command handler error:', err);
+                    }
+                }
+            }
+            catch {
+                console.error('[DAEMON] Failed to parse server message');
+            }
+        });
+        ws.on('close', (code, reason) => {
+            stopHeartbeat();
+            if (intentionalClose) {
+                setState('disconnected');
+                return;
+            }
+            console.log(`[DAEMON] Disconnected (code=${code}, reason=${reason?.toString() || 'none'}). Reconnecting...`);
+            setState('disconnected');
+            scheduleReconnect();
+        });
+        ws.on('error', (err) => {
+            console.error('[DAEMON] WebSocket error:', err.message);
+            setState('error');
+        });
+    }
+    function scheduleReconnect() {
+        if (intentionalClose)
+            return;
+        const delay = Math.min(RECONNECT_BASE_MS * Math.pow(2, reconnectAttempt), RECONNECT_MAX_MS);
+        reconnectAttempt++;
+        console.log(`[DAEMON] Reconnecting in ${delay}ms (attempt ${reconnectAttempt})...`);
+        reconnectTimer = setTimeout(connect, delay);
+    }
+    // Start initial connection
+    connect();
+    return {
+        get state() { return state; },
+        send,
+        onCommand(handler) { commandHandlers.push(handler); },
+        onStateChange(handler) { stateHandlers.push(handler); },
+        close() {
+            intentionalClose = true;
+            stopHeartbeat();
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            if (ws) {
+                ws.close(1000, 'Daemon shutting down');
+                ws = null;
+            }
+            setState('disconnected');
+        },
+    };
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/docker/checker.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Docker Availability Checker (Daemon version)
+ *
+ * Checks Docker availability on the USER's local machine.
+ * Unlike the server version, this connects to the default Docker socket
+ * (/var/run/docker.sock) since the daemon runs on the user's machine
+ * where Docker Desktop / Docker Engine is installed.
+ *
+ * No DOCKER_HOST gating here -- the user's local Docker IS the target.
+ */
+import Docker from 'dockerode';
+export interface DockerStatus {
+    installed: boolean;
+    running: boolean;
+    version: string | null;
+    error?: string;
+}
+/**
+ * Create a dockerode instance using default connection.
+ * On Linux: /var/run/docker.sock
+ * On macOS: /var/run/docker.sock (Docker Desktop)
+ * On Windows: //./pipe/docker_engine (Docker Desktop)
+ *
+ * dockerode auto-detects the right socket for the platform.
+ */
+export declare function createDockerClient(): Docker;
+/**
+ * Check if Docker CLI is installed
+ */
+export declare function isDockerInstalled(): Promise<boolean>;
+/**
+ * Check if Docker daemon is running
+ */
+export declare function isDockerRunning(): Promise<boolean>;
+/**
+ * Get Docker version string
+ */
+export declare function getDockerVersion(): Promise<string | null>;
+/**
+ * Get comprehensive Docker status on the local machine
+ */
+export declare function getDockerStatus(): Promise<DockerStatus>;
+/**
+ * Verify Docker is available, throw if not
+ */
+export declare function verifyDockerAvailable(): Promise<void>;
+/**
+ * Check if the agent-runner image exists locally
+ */
+export declare function isAgentRunnerImageAvailable(): Promise<boolean>;

package/dist/docker/checker.js

@@ -0,0 +1,131 @@
+/**
+ * Docker Availability Checker (Daemon version)
+ *
+ * Checks Docker availability on the USER's local machine.
+ * Unlike the server version, this connects to the default Docker socket
+ * (/var/run/docker.sock) since the daemon runs on the user's machine
+ * where Docker Desktop / Docker Engine is installed.
+ *
+ * No DOCKER_HOST gating here -- the user's local Docker IS the target.
+ */
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import Docker from 'dockerode';
+const execAsync = promisify(exec);
+const COMMAND_TIMEOUT_MS = 5000;
+const DOCKER_PING_TIMEOUT_MS = 3000;
+/**
+ * Create a dockerode instance using default connection.
+ * On Linux: /var/run/docker.sock
+ * On macOS: /var/run/docker.sock (Docker Desktop)
+ * On Windows: //./pipe/docker_engine (Docker Desktop)
+ *
+ * dockerode auto-detects the right socket for the platform.
+ */
+export function createDockerClient() {
+    return new Docker();
+}
+/**
+ * Ping the local Docker daemon
+ */
+async function pingDockerDaemon() {
+    const docker = createDockerClient();
+    const timeout = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Docker ping timeout')), DOCKER_PING_TIMEOUT_MS);
+    });
+    try {
+        await Promise.race([docker.ping(), timeout]);
+        return { running: true };
+    }
+    catch (error) {
+        return {
+            running: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Check if Docker CLI is installed
+ */
+export async function isDockerInstalled() {
+    try {
+        await execAsync('docker --version', { timeout: COMMAND_TIMEOUT_MS });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if Docker daemon is running
+ */
+export async function isDockerRunning() {
+    const status = await pingDockerDaemon();
+    return status.running;
+}
+/**
+ * Get Docker version string
+ */
+export async function getDockerVersion() {
+    try {
+        const { stdout } = await execAsync('docker --version', { timeout: COMMAND_TIMEOUT_MS });
+        const match = stdout.match(/Docker version ([^\s,]+)/);
+        if (match && match[1]) {
+            return match[1];
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get comprehensive Docker status on the local machine
+ */
+export async function getDockerStatus() {
+    const status = {
+        installed: false,
+        running: false,
+        version: null,
+    };
+    status.installed = await isDockerInstalled();
+    if (!status.installed) {
+        status.error = 'Docker is not installed. Install Docker Desktop from https://docker.com/get-started';
+        return status;
+    }
+    status.version = await getDockerVersion();
+    const daemonStatus = await pingDockerDaemon();
+    status.running = daemonStatus.running;
+    if (!status.running) {
+        const detail = daemonStatus.error ? ` (${daemonStatus.error})` : '';
+        status.error = `Docker daemon is not running. Start Docker Desktop and try again.${detail}`;
+        return status;
+    }
+    return status;
+}
+/**
+ * Verify Docker is available, throw if not
+ */
+export async function verifyDockerAvailable() {
+    const status = await getDockerStatus();
+    if (!status.installed) {
+        throw new Error(status.error || 'Docker is not installed.');
+    }
+    if (!status.running) {
+        throw new Error(status.error || 'Docker daemon is not running.');
+    }
+}
+/**
+ * Check if the agent-runner image exists locally
+ */
+export async function isAgentRunnerImageAvailable() {
+    const docker = createDockerClient();
+    try {
+        await docker.getImage('agent-runner:latest').inspect();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=checker.js.map

package/dist/docker/checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.js","sourceRoot":"","sources":["../../src/docker/checker.ts"],"names":[],"mappings":"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"}

package/dist/docker/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Daemon Docker module exports
+ */
+export { createDockerClient, isDockerInstalled, isDockerRunning, getDockerVersion, getDockerStatus, verifyDockerAvailable, isAgentRunnerImageAvailable, } from './checker.js';
+export type { DockerStatus } from './checker.js';
+export { ContainerManager, DockerUnavailableError } from './manager.js';
+export type { ContainerConfig, ContainerInfo, ContainerEvent, ContainerEventType, ContainerHealthStatus, } from './manager.js';

package/dist/docker/index.js

@@ -0,0 +1,6 @@
+/**
+ * Daemon Docker module exports
+ */
+export { createDockerClient, isDockerInstalled, isDockerRunning, getDockerVersion, getDockerStatus, verifyDockerAvailable, isAgentRunnerImageAvailable, } from './checker.js';
+export { ContainerManager, DockerUnavailableError } from './manager.js';
+//# sourceMappingURL=index.js.map

package/dist/docker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/docker/manager.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Container Manager (Daemon version)
+ *
+ * Manages Docker container lifecycle on the user's local machine.
+ * - Connects to local Docker (default socket)
+ * - Streams output back to the cloud server via a callback
+ * - Receives commands from the server, not directly from the UI
+ * - Subscribes to Docker events for OOM / crash detection
+ */
+import { EventEmitter } from 'events';
+import type { ModelId, InstanceStatus, SetupId, ProviderMode } from '../shared/types.js';
+/**
+ * Error thrown when Docker is not available
+ */
+export declare class DockerUnavailableError extends Error {
+    constructor();
+}
+export interface ContainerConfig {
+    instanceId: string;
+    setupId: SetupId;
+    setupName: string;
+    model: ModelId;
+    providerMode: ProviderMode;
+    /** Absolute path to entrypoint / wrapper scripts */
+    scriptsPath?: string;
+    /** Absolute path to the directory containing setup files */
+    filesPath: string;
+    /** Absolute path for container output */
+    outputPath: string;
+    apiKeys: {
+        anthropic?: string;
+        openai?: string;
+        google?: string;
+        cursor?: string;
+    };
+    gitRemoteUrl?: string;
+    networkName?: string;
+    timeoutMs?: number;
+}
+export interface ContainerInfo {
+    instanceId: string;
+    setupId: SetupId;
+    containerId: string;
+    status: InstanceStatus;
+    startTime?: number;
+    endTime?: number;
+    exitCode?: number;
+    exitType?: 'complete' | 'timeout' | 'crash' | 'stopped';
+}
+/**
+ * Container health status with resource usage
+ * Used for periodic health check logging
+ */
+export interface ContainerHealthStatus {
+    instanceId: string;
+    containerId: string;
+    status: InstanceStatus;
+    uptimeMs: number;
+    memoryUsageBytes?: number;
+    memoryLimitBytes?: number;
+    memoryPercent?: number;
+    cpuPercent?: number;
+}
+export type ContainerEventType = 'created' | 'started' | 'output' | 'commit' | 'status_change' | 'stopped' | 'error' | 'cleanup';
+export interface ContainerEvent {
+    type: ContainerEventType;
+    instanceId: string;
+    setupId: SetupId;
+    containerId: string;
+    timestamp: number;
+    data?: unknown;
+}
+export declare class ContainerManager extends EventEmitter {
+    private docker;
+    private containers;
+    private containerInfo;
+    private timeouts;
+    private isListeningToEvents;
+    private constructor();
+    /**
+     * Factory – verifies Docker is available before returning a manager
+     */
+    static create(): Promise<ContainerManager>;
+    /**
+     * Ping Docker daemon
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Create and start a container, streaming output via onOutput callback
+     */
+    runContainer(config: ContainerConfig, onOutput: (line: string) => void): Promise<ContainerInfo>;
+    stopContainer(instanceId: string): Promise<void>;
+    pauseContainer(instanceId: string): Promise<boolean>;
+    resumeContainer(instanceId: string): Promise<boolean>;
+    cleanupContainer(instanceId: string): Promise<void>;
+    cleanupAll(): Promise<void>;
+    /**
+     * Get resource usage stats for a running container
+     */
+    getResourceUsage(instanceId: string): Promise<{
+        memoryUsageBytes: number;
+        memoryLimitBytes: number;
+        memoryPercent: number;
+        cpuPercent: number;
+    } | null>;
+    getContainerInfo(instanceId: string): ContainerInfo | undefined;
+    getAllContainerInfo(): ContainerInfo[];
+    getActiveCount(): number;
+    /**
+     * Check if a container is paused via Docker inspect
+     */
+    isContainerPaused(instanceId: string): Promise<boolean>;
+    /**
+     * Subscribe to Docker events for OOM / crash detection
+     */
+    subscribeToDockerEvents(): Promise<void>;
+    /**
+     * Get health status for all containers including resource usage
+     */
+    getContainerHealthStatus(): Promise<ContainerHealthStatus[]>;
+    /**
+     * Parse commit line from git hook output
+     * Format: AGENT_COMMIT:hash:message:insertions deletions
+     */
+    static parseCommitLine(line: string): {
+        hash: string;
+        message: string;
+        stats: string;
+    };
+    /** Format uptime in human-readable format */
+    static formatUptime(uptimeMs: number): string;
+    /** Format bytes in human-readable format */
+    static formatBytes(bytes: number): string;
+    private monitorCompletion;
+    private handleTimeout;
+    private clearTimeout;
+    private emitEvent;
+}