@wrongstack/tools 0.313.0 → 0.313.1

package/dist/chunk-HFXSNKCV.js

@@ -0,0 +1,196 @@
+// src/circuit-breaker.ts
+var DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
+var DEFAULT_SLOW_CALL_THRESHOLD_MS = 18e4;
+var DEFAULT_MAX_SLOW_CALLS = 3;
+var DEFAULT_WINDOW_MS = 6e4;
+var DEFAULT_MAX_CALLS_PER_WINDOW = 30;
+var DEFAULT_COOLDOWN_MS = 3e4;
+var CircuitBreaker = class {
+  maxConsecutiveFailures;
+  slowCallThresholdMs;
+  maxSlowCalls;
+  windowMs;
+  maxCallsPerWindow;
+  cooldownMs;
+  state = "closed";
+  consecutiveFailures = 0;
+  window = [];
+  lastFailureAt = null;
+  lastSlowAt = null;
+  /** Timestamp when the breaker was opened (for cooldown calculation). */
+  openedAt = null;
+  /**
+   * Master enable flag. When false the breaker is bypassed: `beforeCall`
+   * always returns true and `afterCall` records nothing. The class itself
+   * defaults to enabled (so the standalone unit tests exercise tripping); the
+   * ProcessRegistry flips this off until the user opts in via `/settings`.
+   */
+  enabled = true;
+  /**
+   * Fired (best-effort) when the breaker transitions into the `open` state.
+   * The registry uses this to arm its auto kill/reset countdown.
+   */
+  onTrip;
+  /**
+   * Fired (best-effort) when the breaker returns to `closed` after having been
+   * open/half-open. The registry uses this to cancel a pending kill/reset.
+   */
+  onReset;
+  constructor(config = {}) {
+    this.maxConsecutiveFailures = config.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES;
+    this.slowCallThresholdMs = config.slowCallThresholdMs ?? DEFAULT_SLOW_CALL_THRESHOLD_MS;
+    this.maxSlowCalls = config.maxSlowCalls ?? DEFAULT_MAX_SLOW_CALLS;
+    this.windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    this.maxCallsPerWindow = config.maxCallsPerWindow ?? DEFAULT_MAX_CALLS_PER_WINDOW;
+    this.cooldownMs = config.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  }
+  /** Toggle the master enable. Disabling resets to a clean `closed` state. */
+  setEnabled(enabled) {
+    if (this.enabled === enabled) return;
+    this.enabled = enabled;
+    if (!enabled) this._reset();
+  }
+  get isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Returns true if the circuit allows a new call to proceed.
+   * When false, callers should abort the tool call and return a
+   * circuit-breaker error instead of spawning a process.
+   */
+  get canProceed() {
+    if (!this.enabled) return true;
+    this._checkStateTransition();
+    return this.state !== "open";
+  }
+  /**
+   * Snapshot of the current breaker state for observability (`/kill`).
+   */
+  snapshot() {
+    this._checkStateTransition();
+    const now = Date.now();
+    let cooldownRemaining = null;
+    if (this.openedAt !== null && this.state === "open") {
+      const elapsed = now - this.openedAt;
+      cooldownRemaining = Math.max(0, this.cooldownMs - elapsed);
+    }
+    return {
+      state: this.state,
+      consecutiveFailures: this.consecutiveFailures,
+      slowCallsInWindow: this.window.filter((c) => c.slow).length,
+      callsInWindow: this.window.length,
+      windowMs: this.windowMs,
+      cooldownRemainingMs: cooldownRemaining,
+      lastFailureAt: this.lastFailureAt,
+      lastSlowAt: this.lastSlowAt
+    };
+  }
+  /**
+   * Call this BEFORE spawning a bash/exec process.
+   * Returns true if the call is allowed; false if the breaker is open.
+   * When false, callers MUST NOT spawn a process.
+   *
+   * @param bypass - If true, skip the circuit breaker check entirely.
+   *                  Use for background/fire-and-forget processes that should
+   *                  not affect breaker state.
+   */
+  beforeCall(bypass = false) {
+    if (bypass || !this.enabled) return true;
+    this._checkStateTransition();
+    if (this.state === "open") return false;
+    return true;
+  }
+  /**
+   * Call this AFTER a bash/exec process finishes (success or failure).
+   * `durationMs` is the wall-clock time the process ran.
+   * `failed` is true when the process returned a non-zero exit code or
+   * threw an exception before spawning.
+   *
+   * @param bypass - If true, do not update breaker state.
+   *                  Use for background/fire-and-forget processes.
+   */
+  afterCall(durationMs, failed, bypass = false) {
+    if (bypass || !this.enabled) return;
+    const now = Date.now();
+    if (this.state === "half-open") {
+      if (failed) {
+        this._trip();
+        return;
+      }
+      this._reset();
+      return;
+    }
+    this._pruneWindow(now);
+    const slow = durationMs >= this.slowCallThresholdMs;
+    this.window.push({ at: now, failed, slow });
+    if (failed) {
+      this.consecutiveFailures++;
+      this.lastFailureAt = now;
+      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+        this._trip();
+      }
+      return;
+    }
+    this.consecutiveFailures = 0;
+    if (slow) {
+      this.lastSlowAt = now;
+      const slowCount = this.window.filter((c) => c.slow).length;
+      if (slowCount >= this.maxSlowCalls) {
+        this._trip();
+      }
+    }
+    const callCount = this.window.length;
+    if (callCount >= this.maxCallsPerWindow) {
+      this._trip();
+    }
+  }
+  /** Force the breaker open. Used by /kill force and Ctrl+C. */
+  forceOpen() {
+    this._trip();
+  }
+  /** Force a reset to closed. Used by tests and /kill reset. */
+  forceReset() {
+    this._reset();
+  }
+  _trip() {
+    if (this.state === "open") return;
+    this.state = "open";
+    this.openedAt = Date.now();
+    this.window = [];
+    try {
+      this.onTrip?.();
+    } catch {
+    }
+  }
+  _reset() {
+    const wasRecovering = this.state !== "closed";
+    this.state = "closed";
+    this.consecutiveFailures = 0;
+    this.window = [];
+    this.openedAt = null;
+    if (wasRecovering) {
+      try {
+        this.onReset?.();
+      } catch {
+      }
+    }
+  }
+  /** Transition from open → half-open when cooldown elapses. */
+  _checkStateTransition() {
+    if (this.state !== "open" || this.openedAt === null) return;
+    const elapsed = Date.now() - this.openedAt;
+    if (elapsed >= this.cooldownMs) {
+      this.state = "half-open";
+      this.openedAt = null;
+    }
+  }
+  _pruneWindow(now) {
+    const cutoff = now - this.windowMs;
+    this.window = this.window.filter((c) => c.at >= cutoff);
+  }
+};
+
+export {
+  CircuitBreaker
+};
+//# sourceMappingURL=chunk-HFXSNKCV.js.map