agent-relay 2.0.6 → 2.0.7

package/packages/resiliency/dist/cgroup-manager.js

@@ -0,0 +1,394 @@
+/**
+ * CgroupManager - Manage CPU limits for agents using Linux cgroups v2
+ *
+ * Provides per-agent CPU isolation to prevent one agent (e.g., running npm install)
+ * from starving other agents of CPU resources.
+ *
+ * Features:
+ * - Auto-detects cgroups v2 availability
+ * - Creates per-agent cgroups with CPU limits
+ * - Gracefully degrades when cgroups unavailable
+ * - Cleans up cgroups when agents exit
+ *
+ * Usage:
+ * ```typescript
+ * const manager = getCgroupManager();
+ * await manager.createAgentCgroup('worker1', { cpuPercent: 50 });
+ * await manager.addProcess('worker1', pid);
+ * // ... agent runs with CPU limit ...
+ * await manager.removeAgentCgroup('worker1');
+ * ```
+ *
+ * Requirements:
+ * - Linux with cgroups v2 (unified hierarchy)
+ * - Write access to cgroup directory (delegated or root)
+ * - cpu controller enabled in cgroup
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { EventEmitter } from 'node:events';
+/**
+ * Default cgroup base path for agent-relay
+ */
+const DEFAULT_CGROUP_BASE = '/sys/fs/cgroup/agent-relay';
+/**
+ * Default CPU settings
+ */
+const DEFAULT_CPU_PERCENT = 100; // 100% of one core
+const DEFAULT_CPU_PERIOD_US = 100000; // 100ms period
+/**
+ * CgroupManager singleton for managing agent CPU limits
+ */
+export class CgroupManager extends EventEmitter {
+    cgroupBase;
+    available;
+    agentCgroups = new Map();
+    initialized = false;
+    constructor(cgroupBase = DEFAULT_CGROUP_BASE) {
+        super();
+        this.cgroupBase = cgroupBase;
+        this.available = false;
+    }
+    /**
+     * Initialize the cgroup manager and detect availability
+     */
+    async initialize() {
+        if (this.initialized) {
+            return this.available;
+        }
+        this.initialized = true;
+        this.available = await this.detectCgroupsV2();
+        if (this.available) {
+            // Ensure base directory exists
+            try {
+                await this.ensureBaseCgroup();
+            }
+            catch (err) {
+                console.warn(`[cgroup-manager] Failed to create base cgroup: ${err.message}`);
+                this.available = false;
+            }
+        }
+        return this.available;
+    }
+    /**
+     * Check if cgroups v2 is available and we have write access
+     */
+    async detectCgroupsV2() {
+        // Check for cgroups v2 unified hierarchy
+        const cgroupRoot = '/sys/fs/cgroup';
+        // Check if cgroup2 is mounted (unified hierarchy)
+        if (!existsSync(join(cgroupRoot, 'cgroup.controllers'))) {
+            console.info('[cgroup-manager] cgroups v2 not detected (no unified hierarchy)');
+            return false;
+        }
+        // Check if cpu controller is available
+        try {
+            const controllers = readFileSync(join(cgroupRoot, 'cgroup.controllers'), 'utf-8');
+            if (!controllers.includes('cpu')) {
+                console.info('[cgroup-manager] CPU controller not available in cgroups');
+                return false;
+            }
+        }
+        catch (err) {
+            console.info(`[cgroup-manager] Cannot read cgroup controllers: ${err.message}`);
+            return false;
+        }
+        // Check if we can write to cgroup directory
+        // In production, agent-relay cgroup should be pre-created with proper delegation
+        try {
+            const testPath = join(cgroupRoot, 'agent-relay-test-' + process.pid);
+            mkdirSync(testPath, { recursive: true });
+            rmSync(testPath, { recursive: true, force: true });
+            console.info('[cgroup-manager] cgroups v2 available with write access');
+            return true;
+        }
+        catch (err) {
+            // Try delegated cgroup path
+            if (existsSync(this.cgroupBase)) {
+                console.info('[cgroup-manager] Using delegated cgroup at ' + this.cgroupBase);
+                return true;
+            }
+            console.info(`[cgroup-manager] No write access to cgroups: ${err.message}`);
+            return false;
+        }
+    }
+    /**
+     * Ensure base cgroup directory exists with proper controllers
+     */
+    async ensureBaseCgroup() {
+        if (!existsSync(this.cgroupBase)) {
+            mkdirSync(this.cgroupBase, { recursive: true });
+        }
+        // Enable cpu controller in subtree
+        const subtreeControlPath = join(this.cgroupBase, 'cgroup.subtree_control');
+        if (existsSync(subtreeControlPath)) {
+            try {
+                writeFileSync(subtreeControlPath, '+cpu');
+            }
+            catch {
+                // Controller might already be enabled or not available
+            }
+        }
+    }
+    /**
+     * Check if cgroups are available
+     */
+    isAvailable() {
+        return this.available;
+    }
+    /**
+     * Create a cgroup for an agent with CPU limits
+     *
+     * @param agentName - Unique agent identifier
+     * @param config - CPU limit configuration
+     * @returns true if cgroup was created, false if not available
+     */
+    async createAgentCgroup(agentName, config = {}) {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        if (!this.available) {
+            return false;
+        }
+        // Validate agent name (no path traversal)
+        if (agentName.includes('/') || agentName.includes('..')) {
+            throw new Error(`Invalid agent name: ${agentName}`);
+        }
+        const cgroupPath = join(this.cgroupBase, agentName);
+        try {
+            // Create cgroup directory
+            if (!existsSync(cgroupPath)) {
+                mkdirSync(cgroupPath, { recursive: true });
+            }
+            // Configure CPU limit
+            const cpuPercent = config.cpuPercent ?? DEFAULT_CPU_PERCENT;
+            const cpuPeriodUs = config.cpuPeriodUs ?? DEFAULT_CPU_PERIOD_US;
+            // cpu.max format: "$MAX $PERIOD" in microseconds
+            // For 50% of one CPU: "50000 100000" (50ms max per 100ms period)
+            const cpuMaxUs = Math.floor((cpuPercent / 100) * cpuPeriodUs);
+            const cpuMaxValue = `${cpuMaxUs} ${cpuPeriodUs}`;
+            writeFileSync(join(cgroupPath, 'cpu.max'), cpuMaxValue);
+            // Track the cgroup
+            const info = {
+                name: agentName,
+                path: cgroupPath,
+                pids: [],
+                cpuLimit: { cpuPercent, cpuPeriodUs },
+                createdAt: Date.now(),
+            };
+            this.agentCgroups.set(agentName, info);
+            this.emit('cgroup-created', { agentName, path: cgroupPath, cpuPercent });
+            console.info(`[cgroup-manager] Created cgroup for ${agentName} with ${cpuPercent}% CPU limit`);
+            return true;
+        }
+        catch (err) {
+            const error = new Error(`Failed to create cgroup for ${agentName}: ${err.message}`);
+            this.emit('error', error);
+            console.warn(`[cgroup-manager] ${error.message}`);
+            return false;
+        }
+    }
+    /**
+     * Add a process to an agent's cgroup
+     *
+     * @param agentName - Agent name
+     * @param pid - Process ID to add
+     * @returns true if process was added
+     */
+    async addProcess(agentName, pid) {
+        if (!this.available) {
+            return false;
+        }
+        const info = this.agentCgroups.get(agentName);
+        if (!info) {
+            console.warn(`[cgroup-manager] No cgroup found for agent ${agentName}`);
+            return false;
+        }
+        try {
+            // Write PID to cgroup.procs
+            writeFileSync(join(info.path, 'cgroup.procs'), String(pid));
+            info.pids.push(pid);
+            this.emit('process-added', { agentName, pid });
+            console.info(`[cgroup-manager] Added process ${pid} to cgroup ${agentName}`);
+            return true;
+        }
+        catch (err) {
+            console.warn(`[cgroup-manager] Failed to add process ${pid} to cgroup ${agentName}: ${err.message}`);
+            return false;
+        }
+    }
+    /**
+     * Remove an agent's cgroup
+     *
+     * @param agentName - Agent name
+     * @returns true if cgroup was removed
+     */
+    async removeAgentCgroup(agentName) {
+        if (!this.available) {
+            return false;
+        }
+        const info = this.agentCgroups.get(agentName);
+        if (!info) {
+            return false;
+        }
+        try {
+            // Move processes to parent cgroup first (required before removal)
+            const parentProcs = join(this.cgroupBase, 'cgroup.procs');
+            for (const pid of info.pids) {
+                try {
+                    writeFileSync(parentProcs, String(pid));
+                }
+                catch {
+                    // Process might have exited
+                }
+            }
+            // Remove the cgroup directory
+            rmSync(info.path, { recursive: true, force: true });
+            this.agentCgroups.delete(agentName);
+            this.emit('cgroup-removed', { agentName });
+            console.info(`[cgroup-manager] Removed cgroup for ${agentName}`);
+            return true;
+        }
+        catch (err) {
+            console.warn(`[cgroup-manager] Failed to remove cgroup ${agentName}: ${err.message}`);
+            return false;
+        }
+    }
+    /**
+     * Update CPU limit for an existing agent cgroup
+     *
+     * @param agentName - Agent name
+     * @param cpuPercent - New CPU percentage limit
+     */
+    async updateCpuLimit(agentName, cpuPercent) {
+        if (!this.available) {
+            return false;
+        }
+        const info = this.agentCgroups.get(agentName);
+        if (!info) {
+            return false;
+        }
+        try {
+            const cpuPeriodUs = info.cpuLimit.cpuPeriodUs ?? DEFAULT_CPU_PERIOD_US;
+            const cpuMaxUs = Math.floor((cpuPercent / 100) * cpuPeriodUs);
+            const cpuMaxValue = `${cpuMaxUs} ${cpuPeriodUs}`;
+            writeFileSync(join(info.path, 'cpu.max'), cpuMaxValue);
+            info.cpuLimit.cpuPercent = cpuPercent;
+            console.info(`[cgroup-manager] Updated CPU limit for ${agentName} to ${cpuPercent}%`);
+            return true;
+        }
+        catch (err) {
+            console.warn(`[cgroup-manager] Failed to update CPU limit for ${agentName}: ${err.message}`);
+            return false;
+        }
+    }
+    /**
+     * Get current CPU usage for an agent (if available)
+     *
+     * @param agentName - Agent name
+     * @returns CPU usage stats or null
+     */
+    getCpuStats(agentName) {
+        if (!this.available) {
+            return null;
+        }
+        const info = this.agentCgroups.get(agentName);
+        if (!info) {
+            return null;
+        }
+        try {
+            const statPath = join(info.path, 'cpu.stat');
+            if (!existsSync(statPath)) {
+                return null;
+            }
+            const stat = readFileSync(statPath, 'utf-8');
+            const lines = stat.trim().split('\n');
+            const stats = {};
+            for (const line of lines) {
+                const [key, value] = line.split(' ');
+                stats[key] = parseInt(value, 10);
+            }
+            return {
+                usageUsec: stats['usage_usec'] ?? 0,
+                throttledUsec: stats['throttled_usec'] ?? 0,
+                periods: stats['nr_periods'] ?? 0,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get info about all agent cgroups
+     */
+    getAllAgentCgroups() {
+        return Array.from(this.agentCgroups.values());
+    }
+    /**
+     * Clean up orphaned cgroups (e.g., after crash)
+     */
+    async cleanupOrphanedCgroups() {
+        if (!this.available || !existsSync(this.cgroupBase)) {
+            return 0;
+        }
+        let cleaned = 0;
+        try {
+            const entries = readdirSync(this.cgroupBase, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                // Skip if we're tracking this cgroup
+                if (this.agentCgroups.has(entry.name))
+                    continue;
+                // Try to remove orphaned cgroup
+                try {
+                    const cgroupPath = join(this.cgroupBase, entry.name);
+                    rmSync(cgroupPath, { recursive: true, force: true });
+                    cleaned++;
+                    console.info(`[cgroup-manager] Cleaned up orphaned cgroup: ${entry.name}`);
+                }
+                catch {
+                    // Might still have processes
+                }
+            }
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        return cleaned;
+    }
+    /**
+     * Shutdown and clean up all cgroups
+     */
+    async shutdown() {
+        for (const [agentName] of this.agentCgroups) {
+            await this.removeAgentCgroup(agentName);
+        }
+    }
+}
+// Singleton instance
+let cgroupManagerInstance = null;
+/**
+ * Get the singleton CgroupManager instance
+ */
+export function getCgroupManager(cgroupBase) {
+    if (!cgroupManagerInstance) {
+        cgroupManagerInstance = new CgroupManager(cgroupBase);
+    }
+    return cgroupManagerInstance;
+}
+/**
+ * Format bytes for display
+ */
+export function formatCpuTime(usec) {
+    if (usec < 1000) {
+        return `${usec}µs`;
+    }
+    else if (usec < 1000000) {
+        return `${(usec / 1000).toFixed(2)}ms`;
+    }
+    else {
+        return `${(usec / 1000000).toFixed(2)}s`;
+    }
+}
+//# sourceMappingURL=cgroup-manager.js.map

package/packages/resiliency/dist/index.d.ts

@@ -65,4 +65,5 @@ export { CrashInsightsService, getCrashInsights, type CrashRecord, type CrashAna
 export { StatelessLeadCoordinator, createStatelessLead, type BeadsTask, type LeadHeartbeat, type StatelessLeadConfig, } from './stateless-lead.js';
 export { LeaderWatchdog, createLeaderWatchdog, type LeaderWatchdogConfig, type ElectionResult, } from './leader-watchdog.js';
 export { GossipHealthMonitor, createGossipHealth, type GossipHeartbeat, type PeerHealth, type GossipHealthConfig, } from './gossip-health.js';
+export { CgroupManager, getCgroupManager, formatCpuTime, type CpuLimitConfig, type AgentCgroupInfo, } from './cgroup-manager.js';
 //# sourceMappingURL=index.d.ts.map

package/packages/resiliency/dist/index.js

@@ -65,4 +65,5 @@ export { CrashInsightsService, getCrashInsights, } from './crash-insights.js';
 export { StatelessLeadCoordinator, createStatelessLead, } from './stateless-lead.js';
 export { LeaderWatchdog, createLeaderWatchdog, } from './leader-watchdog.js';
 export { GossipHealthMonitor, createGossipHealth, } from './gossip-health.js';
+export { CgroupManager, getCgroupManager, formatCpuTime, } from './cgroup-manager.js';
 //# sourceMappingURL=index.js.map

package/packages/resiliency/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/resiliency",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Health monitoring, logging, metrics, and crash resilience utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Lightweight SDK for agent-to-agent communication via Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.6"
+    "@agent-relay/protocol": "2.0.7"
   },
   "engines": {
     "node": ">=18.0.0"

package/packages/spawner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/spawner",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Agent spawning types and utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/state",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Agent state persistence for non-hook CLIs (Codex, Gemini, etc.)",
   "type": "module",
   "main": "dist/index.js",

package/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/storage",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Storage adapters and interfaces for Relay message/session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.6"
+    "@agent-relay/protocol": "2.0.7"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "2.0.6"
+    "@agent-relay/config": "2.0.7"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/resiliency": "2.0.6"
+    "@agent-relay/resiliency": "2.0.7"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/index.js",

package/packages/wrapper/dist/relay-pty-orchestrator.d.ts

@@ -42,6 +42,8 @@ export interface RelayPtyOrchestratorConfig extends BaseWrapperConfig {
     debug?: boolean;
     /** Force headless mode (use pipes instead of inheriting TTY) */
     headless?: boolean;
+    /** CPU limit percentage per agent (1-100 per core, e.g., 50 = 50% of one core). Requires cgroups v2. */
+    cpuLimitPercent?: number;
 }
 /**
  * Events emitted by RelayPtyOrchestrator
@@ -109,6 +111,8 @@ export declare class RelayPtyOrchestrator extends BaseWrapper {
     private isGracefulStop;
     private memoryMonitor;
     private memoryAlertHandler;
+    private cgroupManager;
+    private hasCgroupSetup;
     constructor(config: RelayPtyOrchestratorConfig);
     /**
      * Debug log - only outputs when debug is enabled
@@ -146,6 +150,10 @@ export declare class RelayPtyOrchestrator extends BaseWrapper {
      * Spawn the relay-pty process
      */
     private spawnRelayPty;
+    /**
+     * Set up cgroup CPU limit for this agent
+     */
+    private setupCgroupLimit;
     /**
      * Handle output from relay-pty stdout (headless mode only)
      * In interactive mode, stdout goes directly to terminal via inherited stdio
@@ -223,10 +231,6 @@ export declare class RelayPtyOrchestrator extends BaseWrapper {
      * Inject a message into the agent via socket
      */
     private injectMessage;
-    /** Maximum retries for failed injections before giving up */
-    private static readonly MAX_INJECTION_RETRIES;
-    /** Backoff delay multiplier (ms) for retries: delay = BASE * 2^retryCount */
-    private static readonly INJECTION_RETRY_BASE_MS;
     /**
      * Process queued messages
      */