@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/dist/skills/types.js

@@ -0,0 +1,21 @@
+/**
+ * Skill types and interfaces for PoolBot Skills System
+ * Compatible with agentskills.io ecosystem
+ *
+ * @module skills/types
+ */
+/**
+ * Skill system error
+ */
+export class SkillError extends Error {
+    code;
+    skillId;
+    cause;
+    constructor(code, message, skillId, cause) {
+        super(message);
+        this.code = code;
+        this.skillId = skillId;
+        this.cause = cause;
+        this.name = "SkillError";
+    }
+}

package/dist/swarm/service.js

@@ -0,0 +1,247 @@
+// Agent Swarm Service - Multi-agent coordination and task distribution
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+const log = createSubsystemLogger("swarm");
+const POOLBOT_DIR = join(process.env.HOME ?? "/tmp", ".poolbot");
+const SWARM_STATE_FILE = join(POOLBOT_DIR, "swarm-state.json");
+export class SwarmService {
+    swarms;
+    persistEnabled;
+    constructor(persistEnabled = true) {
+        this.swarms = new Map();
+        this.persistEnabled = persistEnabled;
+        this.loadFromDisk();
+    }
+    ensureDir() {
+        if (!existsSync(POOLBOT_DIR)) {
+            mkdirSync(POOLBOT_DIR, { recursive: true });
+        }
+    }
+    loadFromDisk() {
+        if (!this.persistEnabled)
+            return;
+        try {
+            this.ensureDir();
+            if (existsSync(SWARM_STATE_FILE)) {
+                const data = readFileSync(SWARM_STATE_FILE, "utf-8");
+                const parsed = JSON.parse(data);
+                for (const [id, swarm] of Object.entries(parsed)) {
+                    this.swarms.set(id, swarm);
+                }
+                log.info(`Loaded ${this.swarms.size} swarms from disk`);
+            }
+        }
+        catch (error) {
+            log.error(`Failed to load swarm state: ${String(error)}`);
+        }
+    }
+    saveToDisk() {
+        if (!this.persistEnabled)
+            return;
+        try {
+            this.ensureDir();
+            const data = {};
+            for (const [id, swarm] of this.swarms) {
+                data[id] = swarm;
+            }
+            writeFileSync(SWARM_STATE_FILE, JSON.stringify(data, null, 2));
+        }
+        catch (error) {
+            log.error(`Failed to save swarm state: ${String(error)}`);
+        }
+    }
+    async list() {
+        const swarmList = Array.from(this.swarms.values()).map((swarm) => ({
+            id: swarm.id,
+            name: swarm.name,
+            status: swarm.status,
+            members: swarm.members.length,
+            tasks: swarm.tasks.length,
+        }));
+        return { swarms: swarmList };
+    }
+    async getStatus(swarmId) {
+        const swarm = this.swarms.get(swarmId);
+        return { swarm: swarm ?? null };
+    }
+    async create(params) {
+        const id = `swarm-${Date.now()}`;
+        const now = Date.now();
+        const swarm = {
+            id,
+            name: params.name,
+            description: params.description,
+            createdAt: now,
+            orchestratorAgentId: params.orchestratorAgentId,
+            members: [],
+            tasks: [],
+            strategy: params.strategy,
+            status: "active",
+        };
+        this.swarms.set(id, swarm);
+        this.saveToDisk();
+        log.info(`Created swarm: ${id} (${params.name})`);
+        return {
+            id,
+            name: params.name,
+            description: params.description,
+            strategy: params.strategy,
+            orchestratorAgentId: params.orchestratorAgentId,
+            createdAt: now,
+            status: "active",
+        };
+    }
+    async delete(swarmId) {
+        const deleted = this.swarms.delete(swarmId);
+        if (deleted) {
+            this.saveToDisk();
+            log.info(`Deleted swarm: ${swarmId}`);
+        }
+        return deleted;
+    }
+    async addMember(swarmId, member) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        // Check if member already exists
+        const existingIndex = swarm.members.findIndex((m) => m.agentId === member.agentId);
+        if (existingIndex >= 0) {
+            swarm.members[existingIndex] = member;
+        }
+        else {
+            swarm.members.push(member);
+        }
+        this.saveToDisk();
+        return true;
+    }
+    async removeMember(swarmId, agentId) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        const initialLength = swarm.members.length;
+        swarm.members = swarm.members.filter((m) => m.agentId !== agentId);
+        const removed = swarm.members.length < initialLength;
+        if (removed) {
+            this.saveToDisk();
+        }
+        return removed;
+    }
+    async addTask(swarmId, task) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        swarm.tasks.push(task);
+        this.saveToDisk();
+        return true;
+    }
+    async removeTask(swarmId, taskId) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        const initialLength = swarm.tasks.length;
+        swarm.tasks = swarm.tasks.filter((t) => t.id !== taskId);
+        const removed = swarm.tasks.length < initialLength;
+        if (removed) {
+            this.saveToDisk();
+        }
+        return removed;
+    }
+    async updateTaskStatus(swarmId, taskId, status, assignedTo) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        const task = swarm.tasks.find((t) => t.id === taskId);
+        if (!task)
+            return false;
+        task.status = status;
+        if (assignedTo)
+            task.assignedTo = assignedTo;
+        if (status === "in_progress" && !task.startedAt)
+            task.startedAt = Date.now();
+        if (status === "completed" && !task.completedAt)
+            task.completedAt = Date.now();
+        this.saveToDisk();
+        return true;
+    }
+    async updateMemberStatus(swarmId, agentId, status, currentTaskId) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        const member = swarm.members.find((m) => m.agentId === agentId);
+        if (!member)
+            return false;
+        member.status = status;
+        member.lastHeartbeatAt = Date.now();
+        if (currentTaskId !== undefined)
+            member.currentTaskId = currentTaskId;
+        if (status === "working" && currentTaskId) {
+            member.completedTasks++;
+        }
+        this.saveToDisk();
+        return true;
+    }
+    async updateSwarmStatus(swarmId, status) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        swarm.status = status;
+        this.saveToDisk();
+        return true;
+    }
+    // Get or create default swarm for demo purposes
+    async getOrCreateDefaultSwarm() {
+        const defaultId = "swarm-default";
+        let swarm = this.swarms.get(defaultId);
+        if (!swarm) {
+            const now = Date.now();
+            swarm = {
+                id: defaultId,
+                name: "Default Swarm",
+                description: "Default agent swarm for task coordination",
+                createdAt: now,
+                orchestratorAgentId: "main",
+                members: [
+                    {
+                        agentId: "agent-1",
+                        sessionKey: "swarm/agent-1",
+                        status: "idle",
+                        capabilities: ["typescript", "review", "coding"],
+                        joinedAt: now,
+                        lastHeartbeatAt: now,
+                        completedTasks: 0,
+                        failedTasks: 0,
+                    },
+                ],
+                tasks: [],
+                strategy: "capability_match",
+                status: "active",
+            };
+            this.swarms.set(defaultId, swarm);
+            this.saveToDisk();
+        }
+        return swarm;
+    }
+    // Get swarm statistics
+    async getStats(swarmId) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return null;
+        const activeMembers = swarm.members.filter((m) => m.status === "idle" || m.status === "working").length;
+        const completedTasks = swarm.tasks.filter((t) => t.status === "completed").length;
+        const failedTasks = swarm.tasks.filter((t) => t.status === "failed").length;
+        const pendingTasks = swarm.tasks.filter((t) => t.status === "pending").length;
+        const inProgressTasks = swarm.tasks.filter((t) => t.status === "in_progress").length;
+        return {
+            totalMembers: swarm.members.length,
+            activeMembers,
+            totalTasks: swarm.tasks.length,
+            completedTasks,
+            failedTasks,
+            pendingTasks,
+            inProgressTasks,
+        };
+    }
+}
+// Singleton instance
+export const swarmService = new SwarmService();

