@runcore-sh/runcore 0.1.2

package/dist/health/checks/openrouter.js

@@ -0,0 +1,75 @@
+/**
+ * OpenRouter credit monitoring health check.
+ *
+ * Polls GET https://openrouter.ai/api/v1/key to report credit usage
+ * as a percentage. Maps to the "higher is worse" threshold model used
+ * by AlertManager.
+ */
+/**
+ * Returns a health check function that polls the OpenRouter key endpoint.
+ *
+ * Detail format:
+ *   "credits 85% used, $2.30 remaining of $15.00 limit"
+ *   "credits unlimited (no limit set), $4.20 used"
+ *
+ * Status mapping:
+ *   limit === null     → healthy (unlimited)
+ *   percentUsed < 80   → healthy
+ *   percentUsed >= 80  → degraded
+ *   percentUsed >= 95  → unhealthy
+ *   API error / 401    → unhealthy
+ */
+export function openrouterCreditsCheck() {
+    return async () => {
+        const apiKey = process.env.OPENROUTER_API_KEY;
+        if (!apiKey) {
+            return {
+                status: "unhealthy",
+                detail: "credits unknown — OPENROUTER_API_KEY not set",
+            };
+        }
+        try {
+            const res = await fetch("https://openrouter.ai/api/v1/key", {
+                headers: { Authorization: `Bearer ${apiKey}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok) {
+                return {
+                    status: "unhealthy",
+                    detail: `cannot verify credits — API returned ${res.status}`,
+                };
+            }
+            const json = (await res.json());
+            const data = json.data;
+            if (data.limit === null || data.limit === undefined) {
+                return {
+                    status: "healthy",
+                    detail: `credits unlimited (no limit set), $${data.usage.toFixed(2)} used`,
+                };
+            }
+            const remaining = data.limit_remaining ?? data.limit - data.usage;
+            const percentUsed = Math.round((data.usage / data.limit) * 100);
+            const detail = `credits ${percentUsed}% used, $${remaining.toFixed(2)} remaining of $${data.limit.toFixed(2)} limit`;
+            if (percentUsed >= 95)
+                return { status: "unhealthy", detail };
+            if (percentUsed >= 80)
+                return { status: "degraded", detail };
+            return { status: "healthy", detail };
+        }
+        catch (err) {
+            return {
+                status: "unhealthy",
+                detail: `cannot verify credits — ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    };
+}
+/**
+ * Metric extractor for the credits check detail string.
+ * Parses "credits 85% used, ..." → { percentUsed: 85 }
+ */
+export function creditsExtractor(detail) {
+    const match = detail.match(/credits\s+(\d+)%\s+used/);
+    return match ? { percentUsed: parseInt(match[1], 10) } : {};
+}
+//# sourceMappingURL=openrouter.js.map

package/dist/health/checks/openrouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.js","sourceRoot":"","sources":["../../../src/health/checks/openrouter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,IAA0B,EAAE;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAC9C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,8CAA8C;aACvD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,kCAAkC,EAAE;gBAC1D,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;gBAC9C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;aACpC,CAAC,CAAC;YAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,OAAO;oBACL,MAAM,EAAE,WAAW;oBACnB,MAAM,EAAE,wCAAwC,GAAG,CAAC,MAAM,EAAE;iBAC7D,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAC;YACzD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YAEvB,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACpD,OAAO;oBACL,MAAM,EAAE,SAAS;oBACjB,MAAM,EAAE,sCAAsC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;iBAC3E,CAAC;YACJ,CAAC;YAED,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;YAClE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;YAChE,MAAM,MAAM,GAAG,WAAW,WAAW,YAAY,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;YAErH,IAAI,WAAW,IAAI,EAAE;gBAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;YAC9D,IAAI,WAAW,IAAI,EAAE;gBAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;YAC7D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,2BAA2B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;aACtF,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACtD,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC"}

package/dist/health/checks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Built-in health checks — process-level diagnostics.
+ *
+ * These are the foundational checks that every Core instance registers.
+ * Moved from the original src/health.ts with identical signatures.
+ */
+import type { HealthCheckFn } from "./types.js";
+/** Process memory check. Unhealthy above hardMax, degraded above softMax. */
+export declare function memoryCheck(softMaxMB?: number, hardMaxMB?: number): HealthCheckFn;
+/** Event loop responsiveness check. Measures setTimeout drift. */
+export declare function eventLoopCheck(maxDriftMs?: number): HealthCheckFn;
+/**
+ * Wrap an availability function (like isSidecarAvailable) into a health check.
+ * Returns degraded (not unhealthy) because sidecars are optional.
+ */
+export declare function availabilityCheck(isAvailable: () => boolean, label: string): HealthCheckFn;
+/** CPU usage check. Reports user + system CPU time as a percentage over a sample window. */
+export declare function cpuCheck(warnPct?: number, criticalPct?: number, sampleMs?: number): HealthCheckFn;
+/** Disk usage check. Reports free space in the brain directory's volume. */
+export declare function diskUsageCheck(brainDir: string, warnPct?: number, criticalPct?: number): HealthCheckFn;
+/**
+ * Disk I/O check — verifies the brain directory is readable and writable.
+ * Uses a temp file write+read+delete cycle.
+ */
+export declare function diskCheck(brainDir: string): HealthCheckFn;
+//# sourceMappingURL=checks.d.ts.map

package/dist/health/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../src/health/checks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAE7D,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,SAAS,SAAM,EAAE,SAAS,SAAO,GAAG,aAAa,CAU5E;AAED,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,UAAU,SAAM,GAAG,aAAa,CAa9D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,OAAO,EAC1B,KAAK,EAAE,MAAM,GACZ,aAAa,CAKf;AAED,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,OAAO,SAAK,EAAE,WAAW,SAAK,EAAE,QAAQ,SAAO,GAAG,aAAa,CAgBvF;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAK,EAAE,WAAW,SAAK,GAAG,aAAa,CAoB9F;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAqBzD"}

package/dist/health/checks.js

@@ -0,0 +1,122 @@
+/**
+ * Built-in health checks — process-level diagnostics.
+ *
+ * These are the foundational checks that every Core instance registers.
+ * Moved from the original src/health.ts with identical signatures.
+ */
+/** Process memory check. Unhealthy above hardMax, degraded above softMax. */
+export function memoryCheck(softMaxMB = 512, hardMaxMB = 1024) {
+    return () => {
+        const mem = process.memoryUsage();
+        const heapMB = Math.round(mem.heapUsed / 1024 / 1024);
+        const rssMB = Math.round(mem.rss / 1024 / 1024);
+        const detail = `heap ${heapMB}MB, rss ${rssMB}MB`;
+        if (rssMB > hardMaxMB)
+            return { status: "unhealthy", detail };
+        if (rssMB > softMaxMB)
+            return { status: "degraded", detail };
+        return { status: "healthy", detail };
+    };
+}
+/** Event loop responsiveness check. Measures setTimeout drift. */
+export function eventLoopCheck(maxDriftMs = 500) {
+    return () => {
+        return new Promise((resolve) => {
+            const start = performance.now();
+            setTimeout(() => {
+                const drift = performance.now() - start;
+                const detail = `drift ${Math.round(drift)}ms`;
+                if (drift > maxDriftMs)
+                    resolve({ status: "unhealthy", detail });
+                else if (drift > maxDriftMs / 2)
+                    resolve({ status: "degraded", detail });
+                else
+                    resolve({ status: "healthy", detail });
+            }, 0);
+        });
+    };
+}
+/**
+ * Wrap an availability function (like isSidecarAvailable) into a health check.
+ * Returns degraded (not unhealthy) because sidecars are optional.
+ */
+export function availabilityCheck(isAvailable, label) {
+    return () => ({
+        status: isAvailable() ? "healthy" : "degraded",
+        detail: isAvailable() ? `${label} available` : `${label} unavailable`,
+    });
+}
+/** CPU usage check. Reports user + system CPU time as a percentage over a sample window. */
+export function cpuCheck(warnPct = 80, criticalPct = 95, sampleMs = 1000) {
+    return () => new Promise((resolve) => {
+        const start = process.cpuUsage();
+        const startTime = performance.now();
+        setTimeout(() => {
+            const elapsed = (performance.now() - startTime) * 1000; // microseconds
+            const usage = process.cpuUsage(start);
+            const totalCpu = usage.user + usage.system;
+            const pct = Math.round((totalCpu / elapsed) * 100);
+            const detail = `cpu ${pct}%, user ${Math.round(usage.user / 1000)}ms, system ${Math.round(usage.system / 1000)}ms`;
+            if (pct >= criticalPct)
+                resolve({ status: "unhealthy", detail });
+            else if (pct >= warnPct)
+                resolve({ status: "degraded", detail });
+            else
+                resolve({ status: "healthy", detail });
+        }, sampleMs);
+    });
+}
+/** Disk usage check. Reports free space in the brain directory's volume. */
+export function diskUsageCheck(brainDir, warnPct = 85, criticalPct = 95) {
+    return async () => {
+        try {
+            const { statfs } = await import("node:fs/promises");
+            const stats = await statfs(brainDir);
+            const totalBytes = stats.blocks * stats.bsize;
+            const freeBytes = stats.bavail * stats.bsize;
+            const usedPct = Math.round(((totalBytes - freeBytes) / totalBytes) * 100);
+            const freeMB = Math.round(freeBytes / 1024 / 1024);
+            const detail = `disk ${usedPct}% used, ${freeMB}MB free`;
+            if (usedPct >= criticalPct)
+                return { status: "unhealthy", detail };
+            if (usedPct >= warnPct)
+                return { status: "degraded", detail };
+            return { status: "healthy", detail };
+        }
+        catch (err) {
+            return {
+                status: "degraded",
+                detail: `disk usage unavailable: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    };
+}
+/**
+ * Disk I/O check — verifies the brain directory is readable and writable.
+ * Uses a temp file write+read+delete cycle.
+ */
+export function diskCheck(brainDir) {
+    return async () => {
+        const { writeFile, readFile, unlink } = await import("node:fs/promises");
+        const { join } = await import("node:path");
+        const token = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+        const probe = join(brainDir, `.health-probe-${token}`);
+        try {
+            await writeFile(probe, token, "utf-8");
+            const read = await readFile(probe, "utf-8");
+            await unlink(probe).catch((e) => { if (e.code !== "ENOENT")
+                throw e; });
+            if (read !== token) {
+                return { status: "unhealthy", detail: "disk read-back mismatch" };
+            }
+            return { status: "healthy", detail: `brain dir writable` };
+        }
+        catch (err) {
+            return {
+                status: "unhealthy",
+                detail: `disk I/O failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    };
+}
+//# sourceMappingURL=checks.js.map

package/dist/health/checks.js.map

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

package/dist/health/components.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Component health checks — subsystem-level diagnostics.
+ *
+ * Each check probes a specific Core component and returns its health status.
+ * These are registered at startup after their respective systems initialize.
+ */
+import type { HealthCheckFn } from "./types.js";
+import type { HealthSummary } from "../agents/instance-manager.js";
+import type { ResourceSnapshot } from "../agents/runtime/types.js";
+/**
+ * Queue store health — verifies the JSONL store is accessible and has valid state.
+ * Accepts a lazy getter so it doesn't import the store directly.
+ */
+export declare function queueStoreCheck(getStore: () => {
+    count: () => Promise<number>;
+} | null): HealthCheckFn;
+/**
+ * Agent runtime capacity — checks resource utilization against thresholds.
+ * Degraded at 80% utilization, unhealthy at 95%.
+ */
+export declare function agentCapacityCheck(getSnapshot: () => ResourceSnapshot | null): HealthCheckFn;
+/**
+ * Agent instance health — checks aggregate health scores from instance manager.
+ */
+export declare function agentHealthCheck(getHealthSummary: () => HealthSummary | null): HealthCheckFn;
+/**
+ * Board provider health — checks if the provider is registered and available.
+ */
+export declare function boardCheck(getProvider: () => {
+    name: string;
+    isAvailable: () => boolean;
+} | null): HealthCheckFn;
+/**
+ * HTTP endpoint check — pings a URL and expects a 2xx response.
+ * Useful for checking upstream APIs or sidecar HTTP endpoints.
+ */
+export declare function httpCheck(url: string, label: string, timeoutMs?: number): HealthCheckFn;
+//# sourceMappingURL=components.d.ts.map

package/dist/health/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/health/components.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAInE;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,GACtD,aAAa,CAgBf;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,gBAAgB,GAAG,IAAI,GACzC,aAAa,CAef;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,aAAa,GAAG,IAAI,GAC3C,aAAa,CAgBf;AAID;;GAEG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,MAAM;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,OAAO,CAAA;CAAE,GAAG,IAAI,GACrE,aAAa,CASf;AAID;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,aAAa,CAmBrF"}

package/dist/health/components.js

@@ -0,0 +1,112 @@
+/**
+ * Component health checks — subsystem-level diagnostics.
+ *
+ * Each check probes a specific Core component and returns its health status.
+ * These are registered at startup after their respective systems initialize.
+ */
+// ─── Queue store ─────────────────────────────────────────────────────────────
+/**
+ * Queue store health — verifies the JSONL store is accessible and has valid state.
+ * Accepts a lazy getter so it doesn't import the store directly.
+ */
+export function queueStoreCheck(getStore) {
+    return async () => {
+        const store = getStore();
+        if (!store) {
+            return { status: "degraded", detail: "queue store not initialized" };
+        }
+        try {
+            const count = await store.count();
+            return { status: "healthy", detail: `${count} tasks` };
+        }
+        catch (err) {
+            return {
+                status: "unhealthy",
+                detail: `queue read failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    };
+}
+// ─── Agent runtime ───────────────────────────────────────────────────────────
+/**
+ * Agent runtime capacity — checks resource utilization against thresholds.
+ * Degraded at 80% utilization, unhealthy at 95%.
+ */
+export function agentCapacityCheck(getSnapshot) {
+    return () => {
+        const snap = getSnapshot();
+        if (!snap)
+            return { status: "degraded", detail: "runtime not initialized" };
+        const agentUtil = snap.maxAgents > 0 ? snap.activeAgents / snap.maxAgents : 0;
+        const memUtil = snap.maxMemoryMB > 0 ? snap.totalMemoryMB / snap.maxMemoryMB : 0;
+        const maxUtil = Math.max(agentUtil, memUtil);
+        const detail = `${snap.activeAgents}/${snap.maxAgents} agents, ${snap.totalMemoryMB}/${snap.maxMemoryMB}MB, ${snap.queuedRequests} queued`;
+        if (maxUtil >= 0.95)
+            return { status: "unhealthy", detail: `at capacity — ${detail}` };
+        if (maxUtil >= 0.80)
+            return { status: "degraded", detail: `high utilization — ${detail}` };
+        return { status: "healthy", detail };
+    };
+}
+/**
+ * Agent instance health — checks aggregate health scores from instance manager.
+ */
+export function agentHealthCheck(getHealthSummary) {
+    return () => {
+        const summary = getHealthSummary();
+        if (!summary)
+            return { status: "degraded", detail: "instance manager not initialized" };
+        const { totalInstances, activeInstances, unhealthyInstances, averageScore } = summary;
+        const detail = `${activeInstances} active, ${unhealthyInstances} unhealthy, avg score ${averageScore}`;
+        if (activeInstances > 0 && unhealthyInstances >= activeInstances) {
+            return { status: "unhealthy", detail: `all agents unhealthy — ${detail}` };
+        }
+        if (unhealthyInstances > 0 || averageScore < 50) {
+            return { status: "degraded", detail };
+        }
+        return { status: "healthy", detail };
+    };
+}
+// ─── Board provider ──────────────────────────────────────────────────────────
+/**
+ * Board provider health — checks if the provider is registered and available.
+ */
+export function boardCheck(getProvider) {
+    return () => {
+        const provider = getProvider();
+        if (!provider)
+            return { status: "degraded", detail: "no board provider registered" };
+        if (!provider.isAvailable()) {
+            return { status: "degraded", detail: `${provider.name} unavailable` };
+        }
+        return { status: "healthy", detail: `${provider.name} available` };
+    };
+}
+// ─── External service connectivity ───────────────────────────────────────────
+/**
+ * HTTP endpoint check — pings a URL and expects a 2xx response.
+ * Useful for checking upstream APIs or sidecar HTTP endpoints.
+ */
+export function httpCheck(url, label, timeoutMs = 3000) {
+    return async () => {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const res = await fetch(url, {
+                method: "HEAD",
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (res.ok)
+                return { status: "healthy", detail: `${label} reachable (${res.status})` };
+            return { status: "degraded", detail: `${label} returned ${res.status}` };
+        }
+        catch (err) {
+            return {
+                status: "degraded",
+                detail: `${label} unreachable: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    };
+}
+//# sourceMappingURL=components.js.map

package/dist/health/components.js.map

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

package/dist/health/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Health check system for Core.
+ *
+ * Provides K8s-compatible /healthz (liveness) and /readyz (readiness) probes,
+ * component health checks, dependency validation, and auto-recovery.
+ *
+ * Re-exports everything so `import { HealthChecker, memoryCheck } from "./health/index.js"`
+ * is a drop-in replacement for the old `import { ... } from "./health.js"`.
+ */
+export type { HealthStatus, CheckResult, HealthCheckResult, HealthCheckFn, CheckRegistration, RegisterOptions, DependencyDescriptor, RecoveryAction, RecoveryState, } from "./types.js";
+export { HealthChecker } from "./checker.js";
+export { memoryCheck, eventLoopCheck, availabilityCheck, cpuCheck, diskUsageCheck, diskCheck, } from "./checks.js";
+export { queueStoreCheck, agentCapacityCheck, agentHealthCheck, boardCheck, httpCheck, } from "./components.js";
+export { openrouterCreditsCheck, creditsExtractor } from "./checks/openrouter.js";
+export { RecoveryManager, sidecarRecovery } from "./recovery.js";
+export { AlertManager } from "./alerting.js";
+export { defaultThresholds, defaultAlertConfig } from "./alert-defaults.js";
+export type { Alert, AlertConfig, AlertSeverity, AlertState, AlertSummary, AlertThreshold, ChannelPreference, MetricExtractor, NotificationChannel, } from "./alert-types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/health/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/health/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,EACL,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,SAAS,GACV,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGlF,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,YAAY,EACV,KAAK,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/dist/health/index.js

@@ -0,0 +1,23 @@
+/**
+ * Health check system for Core.
+ *
+ * Provides K8s-compatible /healthz (liveness) and /readyz (readiness) probes,
+ * component health checks, dependency validation, and auto-recovery.
+ *
+ * Re-exports everything so `import { HealthChecker, memoryCheck } from "./health/index.js"`
+ * is a drop-in replacement for the old `import { ... } from "./health.js"`.
+ */
+// Core checker
+export { HealthChecker } from "./checker.js";
+// Built-in checks
+export { memoryCheck, eventLoopCheck, availabilityCheck, cpuCheck, diskUsageCheck, diskCheck, } from "./checks.js";
+// Component checks
+export { queueStoreCheck, agentCapacityCheck, agentHealthCheck, boardCheck, httpCheck, } from "./components.js";
+// OpenRouter credit check
+export { openrouterCreditsCheck, creditsExtractor } from "./checks/openrouter.js";
+// Recovery
+export { RecoveryManager, sidecarRecovery } from "./recovery.js";
+// Alerting
+export { AlertManager } from "./alerting.js";
+export { defaultThresholds, defaultAlertConfig } from "./alert-defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/health/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/health/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,eAAe;AACf,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,kBAAkB;AAClB,OAAO,EACL,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,0BAA0B;AAC1B,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAElF,WAAW;AACX,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEjE,WAAW;AACX,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/health/recovery.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Auto-recovery system — self-healing mechanisms for common failure modes.
+ *
+ * Watches health check results and triggers recovery actions when checks
+ * fail beyond a configurable threshold. Includes cooldowns to prevent
+ * recovery storms.
+ *
+ * Recovery actions are registered alongside health checks and execute
+ * automatically when conditions are met.
+ */
+import type { RecoveryAction, RecoveryState } from "./types.js";
+import type { HealthChecker } from "./checker.js";
+export declare class RecoveryManager {
+    private actions;
+    private state;
+    private checker;
+    private timer;
+    private intervalMs;
+    constructor(checker: HealthChecker, intervalMs?: number);
+    /** Register a recovery action for a specific health check. */
+    register(action: RecoveryAction): void;
+    /** Start the background recovery loop. */
+    start(): void;
+    /** Stop the background recovery loop. */
+    stop(): void;
+    /** Run one evaluation cycle: check health, trigger recoveries if needed. */
+    evaluate(): Promise<string[]>;
+    /** Get diagnostic state for all recovery actions. */
+    getState(): Record<string, RecoveryState & {
+        actionName: string;
+        checkName: string;
+    }>;
+}
+/**
+ * Create a sidecar restart recovery action.
+ * Stops then starts the sidecar process when its health check fails.
+ */
+export declare function sidecarRecovery(name: string, checkName: string, stop: () => void, start: () => Promise<boolean>, opts?: {
+    threshold?: number;
+    cooldownMs?: number;
+}): RecoveryAction;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/health/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/health/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAqB,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAKlD,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,aAAa,EAAE,UAAU,SAAS;IAKvD,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAYtC,0CAA0C;IAC1C,KAAK,IAAI,IAAI;IAMb,yCAAyC;IACzC,IAAI,IAAI,IAAI;IAQZ,4EAA4E;IACtE,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA6DnC,qDAAqD;IACrD,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAUtF;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,IAAI,EAChB,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,cAAc,CAahB"}

package/dist/health/recovery.js

@@ -0,0 +1,138 @@
+/**
+ * Auto-recovery system — self-healing mechanisms for common failure modes.
+ *
+ * Watches health check results and triggers recovery actions when checks
+ * fail beyond a configurable threshold. Includes cooldowns to prevent
+ * recovery storms.
+ *
+ * Recovery actions are registered alongside health checks and execute
+ * automatically when conditions are met.
+ */
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("health.recovery");
+export class RecoveryManager {
+    actions = [];
+    state = new Map();
+    checker;
+    timer = null;
+    intervalMs;
+    constructor(checker, intervalMs = 30_000) {
+        this.checker = checker;
+        this.intervalMs = intervalMs;
+    }
+    /** Register a recovery action for a specific health check. */
+    register(action) {
+        log.debug("registering recovery action", { name: action.name, checkName: action.checkName, threshold: action.threshold, cooldownMs: action.cooldownMs });
+        this.actions.push(action);
+        this.state.set(action.name, {
+            consecutiveFailures: 0,
+            lastAttempt: null,
+            lastSuccess: null,
+            totalAttempts: 0,
+            totalSuccesses: 0,
+        });
+    }
+    /** Start the background recovery loop. */
+    start() {
+        if (this.timer)
+            return;
+        log.info("recovery loop started", { intervalMs: this.intervalMs });
+        this.timer = setInterval(() => this.evaluate(), this.intervalMs);
+    }
+    /** Stop the background recovery loop. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            log.info("recovery loop stopped");
+        }
+    }
+    /** Run one evaluation cycle: check health, trigger recoveries if needed. */
+    async evaluate() {
+        const triggered = [];
+        let result;
+        try {
+            result = await this.checker.check();
+        }
+        catch (err) {
+            log.error("recovery evaluation failed — health check threw", { error: String(err) });
+            return triggered;
+        }
+        for (const action of this.actions) {
+            const checkResult = result.checks[action.checkName];
+            const st = this.state.get(action.name);
+            if (!checkResult || checkResult.status === "healthy") {
+                // Reset failure counter on healthy
+                st.consecutiveFailures = 0;
+                continue;
+            }
+            st.consecutiveFailures++;
+            if (st.consecutiveFailures < action.threshold)
+                continue;
+            // Check cooldown
+            if (st.lastAttempt) {
+                const elapsed = Date.now() - new Date(st.lastAttempt).getTime();
+                if (elapsed < action.cooldownMs)
+                    continue;
+            }
+            // Trigger recovery
+            log.info("triggering recovery action", {
+                action: action.name,
+                checkName: action.checkName,
+                consecutiveFailures: st.consecutiveFailures,
+                totalAttempts: st.totalAttempts,
+            });
+            st.lastAttempt = new Date().toISOString();
+            st.totalAttempts++;
+            try {
+                const success = await action.execute();
+                if (success) {
+                    st.consecutiveFailures = 0;
+                    st.lastSuccess = new Date().toISOString();
+                    st.totalSuccesses++;
+                    log.info("recovery action succeeded", { action: action.name, checkName: action.checkName });
+                }
+                else {
+                    log.warn("recovery action returned false", { action: action.name, checkName: action.checkName });
+                }
+                triggered.push(action.name);
+            }
+            catch (err) {
+                // Recovery itself failed — will retry on next cycle after cooldown
+                log.error("recovery action threw an error", { action: action.name, checkName: action.checkName, error: String(err) });
+            }
+        }
+        return triggered;
+    }
+    /** Get diagnostic state for all recovery actions. */
+    getState() {
+        const out = {};
+        for (const action of this.actions) {
+            const st = this.state.get(action.name);
+            if (st) {
+                out[action.name] = { ...st, actionName: action.name, checkName: action.checkName };
+            }
+        }
+        return out;
+    }
+}
+// ─── Pre-built recovery actions ──────────────────────────────────────────────
+/**
+ * Create a sidecar restart recovery action.
+ * Stops then starts the sidecar process when its health check fails.
+ */
+export function sidecarRecovery(name, checkName, stop, start, opts) {
+    return {
+        name: `recover_${name}`,
+        checkName,
+        threshold: opts?.threshold ?? 3,
+        cooldownMs: opts?.cooldownMs ?? 60_000,
+        execute: async () => {
+            stop();
+            // Brief pause before restarting
+            await new Promise((r) => setTimeout(r, 1000));
+            return start();
+        },
+    };
+}
+//# sourceMappingURL=recovery.js.map