agent-web-interface 4.1.1 → 4.2.0

package/dist/src/worker/port-allocator.js

@@ -0,0 +1,153 @@
+/**
+ * Port Allocator
+ *
+ * Manages allocation and release of ports for Chrome CDP endpoints.
+ * Tracks which ports are in use and provides the next available port.
+ */
+import { createServer } from 'net';
+import { WorkerError } from './errors/index.js';
+/**
+ * Manages port allocation for Chrome CDP endpoints.
+ *
+ * @example
+ * ```typescript
+ * const allocator = new PortAllocator({ min: 9300, max: 9399 });
+ *
+ * const port1 = allocator.allocate();  // 9300
+ * const port2 = allocator.allocate();  // 9301
+ *
+ * allocator.release(port1);            // Return 9300 to pool
+ * const port3 = allocator.allocate();  // 9300 (reused)
+ * ```
+ */
+export class PortAllocator {
+    min;
+    max;
+    allocatedPorts = new Set();
+    constructor(config) {
+        if (config.min > config.max) {
+            throw new Error(`Invalid port range: min (${config.min}) > max (${config.max})`);
+        }
+        if (config.min < 1 || config.max > 65535) {
+            throw new Error(`Port range must be between 1 and 65535`);
+        }
+        this.min = config.min;
+        this.max = config.max;
+    }
+    /**
+     * Get the port range configuration
+     */
+    get portRange() {
+        return { min: this.min, max: this.max };
+    }
+    /**
+     * Get the number of currently allocated ports
+     */
+    get allocatedCount() {
+        return this.allocatedPorts.size;
+    }
+    /**
+     * Get the total capacity (max possible allocations)
+     */
+    get capacity() {
+        return this.max - this.min + 1;
+    }
+    /**
+     * Allocate the next available port.
+     *
+     * @returns The allocated port number
+     * @throws WorkerError with PORT_EXHAUSTED if no ports are available
+     */
+    allocate() {
+        for (let port = this.min; port <= this.max; port++) {
+            if (!this.allocatedPorts.has(port)) {
+                this.allocatedPorts.add(port);
+                return port;
+            }
+        }
+        throw WorkerError.portExhausted(this.min, this.max, {
+            allocatedCount: this.allocatedPorts.size,
+            capacity: this.capacity,
+        });
+    }
+    /**
+     * Release a previously allocated port back to the pool.
+     *
+     * @param port - The port number to release
+     * @returns true if the port was released, false if it wasn't allocated
+     */
+    release(port) {
+        return this.allocatedPorts.delete(port);
+    }
+    /**
+     * Check if a specific port is currently allocated.
+     *
+     * @param port - The port number to check
+     * @returns true if the port is allocated
+     */
+    isAllocated(port) {
+        return this.allocatedPorts.has(port);
+    }
+    /**
+     * Check if a port is available for use by attempting to bind to it.
+     * This verifies that no other process is using the port.
+     *
+     * @param port - The port number to check
+     * @returns Promise that resolves to true if the port is available
+     */
+    async isPortAvailable(port) {
+        return new Promise((resolve) => {
+            const server = createServer();
+            server.once('error', () => {
+                resolve(false);
+            });
+            server.once('listening', () => {
+                server.close(() => {
+                    resolve(true);
+                });
+            });
+            server.listen(port, '127.0.0.1');
+        });
+    }
+    /**
+     * Allocate a port that is verified to be available on the system.
+     * This is slower than allocate() but ensures the port can actually be used.
+     *
+     * @returns Promise that resolves to the allocated port number
+     * @throws WorkerError with PORT_EXHAUSTED if no available ports are found
+     */
+    async allocateVerified() {
+        for (let port = this.min; port <= this.max; port++) {
+            if (!this.allocatedPorts.has(port)) {
+                // Reserve port before async check to prevent race condition
+                this.allocatedPorts.add(port);
+                const available = await this.isPortAvailable(port);
+                if (available) {
+                    return port;
+                }
+                // Release if port is not actually available on the system
+                this.allocatedPorts.delete(port);
+            }
+        }
+        throw WorkerError.portExhausted(this.min, this.max, {
+            allocatedCount: this.allocatedPorts.size,
+            capacity: this.capacity,
+            verified: true,
+        });
+    }
+    /**
+     * Get all currently allocated ports.
+     *
+     * @returns Array of allocated port numbers
+     */
+    getAllocatedPorts() {
+        return Array.from(this.allocatedPorts).sort((a, b) => a - b);
+    }
+    /**
+     * Reset the allocator, releasing all ports.
+     */
+    reset() {
+        this.allocatedPorts.clear();
+    }
+}
+//# sourceMappingURL=port-allocator.js.map

package/dist/src/worker/port-allocator.js.map

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

