@poolzin/pool-bot 2026.3.9 → 2026.3.10

package/dist/cli/cron-cli/register.cron-dashboard.js

@@ -0,0 +1,339 @@
+import { danger } from "../../globals.js";
+import { defaultRuntime } from "../../runtime.js";
+import { colorize, isRich, theme } from "../../terminal/theme.js";
+import { renderTable } from "../../terminal/table.js";
+import { addGatewayClientOptions, callGatewayFromCli } from "../gateway-rpc.js";
+import { formatDurationHuman } from "../../infra/format-time/format-duration.js";
+import { resolveCronStaggerMs } from "../../cron/stagger.js";
+// Sparkline characters for visual history
+const SPARK_CHARS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+// Status indicators
+const STATUS_ICONS = {
+    ok: "●",
+    error: "✖",
+    running: "▶",
+    skipped: "○",
+    idle: "◌",
+    disabled: "⊘",
+};
+// Format relative time with color coding
+function formatRelativeTime(ms, nowMs) {
+    if (!ms)
+        return "-";
+    const delta = ms - nowMs;
+    const absMs = Math.abs(delta);
+    if (absMs < 60_000)
+        return delta >= 0 ? "<1m" : "<1m ago";
+    if (absMs < 3_600_000) {
+        const mins = Math.round(absMs / 60_000);
+        return delta >= 0 ? `${mins}m` : `${mins}m ago`;
+    }
+    if (absMs < 86_400_000) {
+        const hours = Math.round(absMs / 3_600_000);
+        return delta >= 0 ? `${hours}h` : `${hours}h ago`;
+    }
+    const days = Math.round(absMs / 86_400_000);
+    return delta >= 0 ? `${days}d` : `${days}d ago`;
+}
+// Format schedule compactly
+function formatScheduleCompact(job) {
+    const { schedule } = job;
+    if (schedule.kind === "at") {
+        const date = new Date(schedule.at);
+        return `once ${date.toLocaleDateString()}`;
+    }
+    if (schedule.kind === "every") {
+        return `every ${formatDurationHuman(schedule.everyMs)}`;
+    }
+    // cron
+    const staggerMs = resolveCronStaggerMs(schedule);
+    const stagger = staggerMs > 0 ? `~${formatDurationHuman(staggerMs)}` : "exact";
+    return `${schedule.expr} ${stagger}`;
+}
+// Get status with icon
+function getStatusDisplay(job, rich) {
+    if (!job.enabled) {
+        return rich ? `${colorize(rich, theme.muted, STATUS_ICONS.disabled)} disabled` : "disabled";
+    }
+    if (job.state.runningAtMs) {
+        return rich ? `${colorize(rich, theme.warn, STATUS_ICONS.running)} running` : "running";
+    }
+    const status = job.state.lastStatus ?? "idle";
+    const icon = STATUS_ICONS[status] ?? STATUS_ICONS.idle;
+    if (!rich)
+        return status;
+    switch (status) {
+        case "ok":
+            return `${colorize(rich, theme.success, icon)} ${status}`;
+        case "error":
+            return `${colorize(rich, theme.error, icon)} ${status}`;
+        case "skipped":
+            return `${colorize(rich, theme.muted, icon)} ${status}`;
+        default:
+            return `${colorize(rich, theme.muted, icon)} ${status}`;
+    }
+}
+// Generate sparkline from execution history (simulated from state)
+function generateSparkline(job, rich) {
+    // In a real implementation, this would use actual history data
+    // For now, we create a visual indicator based on recent state
+    const { consecutiveErrors = 0, lastStatus } = job.state;
+    if (!rich) {
+        return consecutiveErrors > 0 ? `!${consecutiveErrors}` : "-";
+    }
+    if (consecutiveErrors > 0) {
+        const level = Math.min(consecutiveErrors, SPARK_CHARS.length - 1);
+        return colorize(rich, theme.error, SPARK_CHARS[level].repeat(3));
+    }
+    if (lastStatus === "ok") {
+        return colorize(rich, theme.success, "▁▃▆");
+    }
+    return colorize(rich, theme.muted, "···");
+}
+// Format job target
+function formatTarget(job, rich) {
+    const { sessionTarget, agentId } = job;
+    if (!rich)
+        return agentId ?? sessionTarget ?? "-";
+    const target = sessionTarget === "isolated"
+        ? colorize(rich, theme.accentBright, "iso")
+        : colorize(rich, theme.accent, "main");
+    if (agentId) {
+        return `${target}:${colorize(rich, theme.info, agentId.slice(0, 8))}`;
+    }
+    return target;
+}
+// Calculate health score (0-100)
+function calculateHealthScore(job) {
+    if (!job.enabled)
+        return 100; // Disabled jobs are "healthy" by not running
+    if (job.state.runningAtMs)
+        return 100; // Currently running is fine
+    const { consecutiveErrors = 0, lastStatus, scheduleErrorCount = 0 } = job.state;
+    if (consecutiveErrors >= 5 || scheduleErrorCount >= 10)
+        return 0;
+    if (consecutiveErrors > 0)
+        return Math.max(0, 100 - consecutiveErrors * 20);
+    if (lastStatus === "error")
+        return 50;
+    if (lastStatus === "skipped")
+        return 75;
+    return 100;
+}
+// Get health indicator
+function getHealthIndicator(score, rich) {
+    if (!rich)
+        return `${score}%`;
+    if (score >= 90)
+        return colorize(rich, theme.success, "●");
+    if (score >= 70)
+        return colorize(rich, theme.warn, "●");
+    return colorize(rich, theme.error, "●");
+}
+// Print dashboard header
+function printDashboardHeader(runtime = defaultRuntime) {
+    const rich = isRich();
+    const now = new Date();
+    const timestamp = now.toLocaleString();
+    runtime.log("");
+    if (rich) {
+        runtime.log(colorize(rich, theme.heading, "╔═══════════════════════════════════════════════════════════╗"));
+        runtime.log(colorize(rich, theme.heading, `║  🕐 CRON DASHBOARD                              ${timestamp.padStart(26)} ║`));
+        runtime.log(colorize(rich, theme.heading, "╚═══════════════════════════════════════════════════════════╝"));
+    }
+    else {
+        runtime.log("═══════════════════════════════════════════════════════════");
+        runtime.log(`CRON DASHBOARD - ${timestamp}`);
+        runtime.log("═══════════════════════════════════════════════════════════");
+    }
+    runtime.log("");
+}
+// Print summary stats
+function printSummaryStats(jobs, runtime = defaultRuntime) {
+    const rich = isRich();
+    const now = Date.now();
+    const enabled = jobs.filter((j) => j.enabled).length;
+    const running = jobs.filter((j) => j.state.runningAtMs).length;
+    const errors = jobs.filter((j) => j.enabled && j.state.lastStatus === "error" && !j.state.runningAtMs).length;
+    const upcoming = jobs.filter((j) => j.enabled && j.state.nextRunAtMs && j.state.nextRunAtMs > now).length;
+    if (rich) {
+        const stats = [
+            `${colorize(rich, theme.info, "Total:")} ${jobs.length}`,
+            `${colorize(rich, theme.success, "Enabled:")} ${enabled}`,
+            `${colorize(rich, theme.warn, "Running:")} ${running}`,
+            `${colorize(rich, theme.error, "Errors:")} ${errors}`,
+            `${colorize(rich, theme.accent, "Upcoming:")} ${upcoming}`,
+        ].join("  │  ");
+        runtime.log(`  ${stats}`);
+    }
+    else {
+        runtime.log(`  Total: ${jobs.length} | Enabled: ${enabled} | Running: ${running} | Errors: ${errors} | Upcoming: ${upcoming}`);
+    }
+    runtime.log("");
+}
+// Print jobs table
+function printJobsTable(jobs, runtime = defaultRuntime) {
+    const rich = isRich();
+    const now = Date.now();
+    if (jobs.length === 0) {
+        runtime.log(rich
+            ? colorize(rich, theme.muted, "  No cron jobs configured.")
+            : "  No cron jobs configured.");
+        return;
+    }
+    // Sort: running first, then by next run time
+    const sortedJobs = [...jobs].sort((a, b) => {
+        if (a.state.runningAtMs && !b.state.runningAtMs)
+            return -1;
+        if (!a.state.runningAtMs && b.state.runningAtMs)
+            return 1;
+        if (!a.enabled && b.enabled)
+            return 1;
+        if (a.enabled && !b.enabled)
+            return -1;
+        const aNext = a.state.nextRunAtMs ?? Infinity;
+        const bNext = b.state.nextRunAtMs ?? Infinity;
+        return aNext - bNext;
+    });
+    const columns = [
+        { key: "health", header: "", align: "center", minWidth: 2, maxWidth: 3 },
+        {
+            key: "status",
+            header: rich ? colorize(rich, theme.heading, "Status") : "Status",
+            align: "left",
+            minWidth: 10,
+            maxWidth: 12,
+        },
+        {
+            key: "name",
+            header: rich ? colorize(rich, theme.heading, "Name") : "Name",
+            align: "left",
+            minWidth: 20,
+            flex: true,
+        },
+        {
+            key: "schedule",
+            header: rich ? colorize(rich, theme.heading, "Schedule") : "Schedule",
+            align: "left",
+            minWidth: 18,
+            maxWidth: 25,
+        },
+        {
+            key: "next",
+            header: rich ? colorize(rich, theme.heading, "Next") : "Next",
+            align: "right",
+            minWidth: 10,
+            maxWidth: 12,
+        },
+        {
+            key: "last",
+            header: rich ? colorize(rich, theme.heading, "Last") : "Last",
+            align: "right",
+            minWidth: 10,
+            maxWidth: 12,
+        },
+        {
+            key: "target",
+            header: rich ? colorize(rich, theme.heading, "Target") : "Target",
+            align: "left",
+            minWidth: 12,
+            maxWidth: 15,
+        },
+        {
+            key: "trend",
+            header: rich ? colorize(rich, theme.heading, "Trend") : "Trend",
+            align: "center",
+            minWidth: 4,
+            maxWidth: 6,
+        },
+    ];
+    const rows = sortedJobs.map((job) => {
+        const healthScore = calculateHealthScore(job);
+        const nextRun = formatRelativeTime(job.state.nextRunAtMs, now);
+        const lastRun = formatRelativeTime(job.state.lastRunAtMs, now);
+        // Color-code the times
+        const coloredNext = rich && job.enabled && job.state.nextRunAtMs
+            ? job.state.nextRunAtMs - now < 300_000
+                ? colorize(rich, theme.warn, nextRun) // < 5 min
+                : colorize(rich, theme.muted, nextRun)
+            : nextRun;
+        const coloredLast = rich && job.state.lastRunAtMs
+            ? now - job.state.lastRunAtMs < 300_000
+                ? colorize(rich, theme.accentBright, lastRun) // < 5 min ago
+                : colorize(rich, theme.muted, lastRun)
+            : lastRun;
+        return {
+            health: getHealthIndicator(healthScore, rich),
+            status: getStatusDisplay(job, rich),
+            name: rich ? colorize(rich, theme.info, job.name) : job.name,
+            schedule: formatScheduleCompact(job),
+            next: coloredNext,
+            last: coloredLast,
+            target: formatTarget(job, rich),
+            trend: generateSparkline(job, rich),
+        };
+    });
+    const table = renderTable({
+        columns,
+        rows,
+        border: rich ? "unicode" : "ascii",
+        padding: 1,
+    });
+    runtime.log(table);
+}
+// Print legend
+function printLegend(runtime = defaultRuntime) {
+    const rich = isRich();
+    runtime.log("");
+    if (rich) {
+        runtime.log(colorize(rich, theme.muted, "  Legend:"));
+        runtime.log(`    ${colorize(rich, theme.success, STATUS_ICONS.ok)} ok  ${colorize(rich, theme.error, STATUS_ICONS.error)} error  ${colorize(rich, theme.warn, STATUS_ICONS.running)} running  ${colorize(rich, theme.muted, STATUS_ICONS.skipped)} skipped  ${colorize(rich, theme.muted, STATUS_ICONS.disabled)} disabled`);
+        runtime.log(`    ${colorize(rich, theme.success, "●")} healthy  ${colorize(rich, theme.warn, "●")} warning  ${colorize(rich, theme.error, "●")} critical`);
+    }
+    else {
+        runtime.log("  Legend:");
+        runtime.log("    ● ok  ✖ error  ▶ running  ○ skipped  ⊘ disabled");
+        runtime.log("    ● healthy  ● warning  ● critical");
+    }
+}
+// Print footer with tips
+function printFooter(runtime = defaultRuntime) {
+    const rich = isRich();
+    runtime.log("");
+    if (rich) {
+        runtime.log(colorize(rich, theme.muted, "  Commands: poolbot cron list | poolbot cron add --help | poolbot cron status"));
+    }
+    else {
+        runtime.log("  Commands: poolbot cron list | poolbot cron add --help | poolbot cron status");
+    }
+    runtime.log("");
+}
+export function registerCronDashboardCommand(cron) {
+    addGatewayClientOptions(cron
+        .command("dashboard")
+        .alias("dash")
+        .description("Visual dashboard for cron jobs")
+        .option("--all", "Include disabled jobs", false)
+        .option("--json", "Output JSON (disables visual dashboard)", false)
+        .action(async (opts) => {
+        try {
+            const res = await callGatewayFromCli("cron.list", opts, {
+                includeDisabled: Boolean(opts.all),
+            });
+            if (opts.json) {
+                defaultRuntime.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const jobs = res?.jobs ?? [];
+            printDashboardHeader();
+            printSummaryStats(jobs);
+            printJobsTable(jobs);
+            printLegend();
+            printFooter();
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    }));
+}

package/dist/cli/cron-cli/register.js

@@ -1,6 +1,7 @@
 import { formatDocsLink } from "../../terminal/links.js";
 import { theme } from "../../terminal/theme.js";
 import { registerCronAddCommand, registerCronListCommand, registerCronStatusCommand, } from "./register.cron-add.js";
+import { registerCronDashboardCommand } from "./register.cron-dashboard.js";
 import { registerCronEditCommand } from "./register.cron-edit.js";
 import { registerCronSimpleCommands } from "./register.cron-simple.js";
 export function registerCronCli(program) {
@@ -10,6 +11,7 @@ export function registerCronCli(program) {
         .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/cron", "docs.molt.bot/cli/cron")}\n`);
     registerCronStatusCommand(cron);
     registerCronListCommand(cron);
+    registerCronDashboardCommand(cron);
     registerCronAddCommand(cron);
     registerCronSimpleCommands(cron);
     registerCronEditCommand(cron);

package/dist/cli/errors.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+/**
+ * Structured error class for PoolBot CLI
+ * Provides rich error information with recovery suggestions
+ */
+export class PoolBotError extends Error {
+    code;
+    category;
+    recoverable;
+    severity;
+    suggestions;
+    context;
+    exitCode;
+    constructor(options) {
+        super(options.message);
+        this.name = "PoolBotError";
+        this.code = options.code;
+        this.category = options.category;
+        this.recoverable = options.recoverable;
+        this.severity = options.severity ?? "error";
+        this.suggestions = options.suggestions ?? [];
+        this.context = options.context;
+        this.exitCode = options.exitCode ?? 1;
+        if (options.cause) {
+            this.cause = options.cause;
+        }
+        // Maintain proper stack trace
+        Error.captureStackTrace?.(this, PoolBotError);
+    }
+    /**
+     * Format error for user display with suggestions
+     */
+    formatForDisplay() {
+        const lines = [`❌ ${this.message}`, `   Code: ${this.code}`];
+        if (this.suggestions.length > 0) {
+            lines.push("", "💡 Suggestions:");
+            for (const suggestion of this.suggestions) {
+                lines.push(`   • ${suggestion}`);
+            }
+        }
+        if (this.recoverable) {
+            lines.push("", "ℹ️  This error can be recovered from.");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Format error for JSON output
+     */
+    toJSON() {
+        const errorObj = {
+            message: this.message,
+            code: this.code,
+            category: this.category,
+            recoverable: this.recoverable,
+            severity: this.severity,
+            suggestions: this.suggestions,
+            context: this.context,
+            exitCode: this.exitCode,
+        };
+        if (this.cause) {
+            errorObj.cause = String(this.cause);
+        }
+        return { error: errorObj };
+    }
+}
+/**
+ * Error code registry with predefined common errors
+ */
+export const ErrorCodes = {
+    // Config errors (E1xxx)
+    CONFIG_INVALID: "E1001",
+    CONFIG_MISSING: "E1002",
+    CONFIG_DEPRECATED: "E1003",
+    CONFIG_VERSION_MISMATCH: "E1004",
+    // Gateway errors (E2xxx)
+    GATEWAY_NOT_RUNNING: "E2001",
+    GATEWAY_CONNECTION_FAILED: "E2002",
+    GATEWAY_TIMEOUT: "E2003",
+    GATEWAY_AUTH_FAILED: "E2004",
+    // Auth errors (E3xxx)
+    AUTH_TOKEN_MISSING: "E3001",
+    AUTH_TOKEN_INVALID: "E3002",
+    AUTH_OAUTH_EXPIRED: "E3003",
+    // Network errors (E4xxx)
+    NETWORK_UNREACHABLE: "E4001",
+    NETWORK_TIMEOUT: "E4002",
+    DNS_RESOLUTION_FAILED: "E4003",
+    // Validation errors (E5xxx)
+    VALIDATION_INVALID_INPUT: "E5001",
+    VALIDATION_MISSING_REQUIRED: "E5002",
+    VALIDATION_TYPE_MISMATCH: "E5003",
+    // Filesystem errors (E6xxx)
+    FILE_NOT_FOUND: "E6001",
+    FILE_PERMISSION_DENIED: "E6002",
+    FILE_ALREADY_EXISTS: "E6003",
+    // Plugin errors (E7xxx)
+    PLUGIN_LOAD_FAILED: "E7001",
+    PLUGIN_NOT_FOUND: "E7002",
+    PLUGIN_INCOMPATIBLE: "E7003",
+    // Completion errors (E8xxx)
+    COMPLETION_CACHE_MISSING: "E8001",
+    COMPLETION_SHELL_UNSUPPORTED: "E8002",
+    COMPLETION_PROFILE_WRITE_FAILED: "E8003",
+};
+/**
+ * Helper functions for common error scenarios
+ */
+export function createConfigError(message, suggestions, context) {
+    return new PoolBotError({
+        message,
+        code: ErrorCodes.CONFIG_INVALID,
+        category: "config",
+        recoverable: true,
+        suggestions: suggestions ?? ["Run `poolbot doctor` to check configuration"],
+        context,
+    });
+}
+export function createGatewayError(message, code, suggestions, context) {
+    return new PoolBotError({
+        message,
+        code,
+        category: "gateway",
+        recoverable: true,
+        suggestions: suggestions ?? [
+            "Run `poolbot gateway status` to check gateway health",
+            "Run `poolbot doctor` for diagnostics",
+        ],
+        context,
+    });
+}
+export function createValidationError(message, context) {
+    return new PoolBotError({
+        message,
+        code: ErrorCodes.VALIDATION_INVALID_INPUT,
+        category: "validation",
+        recoverable: true,
+        suggestions: ["Check command help with `--help` for usage information"],
+        context,
+    });
+}
+export function createCompletionError(message, code, suggestions) {
+    return new PoolBotError({
+        message,
+        code,
+        category: "config",
+        recoverable: true,
+        suggestions: suggestions ?? [
+            "Run `poolbot completion --write-state` to generate cache",
+            "Run `poolbot completion --install` to install to shell profile",
+        ],
+    });
+}
+/**
+ * Async wrapper that converts exceptions to PoolBotError
+ */
+export async function withErrorHandling(operation, errorMapper) {
+    try {
+        return await operation();
+    }
+    catch (err) {
+        if (err instanceof PoolBotError) {
+            throw err;
+        }
+        throw errorMapper(err);
+    }
+}
+/**
+ * Zod schema for validating error options
+ */
+export const PoolBotErrorSchema = z.object({
+    message: z.string(),
+    code: z.string(),
+    category: z.enum([
+        "config",
+        "gateway",
+        "auth",
+        "network",
+        "validation",
+        "filesystem",
+        "runtime",
+        "plugin",
+    ]),
+    recoverable: z.boolean(),
+    severity: z.enum(["error", "warning", "info"]).optional(),
+    suggestions: z.array(z.string()).optional(),
+    exitCode: z.number().optional(),
+});

package/dist/cli/program/command-registry.js

@@ -187,6 +187,19 @@ const coreEntries = [
             mod.registerSkillsCli(program);
         },
     },
+    {
+        commands: [
+            {
+                name: "swarm",
+                description: "Agent swarm coordination and management",
+                hasSubcommands: true,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("../swarm-cli/register.js");
+            mod.registerSwarmCommand(program);
+        },
+    },
 ];
 function collectCoreCliCommandNames(predicate) {
     const seen = new Set();

package/dist/cli/program/register.maintenance.js

@@ -6,6 +6,18 @@ import { defaultRuntime } from "../../runtime.js";
 import { formatDocsLink } from "../../terminal/links.js";
 import { theme } from "../../terminal/theme.js";
 import { runCommandWithRuntime } from "../cli-utils.js";
+const DOCTOR_CHECKS = [
+    "config",
+    "auth",
+    "gateway",
+    "completion",
+    "security",
+    "plugins",
+    "memory",
+    "workspace",
+    "state",
+    "all",
+];
 export function registerMaintenanceCommands(program) {
     program
         .command("doctor")
@@ -19,6 +31,13 @@ export function registerMaintenanceCommands(program) {
         .option("--non-interactive", "Run without prompts (safe migrations only)", false)
         .option("--generate-gateway-token", "Generate and configure a gateway token", false)
         .option("--deep", "Scan system services for extra gateway installs", false)
+        .option("--check <check>", `Run specific check: ${DOCTOR_CHECKS.join(", ")}`, (value) => {
+        if (!DOCTOR_CHECKS.includes(value)) {
+            throw new Error(`Invalid check: ${value}. Valid: ${DOCTOR_CHECKS.join(", ")}`);
+        }
+        return value;
+    })
+        .option("--json", "Output results in JSON format", false)
         .action(async (opts) => {
         await runCommandWithRuntime(defaultRuntime, async () => {
             await doctorCommand(defaultRuntime, {
@@ -29,6 +48,8 @@ export function registerMaintenanceCommands(program) {
                 nonInteractive: Boolean(opts.nonInteractive),
                 generateGatewayToken: Boolean(opts.generateGatewayToken),
                 deep: Boolean(opts.deep),
+                check: opts.check,
+                json: Boolean(opts.json),
             });
         });
     });

package/dist/cli/program/register.subclis.js

@@ -272,6 +272,15 @@ const entries = [
             mod.registerCompletionCli(program);
         },
     },
+    {
+        name: "telemetry",
+        description: "OpenTelemetry observability and metrics",
+        hasSubcommands: true,
+        register: async (program) => {
+            const mod = await import("../telemetry-cli/register.js");
+            mod.registerTelemetryCli(program);
+        },
+    },
 ];
 export function getSubCliEntries() {
     return entries;

package/dist/cli/swarm-cli/register.js

@@ -0,0 +1,8 @@
+import { registerSwarmCreateCommand, registerSwarmListCommand, registerSwarmStatusCommand, } from "./register.swarm-status.js";
+export function registerSwarmCommand(program) {
+    const swarm = program.command("swarm").description("Agent swarm coordination and management");
+    registerSwarmStatusCommand(swarm);
+    registerSwarmListCommand(swarm);
+    registerSwarmCreateCommand(swarm);
+    return swarm;
+}