confused-ai-core 0.1.0

package/src/production/graceful-shutdown.ts

@@ -0,0 +1,251 @@
+/**
+ * Graceful Shutdown - Agno-style Production Lifecycle Management
+ *
+ * Handles process termination signals gracefully:
+ * - SIGTERM/SIGINT signal handling
+ * - In-flight request draining
+ * - Resource cleanup callbacks
+ * - Configurable shutdown timeout
+ */
+
+import type { Logger } from '../observability/types.js';
+
+/** Shutdown handler configuration */
+export interface GracefulShutdownConfig {
+    /** Timeout for shutdown in ms (default: 30000) */
+    readonly timeoutMs?: number;
+    /** Signals to handle (default: ['SIGTERM', 'SIGINT']) */
+    readonly signals?: NodeJS.Signals[];
+    /** Optional logger */
+    readonly logger?: Logger;
+    /** Force exit after timeout (default: true) */
+    readonly forceExitOnTimeout?: boolean;
+}
+
+/** Cleanup handler function */
+export type CleanupHandler = () => Promise<void> | void;
+
+/** Shutdown event */
+export interface ShutdownEvent {
+    readonly signal?: NodeJS.Signals;
+    readonly reason?: string;
+    readonly timestamp: Date;
+}
+
+/**
+ * Graceful Shutdown Manager - handles process termination cleanly.
+ *
+ * @example
+ * const shutdown = new GracefulShutdown({ timeoutMs: 30000 });
+ *
+ * // Register cleanup handlers
+ * shutdown.addHandler('database', async () => {
+ *   await db.close();
+ * });
+ *
+ * shutdown.addHandler('http-server', async () => {
+ *   await server.close();
+ * });
+ *
+ * // Start listening for signals
+ * shutdown.listen();
+ */
+export class GracefulShutdown {
+    private readonly config: Required<Omit<GracefulShutdownConfig, 'logger'>> &
+        Pick<GracefulShutdownConfig, 'logger'>;
+    private readonly handlers = new Map<string, CleanupHandler>();
+    private isShuttingDown = false;
+    private shutdownPromise: Promise<void> | null = null;
+
+    constructor(config: GracefulShutdownConfig = {}) {
+        this.config = {
+            timeoutMs: config.timeoutMs ?? 30_000,
+            signals: config.signals ?? ['SIGTERM', 'SIGINT'],
+            logger: config.logger,
+            forceExitOnTimeout: config.forceExitOnTimeout ?? true,
+        };
+    }
+
+    /** Check if shutdown is in progress */
+    isInProgress(): boolean {
+        return this.isShuttingDown;
+    }
+
+    /** Add a cleanup handler */
+    addHandler(name: string, handler: CleanupHandler): void {
+        if (this.handlers.has(name)) {
+            this.log('warn', `Replacing existing handler: ${name}`);
+        }
+        this.handlers.set(name, handler);
+    }
+
+    /** Remove a cleanup handler */
+    removeHandler(name: string): boolean {
+        return this.handlers.delete(name);
+    }
+
+    /** Get registered handler names */
+    getHandlerNames(): string[] {
+        return Array.from(this.handlers.keys());
+    }
+
+    /**
+     * Start listening for shutdown signals.
+     * Only call this once.
+     */
+    listen(): void {
+        for (const signal of this.config.signals) {
+            process.on(signal, () => {
+                this.log('info', `Received ${signal}, initiating graceful shutdown...`);
+                this.shutdown({ signal, timestamp: new Date() });
+            });
+        }
+
+        this.log('debug', `Listening for signals: ${this.config.signals.join(', ')}`);
+    }
+
+    /**
+     * Programmatically trigger shutdown.
+     * Safe to call multiple times - subsequent calls return the same promise.
+     */
+    async shutdown(event?: Partial<ShutdownEvent>): Promise<void> {
+        if (this.shutdownPromise) {
+            return this.shutdownPromise;
+        }
+
+        this.isShuttingDown = true;
+        const shutdownEvent: ShutdownEvent = {
+            signal: event?.signal,
+            reason: event?.reason,
+            timestamp: event?.timestamp ?? new Date(),
+        };
+
+        this.shutdownPromise = this.executeShutdown(shutdownEvent);
+        return this.shutdownPromise;
+    }
+
+    /**
+     * Wait for shutdown to complete (for tests or manual control).
+     */
+    async waitForShutdown(): Promise<void> {
+        if (this.shutdownPromise) {
+            await this.shutdownPromise;
+        }
+    }
+
+    // --- Private methods ---
+
+    private async executeShutdown(event: ShutdownEvent): Promise<void> {
+        this.log('info', 'Starting graceful shutdown...');
+
+        const timeout = this.createTimeout();
+
+        try {
+            await Promise.race([
+                this.runHandlers(),
+                timeout.promise,
+            ]);
+
+            this.log('info', 'Graceful shutdown completed');
+        } catch (error) {
+            this.log('error', `Shutdown error: ${error instanceof Error ? error.message : error}`);
+        } finally {
+            timeout.clear();
+
+            if (this.config.forceExitOnTimeout) {
+                // Give a moment for logs to flush
+                setTimeout(() => {
+                    process.exit(event.signal === 'SIGTERM' ? 0 : 1);
+                }, 100);
+            }
+        }
+    }
+
+    private async runHandlers(): Promise<void> {
+        const handlerEntries = Array.from(this.handlers.entries());
+        const results: { name: string; success: boolean; error?: Error }[] = [];
+
+        // Run handlers in parallel
+        await Promise.all(
+            handlerEntries.map(async ([name, handler]) => {
+                const startTime = Date.now();
+                try {
+                    await handler();
+                    this.log('debug', `Handler '${name}' completed in ${Date.now() - startTime}ms`);
+                    results.push({ name, success: true });
+                } catch (error) {
+                    this.log('error', `Handler '${name}' failed: ${error instanceof Error ? error.message : error}`);
+                    results.push({ name, success: false, error: error as Error });
+                }
+            })
+        );
+
+        const failed = results.filter(r => !r.success);
+        if (failed.length > 0) {
+            this.log('warn', `${failed.length}/${results.length} handlers failed during shutdown`);
+        }
+    }
+
+    private createTimeout(): { promise: Promise<never>; clear: () => void } {
+        let timeoutId: NodeJS.Timeout;
+
+        const promise = new Promise<never>((_, reject) => {
+            timeoutId = setTimeout(() => {
+                this.log('warn', `Shutdown timeout (${this.config.timeoutMs}ms) reached, forcing exit`);
+                reject(new Error('Shutdown timeout'));
+            }, this.config.timeoutMs);
+        });
+
+        return {
+            promise,
+            clear: () => clearTimeout(timeoutId),
+        };
+    }
+
+    private log(level: 'debug' | 'info' | 'warn' | 'error', message: string): void {
+        if (this.config.logger) {
+            this.config.logger[level](message);
+        } else {
+            const prefix = `[GracefulShutdown] [${level.toUpperCase()}]`;
+            if (level === 'error') {
+                console.error(prefix, message);
+            } else if (level === 'warn') {
+                console.warn(prefix, message);
+            } else {
+                console.log(prefix, message);
+            }
+        }
+    }
+}
+
+/**
+ * Create a simple shutdown manager with common defaults.
+ */
+export function createGracefulShutdown(
+    handlers?: Record<string, CleanupHandler>,
+    config?: GracefulShutdownConfig
+): GracefulShutdown {
+    const shutdown = new GracefulShutdown(config);
+
+    if (handlers) {
+        for (const [name, handler] of Object.entries(handlers)) {
+            shutdown.addHandler(name, handler);
+        }
+    }
+
+    return shutdown;
+}
+
+/**
+ * Wrap an async operation with shutdown awareness.
+ * Will reject if shutdown is in progress.
+ */
+export function withShutdownGuard<T>(
+    shutdown: GracefulShutdown,
+    fn: () => Promise<T>
+): Promise<T> {
+    if (shutdown.isInProgress()) {
+        return Promise.reject(new Error('Operation rejected: shutdown in progress'));
+    }
+    return fn();
+}