package/dist/telemetry/alert-engine.js

@@ -0,0 +1,258 @@
+import { createSubsystemLogger } from "../logging/subsystem.js";
+const log = createSubsystemLogger("telemetry:alerts");
+export class AlertEngine {
+    rules = new Map();
+    states = new Map();
+    onAlertCallback;
+    constructor(rules = []) {
+        for (const rule of rules) {
+            this.addRule(rule);
+        }
+    }
+    addRule(rule) {
+        this.rules.set(rule.id, rule);
+        this.states.set(rule.id, { consecutiveCount: 0 });
+        log.debug(`Added alert rule: ${rule.id} (${rule.name})`);
+    }
+    removeRule(ruleId) {
+        this.states.delete(ruleId);
+        return this.rules.delete(ruleId);
+    }
+    getRules() {
+        return Array.from(this.rules.values());
+    }
+    onAlert(callback) {
+        this.onAlertCallback = callback;
+    }
+    evaluate(snapshot) {
+        const alerts = [];
+        const now = Date.now();
+        for (const rule of this.rules.values()) {
+            if (!rule.enabled)
+                continue;
+            const alert = this.evaluateRule(rule, snapshot, now);
+            if (alert) {
+                alerts.push(alert);
+                this.onAlertCallback?.(alert);
+            }
+        }
+        return alerts;
+    }
+    evaluateRule(rule, snapshot, now) {
+        const state = this.states.get(rule.id);
+        if (!state)
+            return null;
+        // Find matching metrics
+        const matchingMetrics = snapshot.metrics.filter((m) => {
+            if (m.name !== rule.threshold.metric)
+                return false;
+            if (rule.attributes) {
+                for (const [key, value] of Object.entries(rule.attributes)) {
+                    if (m.attributes?.[key] !== value)
+                        return false;
+                }
+            }
+            return true;
+        });
+        if (matchingMetrics.length === 0) {
+            // Reset state if no matching metrics
+            state.consecutiveCount = 0;
+            state.triggeredAt = undefined;
+            return null;
+        }
+        // Check if any metric violates threshold
+        let violated = false;
+        let violatingMetric = null;
+        for (const metric of matchingMetrics) {
+            if (this.checkThreshold(metric.value, rule.threshold)) {
+                violated = true;
+                violatingMetric = metric;
+                break;
+            }
+        }
+        if (!violated) {
+            // Reset state if threshold no longer violated
+            state.consecutiveCount = 0;
+            state.triggeredAt = undefined;
+            return null;
+        }
+        // Track consecutive violations
+        state.consecutiveCount++;
+        if (!state.triggeredAt) {
+            state.triggeredAt = now;
+        }
+        // Check duration requirement
+        const durationMs = rule.threshold.durationMs ?? 0;
+        if (now - state.triggeredAt < durationMs) {
+            return null; // Haven't met duration requirement yet
+        }
+        // Check cooldown
+        const cooldownMs = rule.threshold.cooldownMs ?? 60000;
+        if (state.lastAlertAt && now - state.lastAlertAt < cooldownMs) {
+            return null; // Still in cooldown
+        }
+        // Trigger alert
+        state.lastAlertAt = now;
+        return {
+            id: `${rule.id}-${now}`,
+            ruleId: rule.id,
+            name: rule.name,
+            severity: rule.severity,
+            metric: rule.threshold.metric,
+            value: violatingMetric.value,
+            threshold: rule.threshold.value,
+            operator: rule.threshold.operator,
+            timestamp: now,
+            message: this.buildAlertMessage(rule, violatingMetric.value),
+            attributes: violatingMetric.attributes,
+        };
+    }
+    checkThreshold(value, threshold) {
+        switch (threshold.operator) {
+            case "gt":
+                return value > threshold.value;
+            case "gte":
+                return value >= threshold.value;
+            case "lt":
+                return value < threshold.value;
+            case "lte":
+                return value <= threshold.value;
+            case "eq":
+                return value === threshold.value;
+            default:
+                return false;
+        }
+    }
+    buildAlertMessage(rule, value) {
+        const opMap = {
+            gt: ">",
+            gte: ">=",
+            lt: "<",
+            lte: "<=",
+            eq: "=",
+        };
+        return `${rule.name}: ${rule.threshold.metric} = ${value} ${opMap[rule.threshold.operator]} ${rule.threshold.value}`;
+    }
+}
+// Predefined alert rules for common Pool Bot scenarios
+export const defaultAlertRules = [
+    // Cron Job Alerts
+    {
+        id: "cron-high-failure-rate",
+        name: "High Cron Job Failure Rate",
+        description: "Triggers when cron job failures exceed 3 in 5 minutes",
+        enabled: true,
+        severity: "warning",
+        threshold: {
+            metric: "poolbot.cron.job_failures",
+            operator: "gt",
+            value: 3,
+            durationMs: 300000, // 5 minutes
+            cooldownMs: 600000, // 10 minutes
+        },
+    },
+    {
+        id: "cron-slow-jobs",
+        name: "Slow Cron Job Execution",
+        description: "Triggers when cron job duration exceeds 60 seconds",
+        enabled: true,
+        severity: "info",
+        threshold: {
+            metric: "poolbot.cron.job_duration_ms",
+            operator: "gt",
+            value: 60000,
+            durationMs: 60000, // 1 minute
+            cooldownMs: 300000, // 5 minutes
+        },
+    },
+    {
+        id: "cron-job-stuck",
+        name: "Cron Job Possibly Stuck",
+        description: "Triggers when cron job duration exceeds 5 minutes",
+        enabled: true,
+        severity: "critical",
+        threshold: {
+            metric: "poolbot.cron.job_duration_ms",
+            operator: "gt",
+            value: 300000,
+            durationMs: 60000,
+            cooldownMs: 300000,
+        },
+    },
+    // Security Scan Alerts (HexStrike)
+    {
+        id: "security-scan-failures",
+        name: "Security Scan Failures",
+        description: "Triggers when security scans fail",
+        enabled: true,
+        severity: "warning",
+        threshold: {
+            metric: "poolbot.security.scan_failures",
+            operator: "gt",
+            value: 2,
+            durationMs: 300000,
+            cooldownMs: 600000,
+        },
+    },
+    {
+        id: "security-high-latency",
+        name: "HexStrike API High Latency",
+        description: "Triggers when HexStrike API latency exceeds 5 seconds",
+        enabled: true,
+        severity: "info",
+        threshold: {
+            metric: "poolbot.security.api_latency_ms",
+            operator: "gt",
+            value: 5000,
+            durationMs: 120000,
+            cooldownMs: 300000,
+        },
+    },
+    // Swarm Alerts
+    {
+        id: "swarm-high-failure-rate",
+        name: "Swarm Task Failure Rate",
+        description: "Triggers when swarm tasks fail frequently",
+        enabled: true,
+        severity: "warning",
+        threshold: {
+            metric: "poolbot.swarm.task_failures",
+            operator: "gt",
+            value: 5,
+            durationMs: 600000,
+            cooldownMs: 600000,
+        },
+    },
+    // Gateway Health Alerts
+    {
+        id: "gateway-high-memory",
+        name: "High Gateway Memory Usage",
+        description: "Triggers when gateway memory usage exceeds 512MB",
+        enabled: true,
+        severity: "critical",
+        threshold: {
+            metric: "poolbot.gateway.memory_usage_bytes",
+            operator: "gt",
+            value: 536870912, // 512MB
+            durationMs: 120000,
+            cooldownMs: 300000,
+        },
+    },
+    {
+        id: "gateway-high-cpu",
+        name: "High Gateway CPU Usage",
+        description: "Triggers when gateway CPU usage exceeds 80%",
+        enabled: true,
+        severity: "warning",
+        threshold: {
+            metric: "poolbot.gateway.cpu_usage_percent",
+            operator: "gt",
+            value: 80,
+            durationMs: 180000,
+            cooldownMs: 300000,
+        },
+    },
+];
+export function createAlertEngine(customRules) {
+    return new AlertEngine([...defaultAlertRules, ...(customRules ?? [])]);
+}

