@telora/daemon-core 0.2.5

package/dist/log-manager.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Log manager -- retention policy and pruning for agent log files.
+ *
+ * Agent logs accumulate with three files per session:
+ *   agent-{branch}-{ISO-timestamp}.{stdout.log|stderr.log|stream.jsonl}
+ *
+ * This module provides configurable retention with three thresholds:
+ * - Max age (default 7 days)
+ * - Max total size (default 1 GB)
+ * - Max file count (default 500)
+ *
+ * Logs referenced by active escalations are preserved regardless of age.
+ * Pruning runs on startup and periodically (hourly).
+ *
+ * Extracted to daemon-core so both daemon and factory engines can share
+ * the same log rotation logic with engine-specific config.
+ */
+/** Configuration for log retention policy. */
+export interface LogRetentionConfig {
+    /** Directory containing log files. */
+    logDir: string;
+    /** Max age in days for log files. */
+    logMaxAgeDays: number;
+    /** Max total bytes for all log files. */
+    logMaxTotalBytes: number;
+    /** Max number of log files. */
+    logMaxFiles: number;
+}
+/** Information about a single log file on disk. */
+export interface LogFileInfo {
+    /** Full path to the file. */
+    path: string;
+    /** File name without directory. */
+    name: string;
+    /** Size in bytes. */
+    size: number;
+    /** Last modification time (ms since epoch). */
+    mtimeMs: number;
+    /** Session group key (shared prefix before the extension). */
+    sessionKey: string;
+}
+/** Result of a pruning operation. */
+export interface PruneResult {
+    /** Number of files deleted. */
+    filesDeleted: number;
+    /** Number of session groups deleted (partially or fully). */
+    sessionsDeleted: number;
+    /** Total bytes reclaimed. */
+    bytesReclaimed: number;
+    /** Number of files preserved due to escalation references. */
+    filesPreserved: number;
+}
+/**
+ * Injectable dependencies for testing.
+ */
+export interface LogManagerDeps {
+    getActiveEscalationSessionIds: () => Promise<Set<string>>;
+}
+/**
+ * Extract the session key from a log filename.
+ *
+ * Log filenames follow the pattern:
+ *   agent-{branch}-{ISO-timestamp}.{stdout.log|stderr.log|stream.jsonl}
+ *
+ * The session key is everything before the log extension.
+ */
+export declare function extractSessionKey(filename: string): string | null;
+/**
+ * Scan the log directory and return information about all log files.
+ */
+export declare function scanLogDirectory(logDir: string): LogFileInfo[];
+/**
+ * Prune old log files according to the retention policy.
+ *
+ * Deletion order: oldest session groups first. All three files in a session
+ * group are deleted together. Sessions referenced by active escalations are
+ * preserved regardless of age.
+ *
+ * Thresholds are checked in order: age, then file count, then total size.
+ * Files that breach any threshold are candidates for deletion.
+ */
+export declare function pruneOldLogs(config: LogRetentionConfig, deps?: LogManagerDeps): Promise<PruneResult>;
+//# sourceMappingURL=log-manager.d.ts.map

package/dist/log-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-manager.d.ts","sourceRoot":"","sources":["../src/log-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CAC3D;AAUD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAkC9D;AAgBD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,GAAE,cAA4B,GACjC,OAAO,CAAC,WAAW,CAAC,CAyHtB"}

package/dist/log-manager.js