package/src/production/health.ts

@@ -0,0 +1,333 @@
+/**
+ * Health Check System - Agno-style AgentOS Production Probes
+ *
+ * Kubernetes-compatible health check system with:
+ * - Liveness probe (is the process alive)
+ * - Readiness probe (can accept traffic)
+ * - Dependency health checks (LLM, database, etc.)
+ * - Aggregated health status
+ */
+
+import type { LLMProvider } from '../llm/types.js';
+import type { SessionStore } from '../session/types.js';
+
+/** Health check status */
+export enum HealthStatus {
+    /** Everything is working */
+    HEALTHY = 'HEALTHY',
+    /** Some components degraded but still functional */
+    DEGRADED = 'DEGRADED',
+    /** Critical failure, not accepting traffic */
+    UNHEALTHY = 'UNHEALTHY',
+    /** Status unknown (check not yet run) */
+    UNKNOWN = 'UNKNOWN',
+}
+
+/** Individual component health result */
+export interface ComponentHealth {
+    readonly name: string;
+    readonly status: HealthStatus;
+    readonly message?: string;
+    readonly latencyMs?: number;
+    readonly lastCheckedAt: Date;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/** Aggregated health check result */
+export interface HealthCheckResult {
+    readonly status: HealthStatus;
+    readonly uptime: number;
+    readonly version?: string;
+    readonly components: ComponentHealth[];
+    readonly timestamp: Date;
+}
+
+/** Health check configuration */
+export interface HealthCheckConfig {
+    /** Application version (optional, for display) */
+    readonly version?: string;
+    /** Timeout for individual checks in ms (default: 5000) */
+    readonly checkTimeoutMs?: number;
+    /** Components to check */
+    readonly components?: HealthComponent[];
+}
+
+/** A component that can be health-checked */
+export interface HealthComponent {
+    readonly name: string;
+    check(): Promise<Omit<ComponentHealth, 'name' | 'lastCheckedAt'>>;
+}
+
+/**
+ * Health Check Manager - aggregates component health checks.
+ *
+ * @example
+ * const health = new HealthCheckManager({
+ *   version: '1.0.0',
+ *   components: [
+ *     createLLMHealthCheck(llmProvider),
+ *     createSessionStoreHealthCheck(sessionStore),
+ *   ],
+ * });
+ *
+ * // Use in HTTP endpoint
+ * app.get('/health', async (req, res) => {
+ *   const result = await health.check();
+ *   res.status(result.status === 'HEALTHY' ? 200 : 503).json(result);
+ * });
+ */
+export class HealthCheckManager {
+    private readonly config: Required<Omit<HealthCheckConfig, 'version'>> &
+        Pick<HealthCheckConfig, 'version'>;
+    private readonly startTime = Date.now();
+    private lastResult: HealthCheckResult | null = null;
+
+    constructor(config: HealthCheckConfig = {}) {
+        this.config = {
+            version: config.version,
+            checkTimeoutMs: config.checkTimeoutMs ?? 5_000,
+            components: config.components ?? [],
+        };
+    }
+
+    /** Add a health component */
+    addComponent(component: HealthComponent): void {
+        this.config.components.push(component);
+    }
+
+    /** Remove a health component by name */
+    removeComponent(name: string): void {
+        const index = this.config.components.findIndex(c => c.name === name);
+        if (index !== -1) {
+            this.config.components.splice(index, 1);
+        }
+    }
+
+    /** Get uptime in seconds */
+    getUptime(): number {
+        return Math.floor((Date.now() - this.startTime) / 1000);
+    }
+
+    /** Get last health check result (if any) */
+    getLastResult(): HealthCheckResult | null {
+        return this.lastResult;
+    }
+
+    /**
+     * Liveness probe - is the process alive?
+     * Returns immediately, no component checks.
+     */
+    liveness(): { status: HealthStatus; uptime: number } {
+        return {
+            status: HealthStatus.HEALTHY,
+            uptime: this.getUptime(),
+        };
+    }
+
+    /**
+     * Readiness probe - can the service accept traffic?
+     * Checks all components and returns aggregated status.
+     */
+    async readiness(): Promise<HealthCheckResult> {
+        return this.check();
+    }
+
+    /**
+     * Full health check - check all components.
+     */
+    async check(): Promise<HealthCheckResult> {
+        const timestamp = new Date();
+        const components: ComponentHealth[] = [];
+
+        for (const component of this.config.components) {
+            const startTime = Date.now();
+            try {
+                const result = await Promise.race([
+                    component.check(),
+                    this.timeout(this.config.checkTimeoutMs),
+                ]);
+
+                if (result === 'TIMEOUT') {
+                    components.push({
+                        name: component.name,
+                        status: HealthStatus.UNHEALTHY,
+                        message: 'Health check timed out',
+                        latencyMs: this.config.checkTimeoutMs,
+                        lastCheckedAt: new Date(),
+                    });
+                } else {
+                    components.push({
+                        ...result,
+                        name: component.name,
+                        latencyMs: Date.now() - startTime,
+                        lastCheckedAt: new Date(),
+                    });
+                }
+            } catch (error) {
+                components.push({
+                    name: component.name,
+                    status: HealthStatus.UNHEALTHY,
+                    message: error instanceof Error ? error.message : String(error),
+                    latencyMs: Date.now() - startTime,
+                    lastCheckedAt: new Date(),
+                });
+            }
+        }
+
+        // Aggregate status
+        const status = this.aggregateStatus(components);
+
+        this.lastResult = {
+            status,
+            uptime: this.getUptime(),
+            version: this.config.version,
+            components,
+            timestamp,
+        };
+
+        return this.lastResult;
+    }
+
+    private aggregateStatus(components: ComponentHealth[]): HealthStatus {
+        if (components.length === 0) {
+            return HealthStatus.HEALTHY;
+        }
+
+        const hasUnhealthy = components.some(c => c.status === HealthStatus.UNHEALTHY);
+        const hasDegraded = components.some(c => c.status === HealthStatus.DEGRADED);
+
+        if (hasUnhealthy) return HealthStatus.UNHEALTHY;
+        if (hasDegraded) return HealthStatus.DEGRADED;
+        return HealthStatus.HEALTHY;
+    }
+
+    private timeout(ms: number): Promise<'TIMEOUT'> {
+        return new Promise(resolve => setTimeout(() => resolve('TIMEOUT'), ms));
+    }
+}
+
+// --- Built-in Health Components ---
+
+/**
+ * Create a health check for an LLM provider.
+ * Performs a minimal completion to verify connectivity.
+ */
+export function createLLMHealthCheck(
+    llm: LLMProvider,
+    name = 'llm'
+): HealthComponent {
+    return {
+        name,
+        async check() {
+            try {
+                // Minimal test call
+                await llm.generateText([
+                    { role: 'user', content: 'test' },
+                ], { maxTokens: 1 });
+
+                return { status: HealthStatus.HEALTHY };
+            } catch (error) {
+                return {
+                    status: HealthStatus.UNHEALTHY,
+                    message: error instanceof Error ? error.message : 'LLM check failed',
+                };
+            }
+        },
+    };
+}
+
+/**
+ * Create a health check for a session store.
+ * Performs a read operation to verify connectivity.
+ */
+export function createSessionStoreHealthCheck(
+    store: SessionStore,
+    name = 'session-store'
+): HealthComponent {
+    return {
+        name,
+        async check() {
+            try {
+                // Try to get a non-existent session (should return null, not error)
+                await store.get('__health_check_probe__');
+                return { status: HealthStatus.HEALTHY };
+            } catch (error) {
+                return {
+                    status: HealthStatus.UNHEALTHY,
+                    message: error instanceof Error ? error.message : 'Session store check failed',
+                };
+            }
+        },
+    };
+}
+
+/**
+ * Create a custom health check from an async function.
+ */
+export function createCustomHealthCheck(
+    name: string,
+    checkFn: () => Promise<boolean | { status: HealthStatus; message?: string }>
+): HealthComponent {
+    return {
+        name,
+        async check() {
+            try {
+                const result = await checkFn();
+                if (typeof result === 'boolean') {
+                    return {
+                        status: result ? HealthStatus.HEALTHY : HealthStatus.UNHEALTHY,
+                    };
+                }
+                return result;
+            } catch (error) {
+                return {
+                    status: HealthStatus.UNHEALTHY,
+                    message: error instanceof Error ? error.message : 'Check failed',
+                };
+            }
+        },
+    };
+}
+
+/**
+ * Create an HTTP health check for external dependencies.
+ */
+export function createHttpHealthCheck(
+    name: string,
+    url: string,
+    options?: { method?: string; expectedStatus?: number; timeoutMs?: number }
+): HealthComponent {
+    const { method = 'GET', expectedStatus = 200, timeoutMs = 5000 } = options ?? {};
+
+    return {
+        name,
+        async check() {
+            try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+                const response = await fetch(url, {
+                    method,
+                    signal: controller.signal,
+                });
+
+                clearTimeout(timeout);
+
+                if (response.status === expectedStatus) {
+                    return { status: HealthStatus.HEALTHY };
+                }
+
+                return {
+                    status: HealthStatus.DEGRADED,
+                    message: `Unexpected status: ${response.status}`,
+                    metadata: { statusCode: response.status },
+                };
+            } catch (error) {
+                return {
+                    status: HealthStatus.UNHEALTHY,
+                    message: error instanceof Error ? error.message : 'HTTP check failed',
+                };
+            }
+        },
+    };
+}