package/dist/telemetry/cron-instrumentation.js

@@ -0,0 +1,49 @@
+import { recordCounter, recordGauge, recordHistogram, withInstrumentation, } from "../telemetry/instrumentation.js";
+export function instrumentCronOperation(operation, fn, attributes) {
+    return withInstrumentation({
+        operation,
+        component: "cron",
+        attributes,
+    }, fn);
+}
+export function recordCronJobExecution(metrics) {
+    recordCounter("poolbot.cron.jobs_executed", 1, {
+        job_id: metrics.jobId,
+        job_name: metrics.jobName,
+        schedule: metrics.schedule,
+        status: metrics.success ? "success" : "failure",
+    });
+    recordHistogram("poolbot.cron.job_duration_ms", metrics.durationMs, {
+        job_id: metrics.jobId,
+        job_name: metrics.jobName,
+    });
+    if (!metrics.success) {
+        recordCounter("poolbot.cron.job_failures", 1, {
+            job_id: metrics.jobId,
+            job_name: metrics.jobName,
+            error_type: metrics.errorType ?? "unknown",
+        });
+    }
+}
+export function recordCronJobScheduled(jobId, jobName, schedule) {
+    recordCounter("poolbot.cron.jobs_scheduled", 1, {
+        job_id: jobId,
+        job_name: jobName,
+        schedule,
+    });
+}
+export function recordCronJobCancelled(jobId, jobName) {
+    recordCounter("poolbot.cron.jobs_cancelled", 1, {
+        job_id: jobId,
+        job_name: jobName,
+    });
+}
+export function updateActiveCronJobsGauge(count) {
+    recordGauge("poolbot.cron.active_jobs", count);
+}
+export function recordCronQueueDepth(depth) {
+    recordGauge("poolbot.cron.queue_depth", depth);
+}
+export function recordCronOverdueJobs(count) {
+    recordGauge("poolbot.cron.overdue_jobs", count);
+}