@@ -0,0 +1,217 @@
+/**
+ * Log manager -- retention policy and pruning for agent log files.
+ *
+ * Agent logs accumulate with three files per session:
+ *   agent-{branch}-{ISO-timestamp}.{stdout.log|stderr.log|stream.jsonl}
+ *
+ * This module provides configurable retention with three thresholds:
+ * - Max age (default 7 days)
+ * - Max total size (default 1 GB)
+ * - Max file count (default 500)
+ *
+ * Logs referenced by active escalations are preserved regardless of age.
+ * Pruning runs on startup and periodically (hourly).
+ *
+ * Extracted to daemon-core so both daemon and factory engines can share
+ * the same log rotation logic with engine-specific config.
+ */
+import { readdirSync, statSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** Extensions that are recognized as agent log files. */
+const LOG_EXTENSIONS = ['.stdout.log', '.stderr.log', '.stream.jsonl'];
+const defaultDeps = {
+    getActiveEscalationSessionIds: async () => new Set(),
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract the session key from a log filename.
+ *
+ * Log filenames follow the pattern:
+ *   agent-{branch}-{ISO-timestamp}.{stdout.log|stderr.log|stream.jsonl}
+ *
+ * The session key is everything before the log extension.
+ */
+export function extractSessionKey(filename) {
+    for (const ext of LOG_EXTENSIONS) {
+        if (filename.endsWith(ext)) {
+            return filename.slice(0, -ext.length);
+        }
+    }
+    return null;
+}
+/**
+ * Scan the log directory and return information about all log files.
+ */
+export function scanLogDirectory(logDir) {
+    if (!existsSync(logDir))
+        return [];
+    const files = [];
+    let entries;
+    try {
+        entries = readdirSync(logDir);
+    }
+    catch (e) {
+        console.debug(`[log-manager] Failed to read log directory ${logDir}:`, e.message);
+        return [];
+    }
+    for (const name of entries) {
+        const sessionKey = extractSessionKey(name);
+        if (!sessionKey)
+            continue;
+        const path = join(logDir, name);
+        try {
+            const stat = statSync(path);
+            if (!stat.isFile())
+                continue;
+            files.push({
+                path,
+                name,
+                size: stat.size,
+                mtimeMs: stat.mtimeMs,
+                sessionKey,
+            });
+        }
+        catch (e) {
+            console.debug(`[log-manager] Failed to stat log file ${path} (may have been deleted):`, e.message);
+            continue;
+        }
+    }
+    return files;
+}
+/**
+ * Check if a session key matches any session ID referenced by active escalations.
+ */
+function isSessionPreserved(sessionKey, preservedSessionKeys) {
+    return preservedSessionKeys.has(sessionKey);
+}
+// ---------------------------------------------------------------------------
+// Pruning
+// ---------------------------------------------------------------------------
+/**
+ * Prune old log files according to the retention policy.
+ *
+ * Deletion order: oldest session groups first. All three files in a session
+ * group are deleted together. Sessions referenced by active escalations are
+ * preserved regardless of age.
+ *
+ * Thresholds are checked in order: age, then file count, then total size.
+ * Files that breach any threshold are candidates for deletion.
+ */
+export async function pruneOldLogs(config, deps = defaultDeps) {
+    const result = {
+        filesDeleted: 0,
+        sessionsDeleted: 0,
+        bytesReclaimed: 0,
+        filesPreserved: 0,
+    };
+    const { logDir, logMaxAgeDays, logMaxTotalBytes, logMaxFiles } = config;
+    if (!existsSync(logDir))
+        return result;
+    // Scan all log files
+    const allFiles = scanLogDirectory(logDir);
+    if (allFiles.length === 0)
+        return result;
+    // Get preserved session keys from active escalations
+    let preservedSessionKeys;
+    try {
+        preservedSessionKeys = await deps.getActiveEscalationSessionIds();
+    }
+    catch (e) {
+        console.debug('[log-manager] Failed to query escalation session IDs (preserving none):', e.message);
+        preservedSessionKeys = new Set();
+    }
+    // Group files by session key
+    const sessionGroups = new Map();
+    for (const file of allFiles) {
+        const group = sessionGroups.get(file.sessionKey) ?? [];
+        group.push(file);
+        sessionGroups.set(file.sessionKey, group);
+    }
+    // Sort session groups by oldest mtime first (candidates for deletion)
+    const sortedSessions = [...sessionGroups.entries()].sort(([, aFiles], [, bFiles]) => {
+        const aOldest = Math.min(...aFiles.map(f => f.mtimeMs));
+        const bOldest = Math.min(...bFiles.map(f => f.mtimeMs));
+        return aOldest - bOldest;
+    });
+    // Build set of session keys to delete
+    const sessionsToDelete = new Set();
+    const now = Date.now();
+    const maxAgeMs = logMaxAgeDays * 24 * 60 * 60 * 1000;
+    // Pass 1: Mark sessions older than max age
+    for (const [sessionKey, files] of sortedSessions) {
+        if (isSessionPreserved(sessionKey, preservedSessionKeys)) {
+            result.filesPreserved += files.length;
+            continue;
+        }
+        const oldestMtime = Math.min(...files.map(f => f.mtimeMs));
+        if (now - oldestMtime > maxAgeMs) {
+            sessionsToDelete.add(sessionKey);
+        }
+    }
+    // Calculate remaining stats after age-based deletion
+    let remainingFiles = 0;
+    let remainingBytes = 0;
+    for (const [sessionKey, files] of sortedSessions) {
+        if (sessionsToDelete.has(sessionKey))
+            continue;
+        remainingFiles += files.length;
+        remainingBytes += files.reduce((sum, f) => sum + f.size, 0);
+    }
+    // Pass 2: Delete oldest sessions until under file count limit
+    for (const [sessionKey, files] of sortedSessions) {
+        if (sessionsToDelete.has(sessionKey))
+            continue;
+        if (remainingFiles <= logMaxFiles)
+            break;
+        if (isSessionPreserved(sessionKey, preservedSessionKeys))
+            continue;
+        sessionsToDelete.add(sessionKey);
+        remainingFiles -= files.length;
+        remainingBytes -= files.reduce((sum, f) => sum + f.size, 0);
+    }
+    // Pass 3: Delete oldest sessions until under total size limit
+    for (const [sessionKey, files] of sortedSessions) {
+        if (sessionsToDelete.has(sessionKey))
+            continue;
+        if (remainingBytes <= logMaxTotalBytes)
+            break;
+        if (isSessionPreserved(sessionKey, preservedSessionKeys))
+            continue;
+        sessionsToDelete.add(sessionKey);
+        remainingFiles -= files.length;
+        remainingBytes -= files.reduce((sum, f) => sum + f.size, 0);
+    }
+    // Execute deletions
+    for (const sessionKey of sessionsToDelete) {
+        const files = sessionGroups.get(sessionKey);
+        if (!files)
+            continue;
+        for (const file of files) {
+            try {
+                unlinkSync(file.path);
+                result.filesDeleted++;
+                result.bytesReclaimed += file.size;
+            }
+            catch (err) {
+                console.warn(`[log-manager] Failed to delete ${file.path}: ${err.message}`);
+            }
+        }
+        result.sessionsDeleted++;
+    }
+    // Log summary
+    if (result.filesDeleted > 0) {
+        const mbReclaimed = (result.bytesReclaimed / (1024 * 1024)).toFixed(1);
+        console.log(`[log-manager] Pruned ${result.filesDeleted} log files ` +
+            `(${result.sessionsDeleted} sessions), reclaimed ${mbReclaimed} MB`);
+    }
+    if (result.filesPreserved > 0) {
+        console.log(`[log-manager] Preserved ${result.filesPreserved} files referenced by active escalations`);
+    }
+    return result;
+}
+//# sourceMappingURL=log-manager.js.map

package/dist/log-manager.js.map

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

package/dist/otel-env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared OTEL environment variable builder for Telora daemon and factory engines.
+ *
+ * Constructs the environment variables needed to enable OpenTelemetry
+ * telemetry in spawned Claude Code processes. Both the daemon's
+ * buildSpawnEnvironment and the factory's buildBuilderEnv call this
+ * with their respective resource attribute sets.
+ */
+export interface BuildOtelEnvOptions {
+    /** Whether to inject OTEL vars at all. When false, returns empty object. */
+    enabled: boolean;
+    /** OTLP endpoint port (default 4318). */
+    port?: number;
+    /** Metric export interval in ms (default 10000). */
+    exportInterval?: number;
+    /**
+     * Arbitrary key-value pairs for OTEL_RESOURCE_ATTRIBUTES.
+     * Undefined/null values are silently omitted.
+     */
+    resourceAttributes?: Record<string, string | undefined | null>;
+}
+/**
+ * Build OTEL environment variables for a spawned Claude Code process.
+ *
+ * Returns a flat Record of env vars to merge into the spawn environment.
+ * When `enabled` is false, returns an empty object (no-op).
+ */
+export declare function buildOtelEnv(options: BuildOtelEnvOptions): Record<string, string>;
+//# sourceMappingURL=otel-env.d.ts.map

package/dist/otel-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-env.d.ts","sourceRoot":"","sources":["../src/otel-env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;CAChE;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BjF"}

package/dist/otel-env.js

@@ -0,0 +1,44 @@
+/**
+ * Shared OTEL environment variable builder for Telora daemon and factory engines.
+ *
+ * Constructs the environment variables needed to enable OpenTelemetry
+ * telemetry in spawned Claude Code processes. Both the daemon's
+ * buildSpawnEnvironment and the factory's buildBuilderEnv call this
+ * with their respective resource attribute sets.
+ */
+// -- Builder ------------------------------------------------------------------
+/**
+ * Build OTEL environment variables for a spawned Claude Code process.
+ *
+ * Returns a flat Record of env vars to merge into the spawn environment.
+ * When `enabled` is false, returns an empty object (no-op).
+ */
+export function buildOtelEnv(options) {
+    if (!options.enabled)
+        return {};
+    const port = options.port ?? 4318;
+    const exportInterval = options.exportInterval ?? 10000;
+    const env = {
+        CLAUDE_CODE_ENABLE_TELEMETRY: '1',
+        OTEL_EXPORTER_OTLP_ENDPOINT: `http://127.0.0.1:${port}`,
+        OTEL_EXPORTER_OTLP_PROTOCOL: 'http/json',
+        OTEL_METRICS_EXPORTER: 'otlp',
+        OTEL_LOGS_EXPORTER: 'otlp',
+        OTEL_METRIC_EXPORT_INTERVAL: String(exportInterval),
+        OTEL_LOG_TOOL_DETAILS: '1',
+    };
+    // Build OTEL_RESOURCE_ATTRIBUTES from the provided key-value pairs
+    if (options.resourceAttributes) {
+        const parts = [];
+        for (const [key, val] of Object.entries(options.resourceAttributes)) {
+            if (val != null && val !== '') {
+                parts.push(`${key}=${val}`);
+            }
+        }
+        if (parts.length > 0) {
+            env.OTEL_RESOURCE_ATTRIBUTES = parts.join(',');
+        }
+    }
+    return env;
+}
+//# sourceMappingURL=otel-env.js.map

package/dist/otel-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-env.js","sourceRoot":"","sources":["../src/otel-env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IAClC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IAEvD,MAAM,GAAG,GAA2B;QAClC,4BAA4B,EAAE,GAAG;QACjC,2BAA2B,EAAE,oBAAoB,IAAI,EAAE;QACvD,2BAA2B,EAAE,WAAW;QACxC,qBAAqB,EAAE,MAAM;QAC7B,kBAAkB,EAAE,MAAM;QAC1B,2BAA2B,EAAE,MAAM,CAAC,cAAc,CAAC;QACnD,qBAAqB,EAAE,GAAG;KAC3B,CAAC;IAEF,mEAAmE;IACnE,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACpE,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;gBAC9B,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,GAAG,CAAC,wBAAwB,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/resilience.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Resilience utilities for Telora daemon and factory.
+ *
+ * Provides retry with exponential backoff and circuit breaker patterns
+ * to make API calls and other operations robust against transient failures.
+ */
+/**
+ * Custom error class that carries HTTP status information.
+ */
+export declare class ApiError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly isRetryable: boolean;
+    constructor(message: string, statusCode?: number | undefined, isRetryable?: boolean);
+}
+/**
+ * Determine if an error is retryable.
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Classify an HTTP response status code for retry decisions.
+ */
+export declare function classifyHttpStatus(status: number): 'retryable' | 'non-retryable' | 'unknown';
+export interface RetryOptions {
+    /** Maximum number of attempts (including the first). Default: 3 */
+    maxAttempts?: number;
+    /** Base delay in ms for exponential backoff. Default: 1000 */
+    baseDelayMs?: number;
+    /** Label for log messages. Default: 'operation' */
+    label?: string;
+}
+/**
+ * Execute an async function with retry and exponential backoff.
+ *
+ * Only retries on errors classified as retryable. Non-retryable errors
+ * are thrown immediately.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening the circuit. Default: 5 */
+    failureThreshold?: number;
+    /** Base cooldown period in ms before allowing a probe. Default: 60000 */
+    cooldownMs?: number;
+    /** Maximum cooldown period in ms (caps exponential backoff). Default: 300000 (5 min) */
+    maxCooldownMs?: number;
+    /** Number of consecutive successes required to close from half-open. Default: 2 */
+    halfOpenSuccessThreshold?: number;
+    /** Label for log messages. Default: 'circuit' */
+    label?: string;
+}
+/**
+ * Get all registered circuit breaker instances.
+ */
+export declare function getCircuitBreakers(): readonly CircuitBreaker[];
+/**
+ * Force-close all registered circuit breakers. Used by SIGUSR2 handler.
+ */
+export declare function forceCloseAllCircuitBreakers(): void;
+/**
+ * Circuit breaker to prevent hammering a failing endpoint.
+ *
+ * States:
+ * - closed: Normal operation, requests pass through
+ * - open: Requests fail immediately without hitting the network
+ * - half-open: Probe requests are allowed; N consecutive successes required to close
+ *
+ * Features:
+ * - Graduated recovery: half-open requires N consecutive successes (default 2)
+ * - Exponential cooldown backoff on repeated open cycles
+ * - State transition logging with endpoint label and reason
+ * - Force-close for operator override (SIGUSR2)
+ */
+export declare class CircuitBreaker {
+    private state;
+    private consecutiveFailures;
+    private lastFailureTime;
+    private halfOpenSuccesses;
+    private consecutiveOpenCycles;
+    /** Tracks whether we already logged the open-state transition to suppress repeat logs. */
+    private openStateLogged;
+    /** Count of suppressed CircuitOpenError throws since the last state-change log. */
+    private suppressedCallCount;
+    private readonly failureThreshold;
+    private readonly baseCooldownMs;
+    private readonly maxCooldownMs;
+    private readonly halfOpenSuccessThreshold;
+    readonly label: string;
+    constructor(options?: CircuitBreakerOptions);
+    /** Current effective cooldown with exponential backoff. */
+    private getEffectiveCooldownMs;
+    /** Log a state transition. */
+    private logTransition;
+    /**
+     * Execute a function through the circuit breaker.
+     * Throws CircuitOpenError if the circuit is open and cooldown hasn't elapsed.
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /** Transition from open to half-open, logging suppressed call count. */
+    private transitionToHalfOpen;
+    private onSuccess;
+    private onFailure;
+    /** Get current circuit state for diagnostics. */
+    getState(): CircuitState;
+    /** Get the number of consecutive open cycles (for diagnostics). */
+    getConsecutiveOpenCycles(): number;
+    /** Reset the circuit breaker to closed state. */
+    reset(): void;
+    /**
+     * Force-close the circuit breaker. Used for operator override.
+     * Resets all state including backoff counters.
+     */
+    forceClose(): void;
+}
+/**
+ * Error thrown when the circuit breaker is open.
+ */
+export declare class CircuitOpenError extends Error {
+    constructor(message: string);
+}
+/**
+ * Create a setInterval that wraps the callback in try/catch.
+ * Prevents unhandled exceptions from crashing the process.
+ *
+ * @returns The interval handle for clearing with clearInterval()
+ */
+export declare function safeInterval(callback: () => void | Promise<void>, intervalMs: number, label: string): ReturnType<typeof setInterval>;
+//# sourceMappingURL=resilience.d.ts.map