package/src/production/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Production module: runtime, control plane, evals, resilience.
+ */
+
+export * from './types.js';
+export { createLatencyEval } from './latency-eval.js';
+export type { LatencyEvalConfig } from './latency-eval.js';
+
+// Resilience patterns
+export {
+    CircuitBreaker,
+    CircuitState,
+    CircuitOpenError,
+    createLLMCircuitBreaker,
+} from './circuit-breaker.js';
+export type { CircuitBreakerConfig, CircuitBreakerResult } from './circuit-breaker.js';
+
+export {
+    RateLimiter,
+    RateLimitError,
+    createOpenAIRateLimiter,
+} from './rate-limiter.js';
+export type { RateLimiterConfig } from './rate-limiter.js';
+
+export {
+    HealthCheckManager,
+    HealthStatus,
+    createLLMHealthCheck,
+    createSessionStoreHealthCheck,
+    createCustomHealthCheck,
+    createHttpHealthCheck,
+} from './health.js';
+export type {
+    HealthCheckConfig,
+    HealthCheckResult,
+    HealthComponent,
+    ComponentHealth,
+} from './health.js';
+
+export {
+    GracefulShutdown,
+    createGracefulShutdown,
+    withShutdownGuard,
+} from './graceful-shutdown.js';
+export type { GracefulShutdownConfig, CleanupHandler, ShutdownEvent } from './graceful-shutdown.js';
+
+// Resumable Streaming (VoltAgent-style)
+export {
+    ResumableStreamManager,
+    formatSSE,
+    createResumableStream,
+} from './resumable-stream.js';
+export type {
+    StreamCheckpoint,
+    ResumableStreamConfig,
+    StreamChunkSSE,
+} from './resumable-stream.js';

