@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/dist/telemetry/instrumentation.js

@@ -0,0 +1,66 @@
+import { getGlobalTelemetryService } from "../telemetry/service.js";
+export function withInstrumentation(options, fn) {
+    const telemetry = getGlobalTelemetryService();
+    if (!telemetry?.isEnabled()) {
+        return Promise.resolve(fn());
+    }
+    const spanName = `${options.component}.${options.operation}`;
+    const attributes = {
+        component: options.component,
+        operation: options.operation,
+        ...options.attributes,
+    };
+    telemetry.recordCounter(`poolbot.${options.component}.operations`, 1, {
+        operation: options.operation,
+    });
+    const startTime = Date.now();
+    return telemetry.withSpan(spanName, async () => {
+        try {
+            const result = await fn();
+            const duration = Date.now() - startTime;
+            telemetry.recordHistogram(`poolbot.${options.component}.duration_ms`, duration, {
+                operation: options.operation,
+            });
+            telemetry.recordCounter(`poolbot.${options.component}.success`, 1, {
+                operation: options.operation,
+            });
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            telemetry.recordHistogram(`poolbot.${options.component}.duration_ms`, duration, {
+                operation: options.operation,
+                error: "true",
+            });
+            telemetry.recordCounter(`poolbot.${options.component}.errors`, 1, {
+                operation: options.operation,
+                error_type: error instanceof Error ? error.name : "unknown",
+            });
+            throw error;
+        }
+    }, attributes);
+}
+export function recordMetric(name, value, attributes) {
+    const telemetry = getGlobalTelemetryService();
+    if (!telemetry?.isEnabled())
+        return;
+    telemetry.recordHistogram(name, value, attributes);
+}
+export function recordCounter(name, value = 1, attributes) {
+    const telemetry = getGlobalTelemetryService();
+    if (!telemetry?.isEnabled())
+        return;
+    telemetry.recordCounter(name, value, attributes);
+}
+export function recordGauge(name, value, attributes) {
+    const telemetry = getGlobalTelemetryService();
+    if (!telemetry?.isEnabled())
+        return;
+    telemetry.recordGauge(name, value, attributes);
+}
+export function recordHistogram(name, value, attributes) {
+    const telemetry = getGlobalTelemetryService();
+    if (!telemetry?.isEnabled())
+        return;
+    telemetry.recordHistogram(name, value, attributes);
+}

package/dist/telemetry/service.js