package/dist/resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.d.ts","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,UAAU,CAAC,EAAE,MAAM;aACnB,WAAW,EAAE,OAAO;gBAFpC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,WAAW,GAAE,OAAe;CAK/C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAwBxD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,SAAS,CAK5F;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CA0BZ;AAMD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,cAAc,EAAE,CAE9D;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAKnD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,qBAAqB,CAAK;IAClC,0FAA0F;IAC1F,OAAO,CAAC,eAAe,CAAS;IAChC,mFAAmF;IACnF,OAAO,CAAC,mBAAmB,CAAK;IAEhC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,OAAO,GAAE,qBAA0B;IAS/C,2DAA2D;IAC3D,OAAO,CAAC,sBAAsB;IAK9B,8BAA8B;IAC9B,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA0BlD,wEAAwE;IACxE,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,SAAS;IAsBjB,OAAO,CAAC,SAAS;IA6BjB,iDAAiD;IACjD,QAAQ,IAAI,YAAY;IAIxB,mEAAmE;IACnE,wBAAwB,IAAI,MAAM;IAIlC,iDAAiD;IACjD,KAAK,IAAI,IAAI;IAUb;;;OAGG;IACH,UAAU,IAAI,IAAI;CAKnB;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACpC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,UAAU,CAAC,OAAO,WAAW,CAAC,CAQhC"}