package/dist/src/worker/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Worker Module Types
+ *
+ * Type definitions for the Browser Worker Manager system.
+ * Manages tenant-bound Chrome workers with exclusive lease-based access control.
+ */
+/**
+ * Worker lifecycle states
+ */
+export type WorkerState = 'idle' | 'starting' | 'running' | 'stopping' | 'crashed' | 'stopped';
+/**
+ * Lease status values
+ */
+export type LeaseStatus = 'active' | 'expired' | 'revoked';
+/**
+ * Describes a Chrome worker instance
+ */
+export interface WorkerDescriptor {
+    /** Unique worker identifier */
+    workerId: string;
+    /** Tenant this worker is bound to */
+    tenantId: string;
+    /** Current worker state */
+    state: WorkerState;
+    /** CDP WebSocket endpoint (e.g., ws://127.0.0.1:9300/devtools/browser/...) */
+    cdpEndpoint?: string;
+    /** CDP port number */
+    port: number;
+    /** Chrome user data directory path */
+    profileDir: string;
+    /** Chrome process ID */
+    pid?: number;
+    /** When the worker was created */
+    createdAt: number;
+    /** When the worker was last used */
+    lastUsedAt: number;
+    /** When the worker started (state became 'running') */
+    startedAt?: number;
+}
+/**
+ * Describes an active lease on a worker
+ */
+export interface LeaseDescriptor {
+    /** Unique lease identifier */
+    leaseId: string;
+    /** Tenant holding the lease */
+    tenantId: string;
+    /** Worker being leased */
+    workerId: string;
+    /** When the lease was acquired */
+    acquiredAt: number;
+    /** When the lease expires (absolute timestamp) */
+    expiresAt: number;
+    /** Current lease status */
+    status: LeaseStatus;
+    /** Controller/session that holds the lease */
+    controllerId: string;
+}
+/**
+ * Result of attempting to acquire a lease
+ */
+export interface LeaseAcquisitionResult {
+    /** Whether the lease was acquired */
+    success: boolean;
+    /** The lease descriptor if successful */
+    lease?: LeaseDescriptor;
+    /** CDP endpoint if successful */
+    cdpEndpoint?: string;
+    /** Worker ID if successful */
+    workerId?: string;
+    /** Error message if unsuccessful */
+    error?: string;
+    /** Error code if unsuccessful */
+    errorCode?: string;
+}
+/**
+ * Configuration for the WorkerManager
+ */
+export interface WorkerManagerConfig {
+    /** Base directory for Chrome user data profiles */
+    profileBaseDir: string;
+    /** Time (ms) after which an idle worker is stopped */
+    idleTimeoutMs: number;
+    /** Maximum time (ms) a worker can run before forced restart */
+    hardTtlMs: number;
+    /** Default lease TTL (ms) */
+    leaseTtlMs: number;
+    /** Interval (ms) between health checks */
+    healthCheckIntervalMs: number;
+    /** Port range for CDP endpoints */
+    portRange: PortRange;
+    /** Maximum number of concurrent workers */
+    maxWorkers: number;
+    /** Path to Chrome executable (optional, auto-detected if not set) */
+    chromePath?: string;
+}
+/**
+ * Port range configuration
+ */
+export interface PortRange {
+    /** Minimum port number (inclusive) */
+    min: number;
+    /** Maximum port number (inclusive) */
+    max: number;
+}
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    /** Whether the worker is healthy */
+    healthy: boolean;
+    /** Response time in ms (if healthy) */
+    responseTimeMs?: number;
+    /** Error message (if unhealthy) */
+    error?: string;
+    /** CDP version info (if healthy) */
+    versionInfo?: CdpVersionInfo;
+}
+/**
+ * CDP /json/version response
+ */
+export interface CdpVersionInfo {
+    Browser: string;
+    'Protocol-Version': string;
+    'User-Agent': string;
+    'V8-Version': string;
+    'WebKit-Version': string;
+    webSocketDebuggerUrl: string;
+}
+/**
+ * Events emitted by ChromeWorkerProcess
+ */
+export interface WorkerProcessEvents {
+    /** Emitted when the process starts successfully */
+    started: {
+        pid: number;
+        cdpEndpoint: string;
+    };
+    /** Emitted when the process exits */
+    exit: {
+        code: number | null;
+        signal: string | null;
+    };
+    /** Emitted on process error */
+    error: {
+        error: Error;
+    };
+}
+/**
+ * Events emitted by HealthMonitor
+ */
+export interface HealthMonitorEvents {
+    /** Emitted when health state changes */
+    healthChange: {
+        workerId: string;
+        healthy: boolean;
+        result: HealthCheckResult;
+    };
+}
+/**
+ * Events emitted by WorkerManager
+ */
+export interface WorkerManagerEvents {
+    /** Emitted when a worker is created */
+    workerCreated: {
+        workerId: string;
+        tenantId: string;
+    };
+    /** Emitted when a worker starts */
+    workerStarted: {
+        workerId: string;
+        tenantId: string;
+        cdpEndpoint: string;
+    };
+    /** Emitted when a worker stops */
+    workerStopped: {
+        workerId: string;
+        tenantId: string;
+        reason: string;
+    };
+    /** Emitted when a worker crashes */
+    workerCrashed: {
+        workerId: string;
+        tenantId: string;
+        exitCode: number | null;
+    };
+    /** Emitted when a lease is acquired */
+    leaseAcquired: {
+        leaseId: string;
+        tenantId: string;
+        controllerId: string;
+    };
+    /** Emitted when a lease is released */
+    leaseReleased: {
+        leaseId: string;
+        tenantId: string;
+    };
+    /** Emitted when a lease expires */
+    leaseExpired: {
+        leaseId: string;
+        tenantId: string;
+    };
+    /** Emitted when a lease is revoked */
+    leaseRevoked: {
+        leaseId: string;
+        tenantId: string;
+        reason: string;
+    };
+}
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_WORKER_CONFIG: Omit<WorkerManagerConfig, 'profileBaseDir'>;
+/**
+ * Chrome launch arguments for worker processes
+ */
+export declare const CHROME_WORKER_ARGS: readonly ["--disable-background-networking", "--disable-client-side-phishing-detection", "--disable-default-apps", "--disable-extensions", "--disable-hang-monitor", "--disable-popup-blocking", "--disable-prompt-on-repost", "--disable-sync", "--disable-translate", "--metrics-recording-only", "--no-first-run", "--safebrowsing-disable-auto-update"];
+//# sourceMappingURL=types.d.ts.map

