agent-relay 1.0.22 → 1.2.0

package/dist/resiliency/stateless-lead.js

@@ -0,0 +1,308 @@
+/**
+ * Stateless Lead Coordinator
+ *
+ * Implements P0: Lead reads from Beads, no in-memory task queue.
+ * All task state lives in Beads. If lead crashes, new lead picks up.
+ *
+ * Key principles:
+ * - Lead is a coordinator, not a state holder
+ * - Beads is the single source of truth for task state
+ * - Any agent can become lead by reading from Beads
+ * - Tasks are assigned by updating Beads, not in-memory
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { EventEmitter } from 'events';
+const DEFAULT_CONFIG = {
+    pollIntervalMs: 5000,
+    heartbeatIntervalMs: 10000,
+    leaseDurationMs: 300000, // 5 minutes
+};
+/**
+ * Stateless Lead Coordinator
+ *
+ * Reads tasks from Beads JSONL, assigns to workers, tracks via Beads updates.
+ * No in-memory task queue - all state persisted to Beads.
+ */
+export class StatelessLeadCoordinator extends EventEmitter {
+    config;
+    issuesPath;
+    heartbeatPath;
+    pollInterval;
+    heartbeatInterval;
+    isRunning = false;
+    constructor(config) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.issuesPath = path.join(this.config.beadsDir, 'issues.jsonl');
+        this.heartbeatPath = path.join(this.config.beadsDir, 'leader-heartbeat.json');
+    }
+    /**
+     * Start the lead coordinator loop
+     */
+    async start() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        console.log(`[stateless-lead] Starting lead coordinator: ${this.config.agentName}`);
+        // Write initial heartbeat
+        await this.writeHeartbeat();
+        // Start polling for ready tasks
+        this.pollInterval = setInterval(async () => {
+            try {
+                await this.pollAndAssign();
+            }
+            catch (err) {
+                console.error('[stateless-lead] Poll error:', err);
+                this.emit('error', err);
+            }
+        }, this.config.pollIntervalMs);
+        // Start heartbeat
+        this.heartbeatInterval = setInterval(async () => {
+            try {
+                await this.writeHeartbeat();
+            }
+            catch (err) {
+                console.error('[stateless-lead] Heartbeat error:', err);
+            }
+        }, this.config.heartbeatIntervalMs);
+        // Initial poll
+        await this.pollAndAssign();
+        this.emit('started', { leadName: this.config.agentName });
+    }
+    /**
+     * Stop the lead coordinator
+     */
+    async stop() {
+        if (!this.isRunning)
+            return;
+        this.isRunning = false;
+        if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = undefined;
+        }
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = undefined;
+        }
+        console.log(`[stateless-lead] Stopped lead coordinator: ${this.config.agentName}`);
+        this.emit('stopped', { leadName: this.config.agentName });
+    }
+    /**
+     * Read all tasks from Beads JSONL
+     */
+    async readTasks() {
+        if (!fs.existsSync(this.issuesPath)) {
+            return [];
+        }
+        const content = await fs.promises.readFile(this.issuesPath, 'utf-8');
+        const tasks = [];
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                tasks.push(JSON.parse(line));
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return tasks;
+    }
+    /**
+     * Update a task in Beads JSONL
+     */
+    async updateTask(taskId, updates) {
+        const tasks = await this.readTasks();
+        const updated = tasks.map((task) => {
+            if (task.id === taskId) {
+                return {
+                    ...task,
+                    ...updates,
+                    updated_at: new Date().toISOString(),
+                };
+            }
+            return task;
+        });
+        const content = updated.map((t) => JSON.stringify(t)).join('\n') + '\n';
+        await fs.promises.writeFile(this.issuesPath, content, 'utf-8');
+    }
+    /**
+     * Get tasks that are ready to be assigned
+     * Ready = open status, not assigned, not blocked, sorted by priority
+     */
+    async getReadyTasks() {
+        const tasks = await this.readTasks();
+        const now = Date.now();
+        return tasks
+            .filter((task) => {
+            // Must be open
+            if (task.status !== 'open')
+                return false;
+            // Not assigned, or lease expired (P1)
+            if (task.assignee) {
+                if (task.leaseExpires && task.leaseExpires > now) {
+                    return false; // Still leased
+                }
+                // Lease expired - task is available again
+            }
+            return true;
+        })
+            .sort((a, b) => a.priority - b.priority); // Lower priority number = higher priority
+    }
+    /**
+     * Get tasks currently assigned to agents
+     */
+    async getAssignedTasks() {
+        const tasks = await this.readTasks();
+        const now = Date.now();
+        return tasks.filter((task) => {
+            if (task.status !== 'in_progress')
+                return false;
+            if (!task.assignee)
+                return false;
+            // Check lease not expired
+            if (task.leaseExpires && task.leaseExpires <= now)
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Poll for ready tasks and assign to available workers
+     */
+    async pollAndAssign() {
+        const readyTasks = await this.getReadyTasks();
+        if (readyTasks.length === 0)
+            return;
+        const workers = await this.config.getAvailableWorkers();
+        if (workers.length === 0) {
+            console.log('[stateless-lead] No available workers');
+            return;
+        }
+        // Assign one task per available worker
+        for (const worker of workers) {
+            const task = readyTasks.shift();
+            if (!task)
+                break;
+            await this.assignTask(task, worker);
+        }
+    }
+    /**
+     * Assign a task to a worker
+     */
+    async assignTask(task, worker) {
+        const leaseExpires = Date.now() + this.config.leaseDurationMs;
+        // Update Beads first (source of truth)
+        await this.updateTask(task.id, {
+            status: 'in_progress',
+            assignee: worker,
+            leaseExpires,
+        });
+        // Send task to worker via relay
+        const message = `TASK [${task.id}]: ${task.title}${task.description ? '\n\n' + task.description : ''}`;
+        await this.config.sendRelay(worker, message);
+        console.log(`[stateless-lead] Assigned ${task.id} to ${worker} (lease expires in ${this.config.leaseDurationMs / 1000}s)`);
+        this.emit('assigned', { taskId: task.id, worker, leaseExpires });
+    }
+    /**
+     * Handle task completion from worker
+     */
+    async completeTask(taskId, worker, reason) {
+        await this.updateTask(taskId, {
+            status: 'closed',
+            assignee: worker,
+        });
+        console.log(`[stateless-lead] Task ${taskId} completed by ${worker}${reason ? ': ' + reason : ''}`);
+        this.emit('completed', { taskId, worker, reason });
+    }
+    /**
+     * Handle task blocked by worker
+     */
+    async blockTask(taskId, worker, reason) {
+        await this.updateTask(taskId, {
+            status: 'blocked',
+            assignee: worker,
+        });
+        console.log(`[stateless-lead] Task ${taskId} blocked by ${worker}: ${reason}`);
+        this.emit('blocked', { taskId, worker, reason });
+    }
+    /**
+     * Renew lease for a task (worker signals still working)
+     */
+    async renewLease(taskId, worker) {
+        const leaseExpires = Date.now() + this.config.leaseDurationMs;
+        await this.updateTask(taskId, { leaseExpires });
+        console.log(`[stateless-lead] Renewed lease for ${taskId} (${worker})`);
+        this.emit('leaseRenewed', { taskId, worker, leaseExpires });
+    }
+    /**
+     * Write leader heartbeat to file (P2)
+     */
+    async writeHeartbeat() {
+        const assignedTasks = await this.getAssignedTasks();
+        const assignedAgents = [...new Set(assignedTasks.map((t) => t.assignee).filter(Boolean))];
+        const heartbeat = {
+            leadName: this.config.agentName,
+            leadId: this.config.agentId,
+            timestamp: Date.now(),
+            activeTaskCount: assignedTasks.length,
+            assignedAgents,
+        };
+        await fs.promises.writeFile(this.heartbeatPath, JSON.stringify(heartbeat, null, 2), 'utf-8');
+    }
+    /**
+     * Read current leader heartbeat (for watchdog - P3)
+     */
+    static async readHeartbeat(beadsDir) {
+        const heartbeatPath = path.join(beadsDir, 'leader-heartbeat.json');
+        if (!fs.existsSync(heartbeatPath)) {
+            return null;
+        }
+        try {
+            const content = await fs.promises.readFile(heartbeatPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if leader is stale (for watchdog - P3)
+     */
+    static async isLeaderStale(beadsDir, staleThresholdMs = 30000) {
+        const heartbeat = await StatelessLeadCoordinator.readHeartbeat(beadsDir);
+        if (!heartbeat)
+            return true;
+        return Date.now() - heartbeat.timestamp > staleThresholdMs;
+    }
+    /**
+     * Get current status
+     */
+    async getStatus() {
+        const readyTasks = await this.getReadyTasks();
+        const assignedTasks = await this.getAssignedTasks();
+        const heartbeat = await StatelessLeadCoordinator.readHeartbeat(this.config.beadsDir);
+        return {
+            isRunning: this.isRunning,
+            leadName: this.config.agentName,
+            readyTasks: readyTasks.length,
+            assignedTasks: assignedTasks.length,
+            lastHeartbeat: heartbeat?.timestamp ?? null,
+        };
+    }
+}
+/**
+ * Create a stateless lead coordinator with defaults
+ */
+export function createStatelessLead(beadsDir, agentName, agentId, callbacks) {
+    return new StatelessLeadCoordinator({
+        beadsDir,
+        agentName,
+        agentId,
+        ...callbacks,
+        pollIntervalMs: 5000,
+        heartbeatIntervalMs: 10000,
+        leaseDurationMs: 300000,
+    });
+}
+//# sourceMappingURL=stateless-lead.js.map

package/dist/resiliency/stateless-lead.js.map

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

package/dist/resiliency/supervisor.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Agent Supervisor
+ *
+ * High-level supervisor that combines health monitoring, logging, and metrics
+ * to provide comprehensive agent resiliency.
+ */
+import { EventEmitter } from 'events';
+import { AgentHealthMonitor, HealthMonitorConfig } from './health-monitor.js';
+import { LogLevel } from './logger.js';
+import { metrics } from './metrics.js';
+import { ProviderType } from './provider-context.js';
+import { LeadHeartbeat } from './stateless-lead.js';
+export interface SupervisedAgent {
+    name: string;
+    cli: string;
+    task?: string;
+    pid: number;
+    logFile?: string;
+    spawnedAt: Date;
+    workingDir?: string;
+    provider?: ProviderType;
+}
+export interface SupervisorConfig {
+    healthCheck: Partial<HealthMonitorConfig>;
+    logging: {
+        level: LogLevel;
+        file?: string;
+    };
+    autoRestart: boolean;
+    maxRestarts: number;
+    notifyOnCrash: boolean;
+    contextPersistence: {
+        enabled: boolean;
+        baseDir?: string;
+        autoInjectOnRestart: boolean;
+    };
+    /** Leader coordination (P0-P3) */
+    leaderCoordination?: {
+        enabled: boolean;
+        /** Path to .beads directory */
+        beadsDir: string;
+        /** Callback to send relay messages */
+        sendRelay?: (to: string, message: string) => Promise<void>;
+    };
+}
+export declare class AgentSupervisor extends EventEmitter {
+    private config;
+    private healthMonitor;
+    private logger;
+    private agents;
+    private restarters;
+    private contextPersistence?;
+    private contextHandlers;
+    private leaderWatchdog?;
+    private leadCoordinator?;
+    private supervisorAgentId;
+    constructor(config?: Partial<SupervisorConfig>);
+    /**
+     * Start supervising agents
+     */
+    start(): void;
+    /**
+     * Stop supervising agents
+     */
+    stop(): void;
+    /**
+     * Enable leader coordination with watchdog
+     * This allows this supervisor to participate in leader election and
+     * potentially become the lead coordinator for task distribution.
+     */
+    enableLeaderCoordination(beadsDir: string, sendRelay: (to: string, message: string) => Promise<void>): void;
+    /**
+     * Called when this supervisor wins leader election
+     */
+    private becomeLeader;
+    /**
+     * Get healthy agents for leader election
+     */
+    private getHealthyAgents;
+    /**
+     * Get available worker names (healthy agents not currently busy)
+     */
+    private getAvailableWorkerNames;
+    /**
+     * Check if this supervisor is currently the leader
+     */
+    isLeader(): boolean;
+    /**
+     * Get current leader info
+     */
+    getCurrentLeader(): LeadHeartbeat | null;
+    /**
+     * Add an agent to supervision
+     */
+    supervise(agent: SupervisedAgent, options: {
+        isAlive: () => boolean;
+        kill: (signal?: string) => void;
+        restart: () => Promise<void>;
+        sendHealthCheck?: () => Promise<boolean>;
+    }): void;
+    /**
+     * Remove an agent from supervision
+     */
+    unsupervise(name: string): void;
+    /**
+     * Update agent info (e.g., after restart)
+     */
+    updateAgent(name: string, updates: Partial<SupervisedAgent>): void;
+    /**
+     * Get all supervised agents
+     */
+    getAgents(): SupervisedAgent[];
+    /**
+     * Get agent status
+     */
+    getStatus(name: string): {
+        agent?: SupervisedAgent;
+        health?: ReturnType<AgentHealthMonitor['get']>;
+        metrics?: ReturnType<typeof metrics.getAgentMetrics>;
+    };
+    /**
+     * Get overall supervisor status
+     */
+    getOverallStatus(): {
+        agents: SupervisedAgent[];
+        health: ReturnType<AgentHealthMonitor['getAll']>;
+        systemMetrics: ReturnType<typeof metrics.getSystemMetrics>;
+    };
+    /**
+     * Force restart an agent
+     */
+    forceRestart(name: string): Promise<void>;
+    /**
+     * Setup event handlers for health monitor
+     */
+    private setupHealthMonitorEvents;
+    /**
+     * Send notification about agent crash
+     */
+    private notifyCrash;
+    /**
+     * Send notification about permanently dead agent
+     */
+    private notifyDead;
+}
+export declare function getSupervisor(config?: Partial<SupervisorConfig>): AgentSupervisor;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/resiliency/supervisor.d.ts.map

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