package/dist/telemetry/gateway-instrumentation.js

@@ -0,0 +1,80 @@
+import { recordCounter, recordHistogram, withInstrumentation, } from "../telemetry/instrumentation.js";
+export function instrumentGatewayRequest(operation, fn, attributes) {
+    return withInstrumentation({
+        operation,
+        component: "gateway",
+        attributes,
+    }, fn);
+}
+export function recordGatewayRequest(metrics) {
+    recordCounter("poolbot.gateway.requests", 1, {
+        method: metrics.method,
+        path: metrics.path,
+        status_code: String(metrics.statusCode),
+    });
+    recordHistogram("poolbot.gateway.request_duration_ms", metrics.durationMs, {
+        method: metrics.method,
+        path: metrics.path,
+    });
+    if (metrics.statusCode >= 500) {
+        recordCounter("poolbot.gateway.server_errors", 1, {
+            path: metrics.path,
+        });
+    }
+    else if (metrics.statusCode >= 400) {
+        recordCounter("poolbot.gateway.client_errors", 1, {
+            path: metrics.path,
+            status_code: String(metrics.statusCode),
+        });
+    }
+}
+export function createTelemetryMiddleware() {
+    return (req, res, next) => {
+        const startTime = Date.now();
+        const path = req.url ?? "/unknown";
+        const method = req.method ?? "UNKNOWN";
+        recordCounter("poolbot.gateway.active_requests", 1, {
+            method,
+            path,
+        });
+        const originalEnd = res.end.bind(res);
+        res.end = function (...args) {
+            const duration = Date.now() - startTime;
+            recordCounter("poolbot.gateway.active_requests", -1, {
+                method,
+                path,
+            });
+            recordGatewayRequest({
+                method,
+                path,
+                statusCode: res.statusCode,
+                durationMs: duration,
+                userAgent: req.headers["user-agent"],
+            });
+            return originalEnd(...args);
+        };
+        next();
+    };
+}
+export function instrumentWebSocketConnection(connectionId) {
+    recordCounter("poolbot.gateway.ws.connections", 1, {
+        connection_id: connectionId,
+    });
+}
+export function recordWebSocketMessage(connectionId, messageType, sizeBytes) {
+    recordCounter("poolbot.gateway.ws.messages", 1, {
+        connection_id: connectionId,
+        message_type: messageType,
+    });
+    recordHistogram("poolbot.gateway.ws.message_size_bytes", sizeBytes, {
+        message_type: messageType,
+    });
+}
+export function recordWebSocketDisconnection(connectionId, durationMs) {
+    recordCounter("poolbot.gateway.ws.disconnections", 1, {
+        connection_id: connectionId,
+    });
+    recordHistogram("poolbot.gateway.ws.connection_duration_ms", durationMs, {
+        connection_id: connectionId,
+    });
+}