package/dist/src/worker/types.d.ts.map

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

package/dist/src/worker/types.js

@@ -0,0 +1,38 @@
+/**
+ * Worker Module Types
+ *
+ * Type definitions for the Browser Worker Manager system.
+ * Manages tenant-bound Chrome workers with exclusive lease-based access control.
+ */
+/**
+ * Default configuration values
+ */
+export const DEFAULT_WORKER_CONFIG = {
+    idleTimeoutMs: 300_000, // 5 minutes
+    hardTtlMs: 7_200_000, // 2 hours
+    leaseTtlMs: 300_000, // 5 minutes
+    healthCheckIntervalMs: 30_000, // 30 seconds
+    portRange: {
+        min: 9300,
+        max: 9399,
+    },
+    maxWorkers: 100,
+};
+/**
+ * Chrome launch arguments for worker processes
+ */
+export const CHROME_WORKER_ARGS = [
+    '--disable-background-networking',
+    '--disable-client-side-phishing-detection',
+    '--disable-default-apps',
+    '--disable-extensions',
+    '--disable-hang-monitor',
+    '--disable-popup-blocking',
+    '--disable-prompt-on-repost',
+    '--disable-sync',
+    '--disable-translate',
+    '--metrics-recording-only',
+    '--no-first-run',
+    '--safebrowsing-disable-auto-update',
+];
+//# sourceMappingURL=types.js.map

package/dist/src/worker/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/worker/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgLH;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgD;IAChF,aAAa,EAAE,OAAO,EAAE,YAAY;IACpC,SAAS,EAAE,SAAS,EAAE,UAAU;IAChC,UAAU,EAAE,OAAO,EAAE,YAAY;IACjC,qBAAqB,EAAE,MAAM,EAAE,aAAa;IAC5C,SAAS,EAAE;QACT,GAAG,EAAE,IAAI;QACT,GAAG,EAAE,IAAI;KACV;IACD,UAAU,EAAE,GAAG;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,iCAAiC;IACjC,0CAA0C;IAC1C,wBAAwB;IACxB,sBAAsB;IACtB,wBAAwB;IACxB,0BAA0B;IAC1B,4BAA4B;IAC5B,gBAAgB;IAChB,qBAAqB;IACrB,0BAA0B;IAC1B,gBAAgB;IAChB,oCAAoC;CAC5B,CAAC"}