@@ -0,0 +1,345 @@
+import { context, metrics, trace } from "@opentelemetry/api";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ConsoleMetricExporter, InMemoryMetricExporter, MeterProvider, PeriodicExportingMetricReader, } from "@opentelemetry/sdk-metrics";
+import { BatchSpanProcessor, ConsoleSpanExporter, InMemorySpanExporter, NodeTracerProvider, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-node";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+const log = createSubsystemLogger("telemetry");
+export const defaultTelemetryConfig = {
+    enabled: true,
+    serviceName: "poolbot",
+    serviceVersion: process.env.npm_package_version ?? "unknown",
+    tracing: {
+        enabled: true,
+        exporter: "console",
+        sampleRate: 1.0,
+    },
+    metrics: {
+        enabled: true,
+        exporter: "console",
+        exportIntervalMs: 60000,
+        aggregationTemporality: 1, // CUMULATIVE
+    },
+};
+export class TelemetryService {
+    config;
+    tracerProvider;
+    meterProvider;
+    tracer;
+    meter;
+    inMemorySpanExporter;
+    inMemoryMetricExporter;
+    counters = new Map();
+    histograms = new Map();
+    gauges = new Map();
+    gaugeValues = new Map();
+    activeSpans = new Map();
+    isStarted = false;
+    alertEngine;
+    onAlertCallback;
+    constructor(config = {}) {
+        this.config = { ...defaultTelemetryConfig, ...config };
+        if (config.tracing) {
+            this.config.tracing = { ...defaultTelemetryConfig.tracing, ...config.tracing };
+        }
+        if (config.metrics) {
+            this.config.metrics = { ...defaultTelemetryConfig.metrics, ...config.metrics };
+        }
+    }
+    async start() {
+        if (this.isStarted || !this.config.enabled) {
+            return;
+        }
+        log.info("Starting telemetry service...");
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: this.config.serviceName,
+            [ATTR_SERVICE_VERSION]: this.config.serviceVersion,
+            ...this.config.attributes,
+        });
+        if (this.config.tracing.enabled) {
+            this.setupTracing(resource);
+        }
+        if (this.config.metrics.enabled) {
+            this.setupMetrics(resource);
+        }
+        this.isStarted = true;
+        log.info("Telemetry service started");
+    }
+    stop() {
+        if (!this.isStarted) {
+            return;
+        }
+        log.info("Stopping telemetry service...");
+        void this.tracerProvider?.shutdown();
+        void this.meterProvider?.shutdown();
+        this.isStarted = false;
+        log.info("Telemetry service stopped");
+    }
+    setupTracing(resource) {
+        const spanProcessors = [];
+        switch (this.config.tracing.exporter) {
+            case "console":
+                spanProcessors.push(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+                break;
+            case "memory":
+                this.inMemorySpanExporter = new InMemorySpanExporter();
+                spanProcessors.push(new SimpleSpanProcessor(this.inMemorySpanExporter));
+                break;
+            case "otlp": {
+                const endpoint = this.config.tracing.otlpEndpoint ?? "http://localhost:4318/v1/traces";
+                spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({ url: endpoint })));
+                break;
+            }
+            case "none":
+            default:
+                break;
+        }
+        this.tracerProvider = new NodeTracerProvider({
+            resource,
+            spanProcessors,
+        });
+        this.tracerProvider.register();
+        this.tracer = trace.getTracer(this.config.serviceName, this.config.serviceVersion);
+    }
+    setupMetrics(resource) {
+        const readers = [];
+        switch (this.config.metrics.exporter) {
+            case "console":
+                readers.push(new PeriodicExportingMetricReader({
+                    exporter: new ConsoleMetricExporter(),
+                    exportIntervalMillis: this.config.metrics.exportIntervalMs,
+                }));
+                break;
+            case "memory":
+                this.inMemoryMetricExporter = new InMemoryMetricExporter(this.config.metrics.aggregationTemporality);
+                readers.push(new PeriodicExportingMetricReader({
+                    exporter: this.inMemoryMetricExporter,
+                    exportIntervalMillis: this.config.metrics.exportIntervalMs,
+                }));
+                break;
+            case "otlp": {
+                const endpoint = this.config.metrics.otlpEndpoint ?? "http://localhost:4318/v1/metrics";
+                readers.push(new PeriodicExportingMetricReader({
+                    exporter: new OTLPMetricExporter({ url: endpoint }),
+                    exportIntervalMillis: this.config.metrics.exportIntervalMs,
+                }));
+                break;
+            }
+            case "none":
+            default:
+                break;
+        }
+        this.meterProvider = new MeterProvider({
+            resource,
+            readers,
+        });
+        metrics.setGlobalMeterProvider(this.meterProvider);
+        this.meter = metrics.getMeter(this.config.serviceName, this.config.serviceVersion);
+    }
+    isEnabled() {
+        return this.isStarted && this.config.enabled;
+    }
+    createSpan(name, attributes) {
+        if (!this.tracer)
+            return undefined;
+        const span = this.tracer.startSpan(name, { attributes });
+        const spanId = span.spanContext().spanId;
+        this.activeSpans.set(spanId, span);
+        return span;
+    }
+    endSpan(span, status) {
+        if (status) {
+            const statusCode = status.code === "ok" ? 1 : 2;
+            span.setStatus({ code: statusCode, message: status.message });
+        }
+        span.end();
+        this.activeSpans.delete(span.spanContext().spanId);
+    }
+    withSpan(name, fn, attributes) {
+        if (!this.tracer) {
+            return Promise.resolve(fn());
+        }
+        return this.tracer.startActiveSpan(name, { attributes }, async (span) => {
+            try {
+                const result = await fn();
+                span.setStatus({ code: 1 }); // OK
+                return result;
+            }
+            catch (error) {
+                span.recordException(error);
+                span.setStatus({ code: 2, message: String(error) }); // ERROR
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    recordCounter(name, value = 1, attributes) {
+        if (!this.meter)
+            return;
+        let counter = this.counters.get(name);
+        if (!counter) {
+            counter = this.meter.createCounter(name);
+            this.counters.set(name, counter);
+        }
+        counter.add(value, attributes);
+    }
+    recordHistogram(name, value, attributes, options) {
+        if (!this.meter)
+            return;
+        let histogram = this.histograms.get(name);
+        if (!histogram) {
+            histogram = this.meter.createHistogram(name, options);
+            this.histograms.set(name, histogram);
+        }
+        histogram.record(value, attributes);
+    }
+    recordGauge(name, value, _attributes) {
+        if (!this.meter)
+            return;
+        const existingGauge = this.gauges.get(name);
+        if (!existingGauge) {
+            const newGauge = this.meter.createObservableGauge(name, {
+                valueType: 1, // DOUBLE
+            });
+            this.gauges.set(name, newGauge);
+        }
+        this.gaugeValues.set(name, value);
+    }
+    addEvent(span, name, attributes) {
+        span.addEvent(name, attributes);
+    }
+    getCurrentSpan() {
+        return trace.getSpan(context.active()) ?? undefined;
+    }
+    getSnapshot() {
+        if (!this.inMemorySpanExporter || !this.inMemoryMetricExporter) {
+            return undefined;
+        }
+        const spans = this.inMemorySpanExporter.getFinishedSpans();
+        const exportedMetrics = this.inMemoryMetricExporter.getMetrics();
+        const spanInfos = spans.map((span) => {
+            const spanContext = span.spanContext();
+            const startTime = span.startTime;
+            const endTime = span.endTime;
+            return {
+                traceId: spanContext.traceId,
+                spanId: spanContext.spanId,
+                parentSpanId: span.parentSpanId,
+                name: span.name,
+                startTime: startTime[0] * 1000000000 + startTime[1],
+                endTime: endTime ? endTime[0] * 1000000000 + endTime[1] : undefined,
+                status: span.status.code === 0 ? "unset" : span.status.code === 1 ? "ok" : "error",
+                attributes: Object.fromEntries(Object.entries(span.attributes)),
+                events: span.events.map((e) => {
+                    const time = e.time;
+                    return {
+                        name: e.name,
+                        timestamp: time[0] * 1000000000 + time[1],
+                        attributes: Object.fromEntries(Object.entries(e.attributes ?? {})),
+                    };
+                }),
+            };
+        });
+        const metricValues = [];
+        for (const metric of exportedMetrics) {
+            for (const scopeMetric of metric.scopeMetrics) {
+                for (const m of scopeMetric.metrics) {
+                    const descriptor = m.descriptor;
+                    const dataPoints = m.dataPoints;
+                    if (dataPoints) {
+                        for (const dp of dataPoints) {
+                            metricValues.push({
+                                name: descriptor.name,
+                                value: typeof dp.value === "number" ? dp.value : 0,
+                                attributes: dp.attributes,
+                                timestamp: Date.now(),
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        return {
+            timestamp: Date.now(),
+            spans: spanInfos,
+            metrics: metricValues,
+        };
+    }
+    clearSnapshot() {
+        this.inMemorySpanExporter?.reset();
+        this.inMemoryMetricExporter?.reset();
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    async shutdown() {
+        log.debug("telemetry: shutting down");
+        await this.tracerProvider?.shutdown();
+        await this.meterProvider?.shutdown();
+    }
+    setAlertEngine(engine) {
+        this.alertEngine = engine;
+        engine.onAlert((alert) => {
+            this.onAlertCallback?.(alert);
+        });
+        log.info(`Alert engine configured with ${engine.getRules().length} rules`);
+    }
+    onAlert(callback) {
+        this.onAlertCallback = callback;
+    }
+    evaluateAlerts(snapshot) {
+        if (!this.alertEngine)
+            return [];
+        const snap = snapshot ?? this.getSnapshot();
+        if (!snap)
+            return [];
+        return this.alertEngine.evaluate(snap);
+    }
+}
+let globalTelemetryService;
+export function getGlobalTelemetryService() {
+    return globalTelemetryService;
+}
+export function setGlobalTelemetryService(service) {
+    globalTelemetryService = service;
+}
+export function createTelemetryService(config) {
+    return new TelemetryService(config);
+}
+/**
+ * Convert OTel config from zod schema format to TelemetryService config format.
+ */
+export function telemetryConfigFromOtelConfig(otel, opts) {
+    if (!otel?.enabled) {
+        return {
+            ...defaultTelemetryConfig,
+            enabled: false,
+            tracing: { ...defaultTelemetryConfig.tracing, enabled: false },
+            metrics: { ...defaultTelemetryConfig.metrics, enabled: false },
+        };
+    }
+    const exporterType = otel.endpoint ? "otlp" : "console";
+    return {
+        enabled: true,
+        serviceName: otel.serviceName ?? opts?.defaultServiceName ?? "poolbot",
+        serviceVersion: opts?.serviceVersion ?? process.env.npm_package_version ?? "unknown",
+        tracing: {
+            enabled: otel.traces ?? true,
+            exporter: exporterType,
+            otlpEndpoint: otel.endpoint,
+            sampleRate: otel.sampleRate ?? 1.0,
+        },
+        metrics: {
+            enabled: otel.metrics ?? true,
+            exporter: exporterType,
+            otlpEndpoint: otel.endpoint,
+            exportIntervalMs: otel.flushIntervalMs ?? 60000,
+            aggregationTemporality: 1, // CUMULATIVE
+        },
+        attributes: otel.headers,
+    };
+}

package/dist/test-utils/index.js

@@ -0,0 +1,219 @@
+/**
+ * Test Utilities for PoolBot
+ *
+ * Shared testing helpers and fixtures for consistent testing.
+ */
+import { afterEach } from "vitest";
+/**
+ * Frozen time utility for deterministic time-based tests
+ */
+export class FrozenTime {
+    originalDateNow;
+    currentTime;
+    constructor(startTime = 1700000000000) {
+        this.originalDateNow = Date.now;
+        this.currentTime = startTime;
+    }
+    /**
+     * Freeze time at a specific timestamp
+     */
+    freeze(timestamp) {
+        if (timestamp !== undefined) {
+            this.currentTime = timestamp;
+        }
+        Date.now = () => this.currentTime;
+    }
+    /**
+     * Advance time by milliseconds
+     */
+    advance(ms) {
+        this.currentTime += ms;
+    }
+    /**
+     * Get current frozen time
+     */
+    now() {
+        return this.currentTime;
+    }
+    /**
+     * Restore original Date.now
+     */
+    restore() {
+        Date.now = this.originalDateNow;
+    }
+    /**
+     * Create ISO timestamp from current frozen time
+     */
+    toISOString() {
+        return new Date(this.currentTime).toISOString();
+    }
+}
+/**
+ * Create a test fixture with isolated state
+ */
+export function createFixture(factory, options = {}) {
+    let instance = null;
+    const get = () => {
+        if (!instance) {
+            instance = factory();
+        }
+        return instance;
+    };
+    const reset = () => {
+        instance = null;
+    };
+    if (options.autoCleanup !== false) {
+        afterEach(reset);
+    }
+    return { get, reset };
+}
+/**
+ * Type-safe test case builder
+ */
+export function typedCases(cases) {
+    return cases;
+}
+/**
+ * Temporary directory helper
+ */
+export class TempDir {
+    dirs = [];
+    /**
+     * Create a temporary directory
+     */
+    create(prefix = "poolbot-test-") {
+        const dir = `${prefix}${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        this.dirs.push(dir);
+        return dir;
+    }
+    /**
+     * Clean up all created directories
+     */
+    cleanup() {
+        this.dirs = [];
+    }
+}
+/**
+ * Mock utilities for common dependencies
+ */
+export class MockFactory {
+    /**
+     * Create a mock function with tracking
+     */
+    static fn(implementation) {
+        const calls = [];
+        const mockFn = ((...args) => {
+            const result = implementation ? implementation(...args) : undefined;
+            calls.push({ args, result });
+            return result;
+        });
+        mockFn.calls = calls;
+        mockFn.mockClear = () => {
+            calls.length = 0;
+        };
+        return mockFn;
+    }
+    /**
+     * Create a mock logger
+     */
+    static logger() {
+        return {
+            info: MockFactory.fn(),
+            warn: MockFactory.fn(),
+            error: MockFactory.fn(),
+            debug: MockFactory.fn(),
+            logs: [],
+        };
+    }
+}
+/**
+ * Assertion helpers
+ */
+export class Assert {
+    /**
+     * Assert that a promise resolves within a timeout
+     */
+    static async resolvesWithin(promise, timeoutMs, message) {
+        const timeout = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(message ?? `Promise did not resolve within ${timeoutMs}ms`)), timeoutMs);
+        });
+        return Promise.race([promise, timeout]);
+    }
+    /**
+     * Assert that an error is thrown
+     */
+    static async throws(fn, expectedMessage) {
+        try {
+            await fn();
+            throw new Error("Expected function to throw but it did not");
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                if (expectedMessage) {
+                    if (expectedMessage instanceof RegExp) {
+                        if (!expectedMessage.test(error.message)) {
+                            throw new Error(`Expected error message to match ${expectedMessage}, got: ${error.message}`);
+                        }
+                    }
+                    else if (!error.message.includes(expectedMessage)) {
+                        throw new Error(`Expected error message to include "${expectedMessage}", got: ${error.message}`);
+                    }
+                }
+                return error;
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Data generators for tests
+ */
+export class Generators {
+    /**
+     * Generate a UUID v4
+     */
+    static uuid() {
+        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === "x" ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+    /**
+     * Generate a random session ID
+     */
+    static sessionId() {
+        return `session-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    }
+    /**
+     * Generate a timestamp with optional offset
+     */
+    static timestamp(offsetMs = 0) {
+        return Date.now() + offsetMs;
+    }
+    /**
+     * Generate random text of specified length
+     */
+    static text(length = 100) {
+        const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 ";
+        let result = "";
+        for (let i = 0; i < length; i++) {
+            result += chars.charAt(Math.floor(Math.random() * chars.length));
+        }
+        return result;
+    }
+}
+/**
+ * Setup helper for common test patterns
+ */
+export function setupTestEnvironment() {
+    const frozenTime = new FrozenTime();
+    const tempDir = new TempDir();
+    frozenTime.freeze();
+    const cleanup = () => {
+        frozenTime.restore();
+        tempDir.cleanup();
+    };
+    afterEach(cleanup);
+    return { frozenTime, tempDir, cleanup };
+}

package/dist/tui/components/assistant-message.js

@@ -1,16 +1,20 @@
 import { Container, Markdown, Spacer } from "@mariozechner/pi-tui";
 import { markdownTheme, theme } from "../theme/theme.js";
+import { sanitizeRenderableText } from "../utils/text-sanitization.js";
 export class AssistantMessageComponent extends Container {
     body;
     constructor(text) {
         super();
-        this.body = new Markdown(text, 1, 0, markdownTheme, {
+        // Sanitize text before rendering to prevent terminal corruption
+        const sanitizedText = sanitizeRenderableText(text);
+        this.body = new Markdown(sanitizedText, 1, 0, markdownTheme, {
             color: (line) => theme.fg(line),
         });
         this.addChild(new Spacer(1));
         this.addChild(this.body);
     }
     setText(text) {
-        this.body.setText(text);
+        // Sanitize text before updating
+        this.body.setText(sanitizeRenderableText(text));
     }
 }

package/dist/tui/components/hyperlink-markdown.js

@@ -0,0 +1,32 @@
+/**
+ * Hyperlink Markdown Component
+ *
+ * Extends Markdown component with OSC 8 hyperlink support.
+ * Automatically detects and converts URLs to clickable hyperlinks.
+ */
+import { Markdown } from "@mariozechner/pi-tui";
+import { hyperlinkUrls } from "../utils/osc8-hyperlinks.js";
+/**
+ * Markdown component with automatic hyperlink detection
+ */
+export class HyperlinkMarkdown extends Markdown {
+    constructor(text, padLeft, padRight, theme, options) {
+        // Convert URLs to hyperlinks before passing to parent
+        const textWithHyperlinks = hyperlinkUrls(text);
+        super(textWithHyperlinks, padLeft, padRight, theme, options);
+    }
+    /**
+     * Update text with hyperlink conversion
+     */
+    setText(text) {
+        const textWithHyperlinks = hyperlinkUrls(text);
+        super.setText(textWithHyperlinks);
+    }
+    /**
+     * Set raw text without hyperlink conversion
+     * Use this if you need to bypass automatic URL detection
+     */
+    setRawText(text) {
+        super.setText(text);
+    }
+}