package/src/production/latency-eval.ts

@@ -0,0 +1,62 @@
+/**
+ * Latency eval: measure p50/p95/p99 and throughput for agent runs.
+ */
+
+import type { EvalSuite, EvalRunOptions, EvalResult, EvalSample } from './types.js';
+import type { RunnableHighLevelAgent } from '../extensions/index.js';
+
+export interface LatencyEvalConfig {
+    readonly suiteId?: string;
+    readonly name?: string;
+    /** Agent to eval (must have run(prompt)) */
+    readonly agent: RunnableHighLevelAgent;
+    /** Samples: input prompt per run */
+    readonly samples: EvalSample[];
+    /** Concurrency (default 1) */
+    readonly concurrency?: number;
+}
+
+/**
+ * Create a latency eval suite: runs each sample, records latency, returns p50/p95/p99 and throughput.
+ */
+export function createLatencyEval(config: LatencyEvalConfig): EvalSuite {
+    const suiteId = config.suiteId ?? `latency-${Date.now()}`;
+    const name = config.name ?? 'Latency Eval';
+
+    return {
+        id: suiteId,
+        name,
+        async run(options?: EvalRunOptions): Promise<EvalResult> {
+            const samples = (options?.dataset ?? config.samples).slice(0, options?.maxSamples);
+            const times: number[] = [];
+
+            for (const sample of samples) {
+                const input = typeof sample.input === 'string' ? sample.input : (sample.input?.prompt as string) ?? '';
+                const start = Date.now();
+                try {
+                    await config.agent.run(input);
+                } catch {
+                    // still record latency
+                }
+                times.push(Date.now() - start);
+            }
+
+            times.sort((a, b) => a - b);
+            const n = times.length;
+            const sum = times.reduce((a, b) => a + b, 0);
+
+            return {
+                suiteId,
+                latencyMs: n > 0 ? sum / n : 0,
+                latencyP95Ms: n > 0 ? times[Math.min(Math.ceil(n * 0.95) - 1, n - 1)] : undefined,
+                latencyP99Ms: n > 0 ? times[Math.min(Math.ceil(n * 0.99) - 1, n - 1)] : undefined,
+                samplesTotal: n,
+                details: {
+                    p50: n > 0 ? times[Math.floor(n * 0.5)] : undefined,
+                    min: n > 0 ? times[0] : undefined,
+                    max: n > 0 ? times[n - 1] : undefined,
+                },
+            };
+        },
+    };
+}