package/dist/src/worker/worker-manager.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Worker Manager
+ *
+ * Main orchestrator for managing tenant-bound Chrome workers with exclusive
+ * lease-based access control. Coordinates worker lifecycle, health monitoring,
+ * and lease management.
+ */
+import { EventEmitter } from 'events';
+import type { WorkerManagerConfig, WorkerDescriptor, LeaseAcquisitionResult, WorkerManagerEvents } from './types.js';
+/**
+ * Type-safe EventEmitter for WorkerManager
+ */
+interface WorkerManagerEmitter {
+    on<K extends keyof WorkerManagerEvents>(event: K, listener: (data: WorkerManagerEvents[K]) => void): this;
+    once<K extends keyof WorkerManagerEvents>(event: K, listener: (data: WorkerManagerEvents[K]) => void): this;
+    emit<K extends keyof WorkerManagerEvents>(event: K, data: WorkerManagerEvents[K]): boolean;
+    off<K extends keyof WorkerManagerEvents>(event: K, listener: (data: WorkerManagerEvents[K]) => void): this;
+    removeAllListeners<K extends keyof WorkerManagerEvents>(event?: K): this;
+}
+/**
+ * Manages tenant-bound Chrome workers with exclusive lease-based access.
+ *
+ * @example
+ * ```typescript
+ * const manager = new WorkerManager({
+ *   profileBaseDir: '/var/lib/athena/profiles',
+ *   idleTimeoutMs: 300000,
+ *   hardTtlMs: 7200000,
+ *   leaseTtlMs: 300000,
+ *   healthCheckIntervalMs: 30000,
+ *   portRange: { min: 9300, max: 9399 },
+ *   maxWorkers: 100,
+ * });
+ *
+ * // Acquire a worker for a tenant
+ * const result = await manager.acquireForTenant('tenant-a', 'controller-1');
+ * if (result.success) {
+ *   console.log(`CDP endpoint: ${result.cdpEndpoint}`);
+ * }
+ *
+ * // Release when done
+ * manager.releaseLease('tenant-a');
+ *
+ * // Shutdown all workers
+ * await manager.shutdown();
+ * ```
+ */
+export declare class WorkerManager extends EventEmitter implements WorkerManagerEmitter {
+    private readonly config;
+    private readonly portAllocator;
+    private readonly healthMonitor;
+    private readonly leaseManager;
+    /** Worker entries by worker ID */
+    private readonly workers;
+    /** Tenant to worker ID mapping */
+    private readonly tenantToWorker;
+    private _isShuttingDown;
+    constructor(config: WorkerManagerConfig);
+    /**
+     * Get current worker count
+     */
+    get workerCount(): number;
+    /**
+     * Get current lease count
+     */
+    get leaseCount(): number;
+    /**
+     * Check if shutdown is in progress
+     */
+    get isShuttingDown(): boolean;
+    /**
+     * Acquire a worker for a tenant.
+     * Creates a new worker if one doesn't exist for the tenant.
+     *
+     * @param tenantId - Tenant identifier
+     * @param controllerId - Controller/session identifier
+     * @param ttlMs - Optional custom lease TTL
+     * @returns Lease acquisition result with CDP endpoint
+     */
+    acquireForTenant(tenantId: string, controllerId: string, ttlMs?: number): Promise<LeaseAcquisitionResult>;
+    /**
+     * Release a tenant's lease.
+     *
+     * @param tenantId - Tenant identifier
+     * @param controllerId - Optional controller ID to validate ownership
+     * @returns true if lease was released
+     */
+    releaseLease(tenantId: string, controllerId?: string): boolean;
+    /**
+     * Refresh a tenant's lease.
+     *
+     * @param tenantId - Tenant identifier
+     * @param ttlMs - Optional new TTL
+     * @returns true if lease was refreshed
+     */
+    refreshLease(tenantId: string, ttlMs?: number): boolean;
+    /**
+     * Get the CDP endpoint for a tenant's worker.
+     *
+     * @param tenantId - Tenant identifier
+     * @returns CDP endpoint URL or undefined if no active worker
+     */
+    getCdpEndpoint(tenantId: string): string | undefined;
+    /**
+     * Check if a tenant has an active lease.
+     */
+    hasActiveLease(tenantId: string): boolean;
+    /**
+     * Check if a specific controller holds the lease for a tenant.
+     */
+    isLeaseHeldBy(tenantId: string, controllerId: string): boolean;
+    /**
+     * Get worker descriptor for a tenant.
+     */
+    getWorkerForTenant(tenantId: string): WorkerDescriptor | undefined;
+    /**
+     * Stop a specific worker.
+     *
+     * @param tenantId - Tenant identifier
+     * @param reason - Reason for stopping
+     */
+    stopWorker(tenantId: string, reason: string): Promise<void>;
+    /**
+     * Shutdown the WorkerManager and all workers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Create a new worker for a tenant.
+     */
+    private createWorker;
+    /**
+     * Clean up a worker.
+     */
+    private cleanupWorker;
+    /**
+     * Set up event handlers for sub-components.
+     */
+    private setupEventHandlers;
+    /**
+     * Set up event handlers for a worker process.
+     */
+    private setupWorkerProcessHandlers;
+    /**
+     * Start idle timer for a worker.
+     */
+    private startIdleTimer;
+    /**
+     * Reset idle timer (on activity).
+     */
+    private resetIdleTimer;
+    /**
+     * Start hard TTL timer for a worker.
+     */
+    private startHardTtlTimer;
+}
+export {};
+//# sourceMappingURL=worker-manager.d.ts.map

package/dist/src/worker/worker-manager.d.ts.map

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