risicare 0.2.2 → 0.4.0

package/dist/index.js

@@ -1,3 +1,1419 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/globals.ts
+import { AsyncLocalStorage } from "async_hooks";
+function getClient() {
+  return G[PREFIX + "client"];
+}
+function setClient(client) {
+  G[PREFIX + "client"] = client;
+}
+function getTracer() {
+  return G[PREFIX + "tracer"];
+}
+function setTracer(tracer) {
+  G[PREFIX + "tracer"] = tracer;
+}
+function getContextStorage() {
+  if (!G[PREFIX + "ctx"]) {
+    G[PREFIX + "ctx"] = new AsyncLocalStorage();
+  }
+  return G[PREFIX + "ctx"];
+}
+function getRegistry() {
+  if (!G[PREFIX + "registry"]) {
+    G[PREFIX + "registry"] = /* @__PURE__ */ new Map();
+  }
+  return G[PREFIX + "registry"];
+}
+function getOpCount() {
+  return G[PREFIX + "opcount"] ?? 0;
+}
+function setOpCount(n) {
+  G[PREFIX + "opcount"] = n;
+}
+function getDebug() {
+  return G[PREFIX + "debug"] ?? false;
+}
+function setDebugFlag(enabled) {
+  G[PREFIX + "debug"] = enabled;
+}
+var G, PREFIX;
+var init_globals = __esm({
+  "src/globals.ts"() {
+    "use strict";
+    G = globalThis;
+    PREFIX = "__risicare_";
+  }
+});
+
+// src/utils/log.ts
+function setDebug(enabled) {
+  setDebugFlag(enabled);
+}
+function debug(msg) {
+  if (getDebug()) {
+    process.stderr.write(`[risicare] ${msg}
+`);
+  }
+}
+function warn(msg) {
+  process.stderr.write(`[risicare] WARNING: ${msg}
+`);
+}
+var init_log = __esm({
+  "src/utils/log.ts"() {
+    "use strict";
+    init_globals();
+  }
+});
+
+// src/runtime/config.ts
+function resolveFixRuntimeConfig(config) {
+  return {
+    apiEndpoint: config.apiEndpoint,
+    apiKey: config.apiKey,
+    enabled: config.enabled ?? true,
+    cacheEnabled: config.cacheEnabled ?? true,
+    cacheTtlMs: config.cacheTtlMs ?? 3e5,
+    cacheMaxEntries: config.cacheMaxEntries ?? 1e3,
+    autoRefresh: config.autoRefresh ?? true,
+    refreshIntervalMs: config.refreshIntervalMs ?? 6e4,
+    dryRun: config.dryRun ?? false,
+    abTestingEnabled: config.abTestingEnabled ?? true,
+    timeoutMs: config.timeoutMs ?? 1e3,
+    debug: config.debug ?? false
+  };
+}
+function matchesError(fix, errorCode) {
+  if (fix.errorCode === errorCode) {
+    return true;
+  }
+  if (fix.errorCode.endsWith("*")) {
+    const prefix = fix.errorCode.slice(0, -1);
+    return errorCode.startsWith(prefix);
+  }
+  return false;
+}
+function shouldApply(fix, sessionHash) {
+  if (fix.trafficPercentage >= 100) return true;
+  if (fix.trafficPercentage <= 0) return false;
+  const bucket = sessionHash % 100;
+  return bucket < fix.trafficPercentage;
+}
+function activeFixFromApiResponse(item) {
+  return {
+    fixId: item.id ?? item.fix_id ?? item.fixId ?? "",
+    deploymentId: item.deployment_id ?? item.deploymentId ?? "",
+    errorCode: item.error_code ?? item.errorCode ?? "",
+    fixType: item.fix_type ?? item.fixType ?? "prompt",
+    config: item.config ?? {},
+    trafficPercentage: item.traffic_percentage ?? item.trafficPercentage ?? 100,
+    version: item.version ?? 1
+  };
+}
+var init_config = __esm({
+  "src/runtime/config.ts"() {
+    "use strict";
+  }
+});
+
+// src/runtime/cache.ts
+var FixCache;
+var init_cache = __esm({
+  "src/runtime/cache.ts"() {
+    "use strict";
+    init_config();
+    init_log();
+    FixCache = class {
+      _ttlMs;
+      _maxEntries;
+      _enabled;
+      _cache;
+      _stats;
+      constructor(config) {
+        this._enabled = config?.cacheEnabled ?? true;
+        this._ttlMs = config?.cacheTtlMs ?? 3e5;
+        this._maxEntries = config?.cacheMaxEntries ?? 1e3;
+        this._cache = /* @__PURE__ */ new Map();
+        this._stats = {
+          hits: 0,
+          misses: 0,
+          evictions: 0,
+          size: 0,
+          lastRefresh: null
+        };
+      }
+      /** Whether caching is enabled. */
+      get enabled() {
+        return this._enabled;
+      }
+      /**
+       * Get a fix by error code.
+       *
+       * Checks exact match first, then scans for wildcard matches.
+       * Expired entries are evicted on access.
+       */
+      get(errorCode) {
+        try {
+          if (!this._enabled) return null;
+          const now = Date.now();
+          const exactEntry = this._cache.get(errorCode);
+          if (exactEntry) {
+            if (exactEntry.expiresAt > now) {
+              this._stats.hits++;
+              return exactEntry.fix;
+            }
+            this._cache.delete(errorCode);
+            this._stats.evictions++;
+          }
+          for (const [key, entry] of this._cache) {
+            if (entry.expiresAt <= now) {
+              this._cache.delete(key);
+              this._stats.evictions++;
+              continue;
+            }
+            if (matchesError(entry.fix, errorCode)) {
+              this._stats.hits++;
+              return entry.fix;
+            }
+          }
+          this._stats.misses++;
+          return null;
+        } catch (e) {
+          debug(`FixCache.get error: ${e}`);
+          return null;
+        }
+      }
+      /**
+       * Add a single fix to the cache.
+       *
+       * Evicts the oldest entry if at capacity.
+       */
+      set(fix) {
+        try {
+          if (!this._enabled) return;
+          if (this._cache.size >= this._maxEntries) {
+            this._evictOldest();
+          }
+          const now = Date.now();
+          this._cache.set(fix.errorCode, {
+            fix,
+            createdAt: now,
+            expiresAt: now + this._ttlMs
+          });
+          this._stats.size = this._cache.size;
+        } catch (e) {
+          debug(`FixCache.set error: ${e}`);
+        }
+      }
+      /**
+       * Replace all cached fixes (bulk refresh).
+       *
+       * Clears the cache and populates with the given fixes.
+       */
+      setAll(fixes) {
+        try {
+          if (!this._enabled) return;
+          this._cache.clear();
+          const now = Date.now();
+          for (const fix of fixes) {
+            if (this._cache.size >= this._maxEntries) break;
+            this._cache.set(fix.errorCode, {
+              fix,
+              createdAt: now,
+              expiresAt: now + this._ttlMs
+            });
+          }
+          this._stats.size = this._cache.size;
+          this._stats.lastRefresh = now;
+        } catch (e) {
+          debug(`FixCache.setAll error: ${e}`);
+        }
+      }
+      /**
+       * Get all non-expired fixes.
+       */
+      getAll() {
+        try {
+          const now = Date.now();
+          const valid = [];
+          const expired = [];
+          for (const [key, entry] of this._cache) {
+            if (entry.expiresAt > now) {
+              valid.push(entry.fix);
+            } else {
+              expired.push(key);
+            }
+          }
+          for (const key of expired) {
+            this._cache.delete(key);
+            this._stats.evictions++;
+          }
+          this._stats.size = this._cache.size;
+          return valid;
+        } catch (e) {
+          debug(`FixCache.getAll error: ${e}`);
+          return [];
+        }
+      }
+      /** Clear all cache entries. Returns the number of entries cleared. */
+      clear() {
+        const count = this._cache.size;
+        this._cache.clear();
+        this._stats.size = 0;
+        return count;
+      }
+      /** Get cache statistics. */
+      get stats() {
+        this._stats.size = this._cache.size;
+        return { ...this._stats };
+      }
+      /** Evict the oldest cache entry. */
+      _evictOldest() {
+        if (this._cache.size === 0) return;
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this._cache) {
+          if (entry.createdAt < oldestTime) {
+            oldestTime = entry.createdAt;
+            oldestKey = key;
+          }
+        }
+        if (oldestKey !== null) {
+          this._cache.delete(oldestKey);
+          this._stats.evictions++;
+        }
+      }
+    };
+  }
+});
+
+// src/runtime/applier.ts
+import { createHash } from "crypto";
+function emptyResult(fix, fixType) {
+  return {
+    applied: false,
+    fixId: fix.fixId,
+    deploymentId: fix.deploymentId,
+    fixType,
+    modifications: {}
+  };
+}
+var MAX_FIX_CONTENT_LENGTH, FixApplier;
+var init_applier = __esm({
+  "src/runtime/applier.ts"() {
+    "use strict";
+    init_config();
+    init_log();
+    MAX_FIX_CONTENT_LENGTH = 1e4;
+    FixApplier = class {
+      _config;
+      _cache;
+      _applicationLog = [];
+      constructor(config, cache) {
+        this._config = resolveFixRuntimeConfig(config);
+        this._cache = cache;
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // Fix Lookup
+      // ═══════════════════════════════════════════════════════════════════════════
+      /**
+       * Get applicable fix for an error code.
+       *
+       * Considers A/B testing bucket if sessionId is provided. Uses
+       * crypto.createHash('md5') for deterministic bucketing across restarts.
+       */
+      getFixForError(errorCode, sessionId) {
+        try {
+          const fix = this._cache.get(errorCode);
+          if (!fix) return null;
+          if (sessionId && this._config.abTestingEnabled) {
+            const hashHex = createHash("md5").update(sessionId).digest("hex").substring(0, 8);
+            const sessionHash = parseInt(hashHex, 16);
+            if (!shouldApply(fix, sessionHash)) {
+              debug(`Fix ${fix.fixId} not applied (A/B control group)`);
+              return null;
+            }
+          }
+          return fix;
+        } catch (e) {
+          debug(`getFixForError error: ${e}`);
+          return null;
+        }
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // 1. Prompt Fix
+      // ═══════════════════════════════════════════════════════════════════════════
+      /**
+       * Apply a prompt fix to messages.
+       *
+       * Supports 4 modification types:
+       * - prepend: Add content before first system message
+       * - append:  Add content after first system message
+       * - replace: Regex replace across all messages
+       * - few_shot: Insert user/assistant example pairs after system message
+       */
+      applyPromptFix(fix, messages) {
+        try {
+          const cfg = fix.config;
+          const modificationType = cfg.modification_type ?? cfg.modificationType ?? "append";
+          const target = cfg.target ?? "system";
+          let content = cfg.content ?? "";
+          if (content.length > MAX_FIX_CONTENT_LENGTH) {
+            warn(
+              `Fix ${fix.fixId} content truncated from ${content.length} to ${MAX_FIX_CONTENT_LENGTH} chars`
+            );
+            content = content.slice(0, MAX_FIX_CONTENT_LENGTH);
+          }
+          const result = emptyResult(fix, "prompt");
+          if (this._config.dryRun) {
+            result.modifications = {
+              type: modificationType,
+              target,
+              contentPreview: content.slice(0, 100)
+            };
+            return { messages, result };
+          }
+          let modified = messages.map((m) => ({ ...m }));
+          if (modificationType === "prepend") {
+            modified = this._prependToTarget(modified, target, content);
+            result.applied = true;
+            result.modifications = { type: "prepend", target };
+          } else if (modificationType === "append") {
+            modified = this._appendToTarget(modified, target, content);
+            result.applied = true;
+            result.modifications = { type: "append", target };
+          } else if (modificationType === "replace") {
+            const pattern = cfg.pattern ?? "";
+            if (pattern) {
+              modified = this._replaceInMessages(modified, pattern, content);
+              result.applied = true;
+              result.modifications = { type: "replace", pattern };
+            }
+          } else if (modificationType === "few_shot") {
+            const examples = cfg.examples ?? [];
+            if (examples.length > 0) {
+              modified = this._addFewShotExamples(modified, examples);
+              result.applied = true;
+              result.modifications = { type: "few_shot", count: examples.length };
+            }
+          }
+          return { messages: modified, result };
+        } catch (e) {
+          debug(`applyPromptFix error: ${e}`);
+          return {
+            messages,
+            result: {
+              applied: false,
+              fixId: fix.fixId,
+              fixType: "prompt",
+              modifications: {},
+              error: String(e)
+            }
+          };
+        }
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // 2. Parameter Fix
+      // ═══════════════════════════════════════════════════════════════════════════
+      /**
+       * Apply a parameter fix — merge config.parameters into params.
+       */
+      applyParameterFix(fix, params) {
+        try {
+          const newParams = fix.config.parameters ?? {};
+          const result = emptyResult(fix, "parameter");
+          if (this._config.dryRun) {
+            result.modifications = { parameters: newParams };
+            return { params, result };
+          }
+          const modified = { ...params, ...newParams };
+          result.applied = true;
+          result.modifications = { parameters: newParams };
+          return { params: modified, result };
+        } catch (e) {
+          debug(`applyParameterFix error: ${e}`);
+          return {
+            params,
+            result: {
+              applied: false,
+              fixId: fix.fixId,
+              fixType: "parameter",
+              modifications: {},
+              error: String(e)
+            }
+          };
+        }
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // 3. Retry Fix (async — uses setTimeout for sleeping)
+      // ═══════════════════════════════════════════════════════════════════════════
+      /**
+       * Apply a retry fix to an async operation.
+       *
+       * Retries with exponential backoff + jitter using
+       * `await new Promise(r => setTimeout(r, delay))`.
+       */
+      async applyRetryFix(fix, operation) {
+        const cfg = fix.config;
+        const maxRetries = cfg.max_retries ?? cfg.maxRetries ?? 3;
+        const initialDelayMs = cfg.initial_delay_ms ?? cfg.initialDelayMs ?? 1e3;
+        const maxDelayMs = cfg.max_delay_ms ?? cfg.maxDelayMs ?? 3e4;
+        const exponentialBase = cfg.exponential_base ?? cfg.exponentialBase ?? 2;
+        const jitter = cfg.jitter ?? true;
+        const retryOn = cfg.retry_on ?? cfg.retryOn ?? [];
+        const result = emptyResult(fix, "retry");
+        if (this._config.dryRun) {
+          result.modifications = { maxRetries, initialDelayMs };
+          const value = await operation();
+          return { value, result };
+        }
+        let lastError = null;
+        let attempts = 0;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+          attempts++;
+          try {
+            const value = await operation();
+            result.applied = true;
+            result.modifications = { attempts };
+            return { value, result };
+          } catch (e) {
+            lastError = e instanceof Error ? e : new Error(String(e));
+            const errorType = lastError.constructor.name;
+            if (retryOn.length > 0 && !retryOn.includes(errorType)) {
+              throw lastError;
+            }
+            if (attempt < maxRetries) {
+              let delayMs = Math.min(
+                initialDelayMs * Math.pow(exponentialBase, attempt),
+                maxDelayMs
+              );
+              if (jitter) {
+                delayMs *= 0.5 + Math.random();
+              }
+              debug(
+                `Retry ${attempt + 1}/${maxRetries} after ${Math.round(delayMs)}ms`
+              );
+              await new Promise((r) => setTimeout(r, delayMs));
+            }
+          }
+        }
+        result.applied = true;
+        result.error = lastError?.message;
+        result.modifications = { attempts, exhausted: true };
+        throw lastError;
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // 4. Fallback Fix
+      // ═══════════════════════════════════════════════════════════════════════════
+      /**
+       * Apply a fallback fix.
+       *
+       * - 'model': Replace params.model with the fallback model
+       * - 'default': Set params._fallbackResponse for the caller to use
+       */
+      applyFallbackFix(fix, params) {
+        try {
+          const cfg = fix.config;
+          const fallbackType = cfg.fallback_type ?? cfg.fallbackType ?? "model";
+          const fallbackConfig = cfg.fallback_config ?? cfg.fallbackConfig ?? {};
+          const result = emptyResult(fix, "fallback");
+          if (this._config.dryRun) {
+            result.modifications = { fallbackType, fallbackConfig };
+            return { params, result };
+          }
+          const modified = { ...params };
+          if (fallbackType === "model") {
+            const fallbackModel = fallbackConfig.model;
+            if (fallbackModel) {
+              modified.model = fallbackModel;
+              result.applied = true;
+              result.modifications = { model: fallbackModel };
+            }
+          } else if (fallbackType === "default") {
+            const defaultResponse = fallbackConfig.response;
+            if (defaultResponse !== void 0) {
+              modified._fallbackResponse = defaultResponse;
+              result.applied = true;
+              result.modifications = { defaultResponse: true };
+            }
+          }
+          return { params: modified, result };
+        } catch (e) {
+          debug(`applyFallbackFix error: ${e}`);
+          return {
+            params,
+            result: {
+              applied: false,
+              fixId: fix.fixId,
+              fixType: "fallback",
+              modifications: {},
+              error: String(e)
+            }
+          };
+        }
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // 5. Guard Fix
+      // ═══════════════════════════════════════════════════════════════════════════
+      /**
+       * Apply a guard fix (validation).
+       *
+       * Guard types:
+       * - content_filter: Regex-based blocked patterns
+       * - format_check:   JSON.parse() validity
+       * - input_validation / output_validation: min/max length
+       */
+      applyGuardFix(fix, content, isInput = true) {
+        try {
+          const cfg = fix.config;
+          const guardType = cfg.guard_type ?? cfg.guardType ?? "output_validation";
+          const guardConfig = cfg.guard_config ?? cfg.guardConfig ?? {};
+          const result = emptyResult(fix, "guard");
+          if (isInput && guardType !== "input_validation" && guardType !== "content_filter") {
+            return { content, passed: true, result };
+          }
+          if (!isInput && guardType !== "output_validation" && guardType !== "format_check") {
+            return { content, passed: true, result };
+          }
+          if (this._config.dryRun) {
+            result.modifications = { guardType };
+            return { content, passed: true, result };
+          }
+          let passed = true;
+          if (guardType === "content_filter") {
+            const blockedPatterns = guardConfig.blocked_patterns ?? guardConfig.blockedPatterns ?? [];
+            for (const pattern of blockedPatterns) {
+              const regex = this._safeCompileRegex(pattern);
+              if (regex && regex.test(content)) {
+                passed = false;
+                break;
+              }
+            }
+          } else if (guardType === "format_check") {
+            const requiredFormat = guardConfig.format;
+            if (requiredFormat === "json") {
+              try {
+                JSON.parse(content);
+              } catch {
+                passed = false;
+              }
+            }
+          } else if (guardType === "input_validation" || guardType === "output_validation") {
+            const minLength = guardConfig.min_length ?? guardConfig.minLength ?? 0;
+            const maxLength = guardConfig.max_length ?? guardConfig.maxLength ?? Infinity;
+            if (content.length < minLength || content.length > maxLength) {
+              passed = false;
+            }
+          }
+          result.applied = true;
+          result.modifications = { passed, guardType };
+          return { content, passed, result };
+        } catch (e) {
+          debug(`applyGuardFix error: ${e}`);
+          return {
+            content,
+            passed: true,
+            result: {
+              applied: false,
+              fixId: fix.fixId,
+              fixType: "guard",
+              modifications: {},
+              error: String(e)
+            }
+          };
+        }
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // Application Log
+      // ═══════════════════════════════════════════════════════════════════════════
+      /** Log a fix application result. */
+      logApplication(result) {
+        this._applicationLog.push(result);
+        if (this._applicationLog.length > 1e3) {
+          this._applicationLog = this._applicationLog.slice(-500);
+        }
+      }
+      /** Get the application log. */
+      getApplicationLog() {
+        return [...this._applicationLog];
+      }
+      // ═══════════════════════════════════════════════════════════════════════════
+      // Private Helpers
+      // ═══════════════════════════════════════════════════════════════════════════
+      /**
+       * Safely compile a regex pattern from untrusted input.
+       * Returns null if invalid or too long.
+       */
+      _safeCompileRegex(pattern, maxLength = 500) {
+        if (!pattern || pattern.length > maxLength) return null;
+        try {
+          return new RegExp(pattern, "i");
+        } catch {
+          debug(`Invalid regex pattern (length=${pattern.length})`);
+          return null;
+        }
+      }
+      /** Prepend content to the first message matching the target role. */
+      _prependToTarget(messages, target, content) {
+        return messages.map((msg) => {
+          if (msg.role === target) {
+            return {
+              ...msg,
+              content: content + "\n\n" + (msg.content ?? "")
+            };
+          }
+          return msg;
+        });
+      }
+      /** Append content to the first message matching the target role. */
+      _appendToTarget(messages, target, content) {
+        return messages.map((msg) => {
+          if (msg.role === target) {
+            return {
+              ...msg,
+              content: (msg.content ?? "") + "\n\n" + content
+            };
+          }
+          return msg;
+        });
+      }
+      /** Regex replace across all messages. */
+      _replaceInMessages(messages, pattern, replacement) {
+        const regex = this._safeCompileRegex(pattern);
+        if (!regex) {
+          debug("Skipping invalid regex pattern in prompt fix");
+          return messages;
+        }
+        return messages.map((msg) => {
+          const msgContent = msg.content;
+          if (typeof msgContent === "string") {
+            return { ...msg, content: msgContent.replace(regex, replacement) };
+          }
+          return msg;
+        });
+      }
+      /** Add few-shot examples after the first system message. */
+      _addFewShotExamples(messages, examples) {
+        const result = [];
+        let systemFound = false;
+        for (const msg of messages) {
+          result.push(msg);
+          if (msg.role === "system" && !systemFound) {
+            systemFound = true;
+            for (const example of examples) {
+              if (example.user) {
+                result.push({ role: "user", content: example.user });
+              }
+              if (example.assistant) {
+                result.push({ role: "assistant", content: example.assistant });
+              }
+            }
+          }
+        }
+        return result;
+      }
+    };
+  }
+});
+
+// src/runtime/loader.ts
+var SDK_VERSION2, FixLoader;
+var init_loader = __esm({
+  "src/runtime/loader.ts"() {
+    "use strict";
+    init_config();
+    init_config();
+    init_log();
+    SDK_VERSION2 = "0.1.3";
+    FixLoader = class _FixLoader {
+      _config;
+      _cache;
+      _refreshTimer = null;
+      _lastLoadTime = null;
+      _consecutiveFailures = 0;
+      _circuitOpenUntil = 0;
+      _onLoadCallbacks = [];
+      // Circuit breaker settings
+      static CIRCUIT_BREAKER_THRESHOLD = 3;
+      static CIRCUIT_BREAKER_COOLDOWN_MS = 3e4;
+      constructor(config, cache) {
+        this._config = resolveFixRuntimeConfig(config);
+        this._cache = cache;
+      }
+      /** Timestamp of last successful load. */
+      get lastLoadTime() {
+        return this._lastLoadTime;
+      }
+      /**
+       * Start the loader: perform initial load and start background refresh.
+       *
+       * Never throws — failures are logged and the runtime degrades gracefully.
+       */
+      start() {
+        try {
+          if (!this._config.enabled) {
+            debug("Fix runtime disabled, skipping loader start");
+            return;
+          }
+          if (!this._config.apiKey) {
+            warn("No API key configured, fixes will not be loaded");
+            return;
+          }
+          this.loadSync().catch((e) => {
+            debug(`Initial fix load failed: ${e}`);
+          });
+          if (this._config.autoRefresh) {
+            this._startRefreshInterval();
+          }
+        } catch (e) {
+          debug(`FixLoader.start error: ${e}`);
+        }
+      }
+      /** Stop the loader: clear the refresh interval. */
+      stop() {
+        try {
+          if (this._refreshTimer !== null) {
+            clearInterval(this._refreshTimer);
+            this._refreshTimer = null;
+          }
+        } catch (e) {
+          debug(`FixLoader.stop error: ${e}`);
+        }
+      }
+      /**
+       * Register a callback invoked after each successful load.
+       */
+      onLoad(callback) {
+        this._onLoadCallbacks.push(callback);
+      }
+      /**
+       * Load fixes from the API.
+       *
+       * Name kept as "loadSync" for parity with the Python SDK, but this
+       * returns a Promise in JS (there's no synchronous fetch in Node.js).
+       */
+      async loadSync() {
+        if (!this._config.apiKey) {
+          return [];
+        }
+        const now = Date.now();
+        if (this._consecutiveFailures >= _FixLoader.CIRCUIT_BREAKER_THRESHOLD && now < this._circuitOpenUntil) {
+          debug("Fix loader circuit breaker open \u2014 skipping load");
+          return this._cache.getAll();
+        }
+        try {
+          const endpoint = this._config.apiEndpoint.replace(/\/+$/, "");
+          const url = `${endpoint}/api/v1/fixes/active`;
+          const controller = new AbortController();
+          const timeoutId = setTimeout(
+            () => controller.abort(),
+            this._config.timeoutMs
+          );
+          const response = await fetch(url, {
+            method: "GET",
+            headers: {
+              "Authorization": `Bearer ${this._config.apiKey}`,
+              "Content-Type": "application/json",
+              "X-Risicare-SDK-Version": SDK_VERSION2
+            },
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
+          if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+          }
+          const data = await response.json();
+          const fixes = this._parseResponse(data);
+          this._onLoadSuccess(fixes);
+          return fixes;
+        } catch (e) {
+          this._onLoadFailure(e);
+          throw e;
+        }
+      }
+      /** Get currently cached fixes without hitting the API. */
+      getCached() {
+        return this._cache.getAll();
+      }
+      // ─── Private ────────────────────────────────────────────────────────────
+      _parseResponse(data) {
+        const fixes = [];
+        const items = data.fixes ?? data.data ?? [];
+        if (!Array.isArray(items)) return fixes;
+        for (const item of items) {
+          try {
+            if (item && typeof item === "object") {
+              fixes.push(activeFixFromApiResponse(item));
+            }
+          } catch (e) {
+            debug(`Failed to parse fix item: ${e}`);
+          }
+        }
+        return fixes;
+      }
+      _onLoadSuccess(fixes) {
+        this._lastLoadTime = Date.now();
+        this._consecutiveFailures = 0;
+        this._cache.setAll(fixes);
+        for (const callback of this._onLoadCallbacks) {
+          try {
+            callback(fixes);
+          } catch (e) {
+            debug(`Load callback error: ${e}`);
+          }
+        }
+        debug(`Loaded ${fixes.length} active fixes`);
+      }
+      _onLoadFailure(error) {
+        this._consecutiveFailures++;
+        if (this._consecutiveFailures >= _FixLoader.CIRCUIT_BREAKER_THRESHOLD) {
+          this._circuitOpenUntil = Date.now() + _FixLoader.CIRCUIT_BREAKER_COOLDOWN_MS;
+          warn(
+            `Fix loader circuit breaker opened after ${this._consecutiveFailures} failures. Cooldown: ${_FixLoader.CIRCUIT_BREAKER_COOLDOWN_MS / 1e3}s`
+          );
+        } else {
+          debug(
+            `Fix load failed (attempt ${this._consecutiveFailures}): ${error.message}`
+          );
+        }
+      }
+      _startRefreshInterval() {
+        const tick = () => {
+          this.loadSync().catch((e) => {
+            debug(`Background fix refresh failed: ${e}`);
+          });
+        };
+        this._refreshTimer = setInterval(
+          () => {
+            if (this._consecutiveFailures >= _FixLoader.CIRCUIT_BREAKER_THRESHOLD && Date.now() < this._circuitOpenUntil) {
+              return;
+            }
+            tick();
+          },
+          this._config.refreshIntervalMs
+        );
+        this._refreshTimer.unref();
+        debug("Started fix refresh interval");
+      }
+    };
+  }
+});
+
+// src/runtime/interceptors.ts
+function createInterceptContext(operationType, operationName, options) {
+  return {
+    operationType,
+    operationName,
+    sessionId: options?.sessionId,
+    traceId: options?.traceId,
+    errorCode: options?.errorCode,
+    attempt: 1,
+    appliedFixes: []
+  };
+}
+function classifyError(error) {
+  const errorType = error.constructor.name.toLowerCase();
+  const errorMsg = error.message.toLowerCase();
+  if (errorType.includes("timeout") || errorMsg.includes("timeout") || errorMsg.includes("aborted")) {
+    return "TOOL.EXECUTION.TIMEOUT";
+  }
+  if (errorMsg.includes("rate") && errorMsg.includes("limit")) {
+    return "TOOL.EXECUTION.RATE_LIMIT";
+  }
+  if (errorMsg.includes("429") || errorMsg.includes("too many requests")) {
+    return "TOOL.EXECUTION.RATE_LIMIT";
+  }
+  if (errorType.includes("connection") || errorMsg.includes("connection") || errorMsg.includes("econnrefused") || errorMsg.includes("econnreset") || errorMsg.includes("fetch failed")) {
+    return "TOOL.EXECUTION.CONNECTION_ERROR";
+  }
+  if (errorMsg.includes("auth") || errorMsg.includes("401") || errorMsg.includes("403") || errorMsg.includes("unauthorized") || errorMsg.includes("forbidden")) {
+    return "TOOL.EXECUTION.AUTH_ERROR";
+  }
+  if (errorType.includes("syntaxerror") || errorType.includes("json") || errorMsg.includes("json") || errorMsg.includes("unexpected token")) {
+    return "OUTPUT.FORMAT.JSON_INVALID";
+  }
+  return "TOOL.EXECUTION.FAILURE";
+}
+var DefaultFixInterceptor;
+var init_interceptors = __esm({
+  "src/runtime/interceptors.ts"() {
+    "use strict";
+    init_config();
+    init_log();
+    DefaultFixInterceptor = class {
+      _config;
+      _cache;
+      _applier;
+      constructor(config, cache, applier) {
+        this._config = resolveFixRuntimeConfig(config);
+        this._cache = cache;
+        this._applier = applier;
+      }
+      /**
+       * Apply pre-call fixes.
+       *
+       * - If retrying after error: look up fix by error_code, apply
+       *   prompt/parameter/fallback fixes
+       * - Runs input guard fixes on all message content
+       */
+      preCall(ctx, messages, params) {
+        try {
+          if (!this._config.enabled) {
+            return { messages, params };
+          }
+          let modifiedMessages = messages;
+          let modifiedParams = { ...params };
+          if (ctx.errorCode) {
+            const fix = this._applier.getFixForError(ctx.errorCode, ctx.sessionId);
+            if (fix) {
+              debug(`Applying fix ${fix.fixId} for ${ctx.errorCode}`);
+              if (fix.fixType === "prompt" && messages) {
+                const msgRecords = messages;
+                const { messages: newMessages, result } = this._applier.applyPromptFix(fix, msgRecords);
+                modifiedMessages = newMessages;
+                ctx.appliedFixes.push(result);
+                this._applier.logApplication(result);
+              } else if (fix.fixType === "parameter") {
+                const { params: newParams, result } = this._applier.applyParameterFix(fix, modifiedParams);
+                modifiedParams = newParams;
+                ctx.appliedFixes.push(result);
+                this._applier.logApplication(result);
+              } else if (fix.fixType === "fallback") {
+                const { params: newParams, result } = this._applier.applyFallbackFix(fix, modifiedParams);
+                modifiedParams = newParams;
+                ctx.appliedFixes.push(result);
+                this._applier.logApplication(result);
+              }
+            }
+          }
+          if (modifiedMessages && this._config.enabled) {
+            for (const msg of modifiedMessages) {
+              const content = msg.content;
+              if (typeof content === "string") {
+                for (const fix of this._cache.getAll()) {
+                  if (fix.fixType === "guard") {
+                    const { result } = this._applier.applyGuardFix(
+                      fix,
+                      content,
+                      true
+                    );
+                    if (result.applied) {
+                      ctx.appliedFixes.push(result);
+                      this._applier.logApplication(result);
+                    }
+                  }
+                }
+              }
+            }
+          }
+          return { messages: modifiedMessages, params: modifiedParams };
+        } catch (e) {
+          debug(`DefaultFixInterceptor.preCall error: ${e}`);
+          return { messages, params };
+        }
+      }
+      /**
+       * Apply post-call fixes (output validation).
+       *
+       * Runs output guard fixes on response content.
+       */
+      postCall(ctx, response) {
+        try {
+          if (!this._config.enabled) {
+            return { response, shouldContinue: true };
+          }
+          for (const fix of this._cache.getAll()) {
+            if (fix.fixType !== "guard") continue;
+            const content = this._extractResponseContent(response);
+            if (!content) continue;
+            const { passed, result } = this._applier.applyGuardFix(
+              fix,
+              content,
+              false
+            );
+            if (result.applied) {
+              ctx.appliedFixes.push(result);
+              this._applier.logApplication(result);
+            }
+            if (!passed) {
+              warn(`Output guard failed for fix ${fix.fixId}`);
+            }
+          }
+          return { response, shouldContinue: true };
+        } catch (e) {
+          debug(`DefaultFixInterceptor.postCall error: ${e}`);
+          return { response, shouldContinue: true };
+        }
+      }
+      /**
+       * Handle errors and decide whether to retry.
+       *
+       * Classifies the error, looks up retry/fallback fixes, and returns
+       * whether the caller should retry.
+       */
+      onError(ctx, error) {
+        try {
+          if (!this._config.enabled) {
+            return { shouldRetry: false, modifiedParams: null };
+          }
+          const errorCode = classifyError(error);
+          ctx.errorCode = errorCode;
+          ctx.errorMessage = error.message;
+          const fix = this._applier.getFixForError(errorCode, ctx.sessionId);
+          if (!fix) {
+            return { shouldRetry: false, modifiedParams: null };
+          }
+          if (fix.fixType === "retry") {
+            const maxRetries = fix.config.max_retries ?? fix.config.maxRetries ?? 3;
+            if (ctx.attempt <= maxRetries) {
+              debug(
+                `Retry fix ${fix.fixId}: attempt ${ctx.attempt}/${maxRetries}`
+              );
+              const result = {
+                applied: true,
+                fixId: fix.fixId,
+                deploymentId: fix.deploymentId,
+                fixType: "retry",
+                modifications: { attempt: ctx.attempt }
+              };
+              ctx.appliedFixes.push(result);
+              this._applier.logApplication(result);
+              return { shouldRetry: true, modifiedParams: null };
+            }
+          }
+          if (fix.fixType === "fallback") {
+            const { params: modifiedParams, result } = this._applier.applyFallbackFix(fix, {});
+            if (result.applied) {
+              ctx.appliedFixes.push(result);
+              this._applier.logApplication(result);
+              return { shouldRetry: true, modifiedParams };
+            }
+          }
+          return { shouldRetry: false, modifiedParams: null };
+        } catch (e) {
+          debug(`DefaultFixInterceptor.onError error: ${e}`);
+          return { shouldRetry: false, modifiedParams: null };
+        }
+      }
+      // ─── Private ────────────────────────────────────────────────────────────
+      /** Extract text content from a response object. */
+      _extractResponseContent(response) {
+        if (typeof response === "string") return response;
+        if (response && typeof response === "object") {
+          const resp = response;
+          const choices = resp.choices;
+          if (Array.isArray(choices) && choices.length > 0) {
+            const first = choices[0];
+            const message = first?.message;
+            if (typeof message?.content === "string") {
+              return message.content;
+            }
+          }
+          const content = resp.content;
+          if (typeof content === "string") return content;
+          if (Array.isArray(content) && content.length > 0) {
+            const first = content[0];
+            if (typeof first?.text === "string") return first.text;
+          }
+        }
+        return null;
+      }
+    };
+  }
+});
+
+// src/runtime/runtime.ts
+var runtime_exports = {};
+__export(runtime_exports, {
+  FixRuntime: () => FixRuntime,
+  getFixRuntime: () => getFixRuntime,
+  initFixRuntime: () => initFixRuntime,
+  setFixRuntime: () => setFixRuntime,
+  shutdownFixRuntime: () => shutdownFixRuntime
+});
+function getFixRuntime() {
+  return G2[RUNTIME_KEY];
+}
+function setFixRuntime(runtime) {
+  G2[RUNTIME_KEY] = runtime;
+}
+function initFixRuntime(config) {
+  try {
+    const existing = G2[RUNTIME_KEY];
+    if (existing) {
+      debug("Fix runtime already initialized");
+      return existing;
+    }
+    const runtime = new FixRuntime(config);
+    runtime.start();
+    G2[RUNTIME_KEY] = runtime;
+    return runtime;
+  } catch (e) {
+    warn(`initFixRuntime failed: ${e}`);
+    const fallback = new FixRuntime({ ...config, enabled: false });
+    G2[RUNTIME_KEY] = fallback;
+    return fallback;
+  }
+}
+function shutdownFixRuntime() {
+  try {
+    const runtime = G2[RUNTIME_KEY];
+    if (runtime) {
+      runtime.stop();
+    }
+    G2[RUNTIME_KEY] = void 0;
+  } catch (e) {
+    debug(`shutdownFixRuntime error: ${e}`);
+    G2[RUNTIME_KEY] = void 0;
+  }
+}
+var G2, RUNTIME_KEY, FixRuntime;
+var init_runtime = __esm({
+  "src/runtime/runtime.ts"() {
+    "use strict";
+    init_cache();
+    init_config();
+    init_applier();
+    init_loader();
+    init_interceptors();
+    init_log();
+    G2 = globalThis;
+    RUNTIME_KEY = "__risicare_fix_runtime";
+    FixRuntime = class {
+      _config;
+      _cache;
+      _loader;
+      _applier;
+      _interceptor;
+      _started = false;
+      // Effectiveness tracking
+      _fixApplications = /* @__PURE__ */ new Map();
+      _fixSuccesses = /* @__PURE__ */ new Map();
+      constructor(config) {
+        this._config = resolveFixRuntimeConfig(config);
+        this._cache = new FixCache(this._config);
+        this._loader = new FixLoader(config, this._cache);
+        this._applier = new FixApplier(config, this._cache);
+        this._interceptor = new DefaultFixInterceptor(
+          config,
+          this._cache,
+          this._applier
+        );
+      }
+      // ─── Accessors ──────────────────────────────────────────────────────────
+      /** Runtime configuration (with defaults resolved). */
+      get config() {
+        return this._config;
+      }
+      /** Whether the runtime is enabled and started. */
+      get isEnabled() {
+        return this._config.enabled && this._started;
+      }
+      /** The fix cache. */
+      get cache() {
+        return this._cache;
+      }
+      /** The fix loader. */
+      get loader() {
+        return this._loader;
+      }
+      /** The fix applier. */
+      get applier() {
+        return this._applier;
+      }
+      /** The interceptor. */
+      get interceptor() {
+        return this._interceptor;
+      }
+      // ─── Lifecycle ──────────────────────────────────────────────────────────
+      /**
+       * Start the runtime.
+       *
+       * Triggers initial fix load and starts background refresh.
+       * Never throws — failures degrade gracefully.
+       */
+      start() {
+        try {
+          if (this._started) return;
+          if (!this._config.enabled) {
+            debug("Fix runtime disabled");
+            return;
+          }
+          debug("Starting fix runtime...");
+          this._loader.start();
+          this._started = true;
+          debug("Fix runtime started");
+        } catch (e) {
+          warn(`Fix runtime start failed: ${e}`);
+        }
+      }
+      /**
+       * Stop the runtime.
+       *
+       * Stops background refresh and clears the cache.
+       * Never throws.
+       */
+      stop() {
+        try {
+          if (!this._started) return;
+          debug("Stopping fix runtime...");
+          this._loader.stop();
+          this._cache.clear();
+          this._started = false;
+          debug("Fix runtime stopped");
+        } catch (e) {
+          debug(`Fix runtime stop error: ${e}`);
+        }
+      }
+      // ─── Intercept API ──────────────────────────────────────────────────────
+      /**
+       * Intercept a call: create context and run preCall fixes.
+       *
+       * Returns modified messages/params and the InterceptContext for
+       * use in subsequent interceptResponse / interceptError calls.
+       */
+      interceptCall(operationType, operationName, messages, params, options) {
+        const ctx = createInterceptContext(operationType, operationName, options);
+        try {
+          if (!this.isEnabled) {
+            return { messages, params, ctx };
+          }
+          const result = this._interceptor.preCall(ctx, messages, params);
+          return { messages: result.messages, params: result.params, ctx };
+        } catch (e) {
+          debug(`interceptCall error: ${e}`);
+          return { messages, params, ctx };
+        }
+      }
+      /**
+       * Intercept a response: run postCall fixes (output validation).
+       */
+      interceptResponse(ctx, response) {
+        try {
+          if (!this.isEnabled) {
+            return { response, shouldContinue: true };
+          }
+          const result = this._interceptor.postCall(ctx, response);
+          this._trackSuccess(ctx);
+          return result;
+        } catch (e) {
+          debug(`interceptResponse error: ${e}`);
+          return { response, shouldContinue: true };
+        }
+      }
+      /**
+       * Intercept an error: decide on retry/fallback.
+       */
+      interceptError(ctx, error) {
+        try {
+          if (!this.isEnabled) {
+            return { shouldRetry: false, modifiedParams: null };
+          }
+          ctx.attempt++;
+          const result = this._interceptor.onError(ctx, error);
+          if (!result.shouldRetry) {
+            this._trackFailure(ctx);
+          }
+          return result;
+        } catch (e) {
+          debug(`interceptError error: ${e}`);
+          return { shouldRetry: false, modifiedParams: null };
+        }
+      }
+      // ─── Direct Fix Access ──────────────────────────────────────────────────
+      /**
+       * Get applicable fix for an error code.
+       */
+      getFix(errorCode, sessionId) {
+        try {
+          if (!this.isEnabled) return null;
+          return this._applier.getFixForError(errorCode, sessionId);
+        } catch (e) {
+          debug(`getFix error: ${e}`);
+          return null;
+        }
+      }
+      /**
+       * Manually refresh fixes from the API.
+       */
+      async refreshFixes() {
+        try {
+          return await this._loader.loadSync();
+        } catch (e) {
+          debug(`refreshFixes error: ${e}`);
+          return [];
+        }
+      }
+      // ─── Effectiveness ──────────────────────────────────────────────────────
+      /** Get effectiveness statistics for all fixes. */
+      getEffectivenessStats() {
+        const stats = {};
+        for (const [fixId, applications] of this._fixApplications) {
+          const successes = this._fixSuccesses.get(fixId) ?? 0;
+          stats[fixId] = {
+            applications,
+            successes,
+            successRate: applications > 0 ? successes / applications : 0
+          };
+        }
+        return stats;
+      }
+      // ─── Private ────────────────────────────────────────────────────────────
+      _trackSuccess(ctx) {
+        for (const result of ctx.appliedFixes) {
+          if (result.applied && result.fixId) {
+            this._fixApplications.set(
+              result.fixId,
+              (this._fixApplications.get(result.fixId) ?? 0) + 1
+            );
+            this._fixSuccesses.set(
+              result.fixId,
+              (this._fixSuccesses.get(result.fixId) ?? 0) + 1
+            );
+          }
+        }
+      }
+      _trackFailure(ctx) {
+        for (const result of ctx.appliedFixes) {
+          if (result.applied && result.fixId) {
+            this._fixApplications.set(
+              result.fixId,
+              (this._fixApplications.get(result.fixId) ?? 0) + 1
+            );
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/config.ts
 var DEFAULT_ENDPOINT = "https://app.risicare.ai";
 function resolveConfig(config) {
@@ -403,48 +1819,8 @@ function shouldSample(traceId, sampleRate) {
   return hash / 4294967295 < sampleRate;
 }
 
-// src/globals.ts
-import { AsyncLocalStorage } from "async_hooks";
-var G = globalThis;
-var PREFIX = "__risicare_";
-function getClient() {
-  return G[PREFIX + "client"];
-}
-function setClient(client) {
-  G[PREFIX + "client"] = client;
-}
-function getTracer() {
-  return G[PREFIX + "tracer"];
-}
-function setTracer(tracer) {
-  G[PREFIX + "tracer"] = tracer;
-}
-function getContextStorage() {
-  if (!G[PREFIX + "ctx"]) {
-    G[PREFIX + "ctx"] = new AsyncLocalStorage();
-  }
-  return G[PREFIX + "ctx"];
-}
-function getRegistry() {
-  if (!G[PREFIX + "registry"]) {
-    G[PREFIX + "registry"] = /* @__PURE__ */ new Map();
-  }
-  return G[PREFIX + "registry"];
-}
-function getOpCount() {
-  return G[PREFIX + "opcount"] ?? 0;
-}
-function setOpCount(n) {
-  G[PREFIX + "opcount"] = n;
-}
-function getDebug() {
-  return G[PREFIX + "debug"] ?? false;
-}
-function setDebugFlag(enabled) {
-  G[PREFIX + "debug"] = enabled;
-}
-
 // src/context/storage.ts
+init_globals();
 function storage() {
   return getContextStorage();
 }
@@ -546,7 +1922,8 @@ var Tracer = class {
     const session2 = getCurrentSession();
     const agent2 = getCurrentAgent();
     const phase = getCurrentPhase();
-    const traceId = opts.traceId ?? parentSpan?.traceId ?? generateTraceId();
+    const ctx = getContext();
+    const traceId = opts.traceId ?? parentSpan?.traceId ?? ctx._rootTraceId ?? generateTraceId();
     if (!parentSpan && this._sampleRate < 1) {
       if (!shouldSample(traceId, this._sampleRate)) {
         return fn(NOOP_SPAN);
@@ -641,22 +2018,8 @@ var Tracer = class {
   }
 };
 
-// src/utils/log.ts
-function setDebug(enabled) {
-  setDebugFlag(enabled);
-}
-function debug(msg) {
-  if (getDebug()) {
-    process.stderr.write(`[risicare] ${msg}
-`);
-  }
-}
-function warn(msg) {
-  process.stderr.write(`[risicare] WARNING: ${msg}
-`);
-}
-
 // src/exporters/batch.ts
+init_log();
 var BatchSpanProcessor = class _BatchSpanProcessor {
   _exporters;
   _batchSize;
@@ -677,7 +2040,14 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
   failedExports = 0;
   constructor(options) {
     this._exporters = [...options.exporters];
-    this._batchSize = options.batchSize ?? 100;
+    const requestedBatchSize = options.batchSize ?? 100;
+    const clampedBatchSize = Math.max(1, Math.min(requestedBatchSize, 1e4));
+    if (clampedBatchSize !== requestedBatchSize) {
+      warn(
+        `batchSize=${requestedBatchSize} is outside the allowed range [1, 10000]; clamping to ${clampedBatchSize}`
+      );
+    }
+    this._batchSize = clampedBatchSize;
     this._batchTimeoutMs = options.batchTimeoutMs ?? 1e3;
     this._maxQueueSize = options.maxQueueSize ?? 1e4;
     this._debug = options.debug ?? false;
@@ -807,6 +2177,7 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
 };
 
 // src/exporters/http.ts
+init_log();
 var SDK_VERSION = "0.1.1";
 var HttpExporter = class {
   name = "http";
@@ -817,11 +2188,15 @@ var HttpExporter = class {
   _timeoutMs;
   _maxRetries;
   _compress;
-  // Circuit breaker
+  // Circuit breaker (CON-201 / B-16). Threshold and cooldown sized for
+  // a "30-second prod restart" scenario: with default 1s batch flush a
+  // 5-failure threshold opens the circuit ~5s into an outage and the 60s
+  // cooldown gives the gateway time to come back before the half-open
+  // probe fires. Lower numbers (was 3@30s) tripped on transient blips.
   _consecutiveFailures = 0;
   _circuitOpenUntil = 0;
-  _circuitBreakerThreshold = 3;
-  _circuitBreakerCooldownMs = 3e4;
+  _circuitBreakerThreshold = 5;
+  _circuitBreakerCooldownMs = 6e4;
   constructor(options) {
     this._endpoint = options.endpoint.replace(/\/+$/, "");
     this._apiKey = options.apiKey;
@@ -932,6 +2307,8 @@ var ConsoleExporter = class {
 };
 
 // src/client.ts
+init_log();
+init_globals();
 var RisicareClient = class {
   config;
   processor;
@@ -971,6 +2348,29 @@ var RisicareClient = class {
       traceContent: this.config.traceContent
     });
     this.processor.start();
+    if (this.config.apiKey && this.config.enabled) {
+      try {
+        const { initFixRuntime: initFixRuntime2 } = (init_runtime(), __toCommonJS(runtime_exports));
+        initFixRuntime2({
+          apiEndpoint: this.config.endpoint,
+          apiKey: this.config.apiKey,
+          enabled: true,
+          debug: this.config.debug
+        });
+      } catch (e) {
+        const errName = e instanceof Error ? e.name : "Error";
+        const errMsg = e instanceof Error ? e.message : String(e);
+        try {
+          console.warn(
+            `[risicare] FixRuntime initialization failed \u2014 auto-fix is OFFLINE for this process. endpoint=${this.config.endpoint} error=${errName}: ${errMsg}. Tracing + reporting still work; only fix application is disabled. Pass debug:true in init() options for the full traceback.`
+          );
+        } catch {
+        }
+        if (this.config.debug) {
+          debug(`FixRuntime init traceback: ${e instanceof Error && e.stack ? e.stack : String(e)}`);
+        }
+      }
+    }
     this._registerShutdownHooks();
     setDebug(this.config.debug);
     debug(`Initialized: enabled=${this.config.enabled}, endpoint=${this.config.endpoint}`);
@@ -1022,6 +2422,11 @@ function init(config) {
   setTracer(client.tracer);
 }
 async function shutdown() {
+  try {
+    const { shutdownFixRuntime: shutdownFixRuntime2 } = (init_runtime(), __toCommonJS(runtime_exports));
+    shutdownFixRuntime2();
+  } catch {
+  }
   const client = getClient();
   if (!client) return;
   await client.shutdown();
@@ -1063,12 +2468,39 @@ function getMetrics() {
     queueUtilization: 0
   };
 }
+var _ERROR_DEDUP_TTL_MS = 5 * 60 * 1e3;
+var _ERROR_DEDUP_MAX = 1e3;
+var _recentErrors = /* @__PURE__ */ new Map();
+function _errorFingerprint(err) {
+  const raw = `${err.constructor?.name ?? "Error"}:${String(err.message ?? "").slice(0, 200)}`;
+  const { createHash: createHash2 } = __require("crypto");
+  return createHash2("sha256").update(raw).digest("hex").slice(0, 16);
+}
+function _isDuplicateError(fingerprint) {
+  const now = Date.now();
+  for (const [fp, ts] of _recentErrors) {
+    if (now - ts > _ERROR_DEDUP_TTL_MS) _recentErrors.delete(fp);
+    else break;
+  }
+  if (_recentErrors.has(fingerprint)) return true;
+  if (_recentErrors.size >= _ERROR_DEDUP_MAX) {
+    const oldest = _recentErrors.keys().next().value;
+    if (oldest !== void 0) _recentErrors.delete(oldest);
+  }
+  _recentErrors.set(fingerprint, now);
+  return false;
+}
 function reportError(error, options) {
   try {
     const tracer = getTracer2();
     if (!tracer) return;
-    const err = error instanceof Error ? error : new Error(String(error));
+    const err = error instanceof Error ? error : new Error(String(error ?? "unknown"));
     const spanName = options?.name ?? `error:${err.constructor.name}`;
+    const fp = _errorFingerprint(err);
+    if (_isDuplicateError(fp)) {
+      debug(`reportError: duplicate suppressed (fp=${fp.slice(0, 8)})`);
+      return;
+    }
     tracer.startSpan({ name: spanName, kind: "internal" /* INTERNAL */ }, (span) => {
       span.setStatus("error" /* ERROR */, err.message);
       span.setAttribute("error", true);
@@ -1088,7 +2520,7 @@ function reportError(error, options) {
 }
 function score(traceId, name, value, options) {
   try {
-    if (typeof value !== "number" || value < 0 || value > 1) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
       debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);
       return;
     }
@@ -1138,7 +2570,7 @@ function withAgent(options, fn) {
 }
 
 // src/decorators/agent.ts
-function agent(options, fn) {
+function _wrapAgent(options, fn) {
   const spanName = `agent:${options.name ?? "agent"}`;
   return (...args) => {
     const tracer = getTracer2();
@@ -1152,6 +2584,12 @@ function agent(options, fn) {
     });
   };
 }
+function agent(options, fn) {
+  if (fn === void 0) {
+    return (realFn) => _wrapAgent(options, realFn);
+  }
+  return _wrapAgent(options, fn);
+}
 
 // src/context/session.ts
 function withSession(options, fn) {
@@ -1166,12 +2604,18 @@ function withSession(options, fn) {
 }
 
 // src/decorators/session.ts
-function session(optionsOrResolver, fn) {
+function _wrapSession(optionsOrResolver, fn) {
   return (...args) => {
     const options = typeof optionsOrResolver === "function" ? optionsOrResolver(...args) : optionsOrResolver;
     return withSession(options, () => fn(...args));
   };
 }
+function session(optionsOrResolver, fn) {
+  if (fn === void 0) {
+    return (realFn) => _wrapSession(optionsOrResolver, realFn);
+  }
+  return _wrapSession(optionsOrResolver, fn);
+}
 
 // src/context/phase.ts
 function withPhase(phase, fn) {
@@ -1283,8 +2727,22 @@ function getTraceContext() {
   const span = getCurrentSpan();
   const session2 = getCurrentSession();
   const agent2 = getCurrentAgent();
+  let traceId;
+  if (span) {
+    traceId = span.traceId;
+  } else {
+    const ctx = getContext();
+    if (ctx._rootTraceId) {
+      traceId = ctx._rootTraceId;
+    } else {
+      traceId = generateTraceId();
+      if (ctx.session || ctx.agent) {
+        ctx._rootTraceId = traceId;
+      }
+    }
+  }
   return {
-    traceId: span?.traceId ?? generateTraceId(),
+    traceId,
     spanId: span?.spanId ?? generateSpanId(),
     sessionId: session2?.sessionId,
     agentId: agent2?.agentId
@@ -1352,6 +2810,7 @@ function extractTraceContext(headers) {
 }
 
 // src/context/registry.ts
+init_globals();
 var DEFAULT_TTL_MS = 6e4;
 var MAX_ENTRIES = 1e4;
 var CLEANUP_INTERVAL = 100;
@@ -1421,10 +2880,34 @@ async function* tracedStream(source, options) {
   }
 }
 
+// src/context/dedup.ts
+function suppressProviderInstrumentation(fn) {
+  return runWithContext({ _suppressProviderInstrumentation: true }, fn);
+}
+function isProviderInstrumentationSuppressed() {
+  return getContext()._suppressProviderInstrumentation === true;
+}
+
 // src/frameworks/langchain.ts
 var RisicareCallbackHandler = class {
   name = "RisicareCallbackHandler";
   _spans = /* @__PURE__ */ new Map();
+  /**
+   * Run a function with provider instrumentation suppressed.
+   *
+   * Wrap your chain.invoke() call with this to prevent duplicate spans.
+   * The handler creates LLM/tool spans, so provider proxies (patchOpenAI, etc.)
+   * should be suppressed during chain execution.
+   *
+   * @example
+   *   const handler = new RisicareCallbackHandler();
+   *   const result = await handler.withSuppression(() =>
+   *     chain.invoke(input, { callbacks: [handler] })
+   *   );
+   */
+  withSuppression(fn) {
+    return suppressProviderInstrumentation(fn);
+  }
   // ── Chain lifecycle ────────────────────────────────────────────────────────
   handleChainStart(chain, _inputs, runId, parentRunId) {
     const tracer = getTracer2();
@@ -1602,6 +3085,7 @@ function instrumentLangGraph(graph) {
 }
 
 // src/frameworks/instructor.ts
+init_log();
 function patchInstructor(client) {
   return new Proxy(client, {
     get(target, prop, receiver) {
@@ -1652,14 +3136,6 @@ function patchInstructor(client) {
   });
 }
 
-// src/context/dedup.ts
-function suppressProviderInstrumentation(fn) {
-  return runWithContext({ _suppressProviderInstrumentation: true }, fn);
-}
-function isProviderInstrumentationSuppressed() {
-  return getContext()._suppressProviderInstrumentation === true;
-}
-
 // src/frameworks/llamaindex.ts
 var RisicareLlamaIndexHandler = class {
   _spans = /* @__PURE__ */ new Map();
@@ -1758,14 +3234,183 @@ var RisicareLlamaIndexHandler = class {
     return "component";
   }
 };
+
+// src/index.ts
+init_runtime();
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { Buffer as Buffer2 } from "buffer";
+var DEFAULT_TIMESTAMP_TOLERANCE_S = 300;
+var SIGNATURE_HEADER = "X-Risicare-Signature";
+var TIMESTAMP_HEADER = "X-Risicare-Timestamp";
+var SUPPORTED_SCHEMES = ["v1"];
+var HEX_SHA256_RE = /^[0-9a-f]{64}$/;
+var WebhookVerificationError = class _WebhookVerificationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+    Object.setPrototypeOf(this, _WebhookVerificationError.prototype);
+  }
+};
+function getHeader(headers, name) {
+  const lower = name.toLowerCase();
+  if (typeof headers.get === "function") {
+    const accessor = headers;
+    const v = accessor.get(name) ?? accessor.get(lower);
+    return v ?? void 0;
+  }
+  const dict = headers;
+  const raw = dict[name] ?? dict[lower];
+  if (raw === void 0) {
+    return void 0;
+  }
+  if (Array.isArray(raw)) {
+    return raw[0];
+  }
+  return raw;
+}
+function coercePayload(payload) {
+  if (typeof payload === "string") {
+    return Buffer2.from(payload, "utf-8");
+  }
+  if (payload instanceof Uint8Array) {
+    return Buffer2.from(
+      payload.buffer,
+      payload.byteOffset,
+      payload.byteLength
+    );
+  }
+  if (payload instanceof ArrayBuffer) {
+    return Buffer2.from(payload);
+  }
+  throw new WebhookVerificationError(
+    `payload must be Uint8Array, ArrayBuffer, Buffer, or string, got ${typeof payload}`
+  );
+}
+function parseSignatureHeader(raw) {
+  const parts = /* @__PURE__ */ Object.create(null);
+  for (const rawSegment of raw.split(",")) {
+    const segment = rawSegment.trim();
+    if (segment === "") {
+      continue;
+    }
+    const eqIdx = segment.indexOf("=");
+    if (eqIdx === -1) {
+      throw new WebhookVerificationError(
+        `Malformed segment in ${SIGNATURE_HEADER}: ${JSON.stringify(segment)}`
+      );
+    }
+    const key = segment.slice(0, eqIdx).trim();
+    const value = segment.slice(eqIdx + 1).trim();
+    parts[key] = value;
+  }
+  if (!("t" in parts)) {
+    throw new WebhookVerificationError(
+      `Missing \`t=\` (timestamp) in ${SIGNATURE_HEADER}`
+    );
+  }
+  let scheme;
+  for (const candidate of SUPPORTED_SCHEMES) {
+    if (candidate in parts) {
+      scheme = candidate;
+      break;
+    }
+  }
+  if (scheme === void 0) {
+    const keys = Object.keys(parts).sort();
+    throw new WebhookVerificationError(
+      `No supported signature scheme in ${SIGNATURE_HEADER}; expected one of (${SUPPORTED_SCHEMES.map((s) => `'${s}'`).join(", ")}), got keys [${keys.map((k) => `'${k}'`).join(", ")}]`
+    );
+  }
+  const tRaw = parts["t"];
+  if (!/^-?\d+$/.test(tRaw)) {
+    throw new WebhookVerificationError(
+      `Non-integer timestamp in ${SIGNATURE_HEADER}: ${JSON.stringify(tRaw)}`
+    );
+  }
+  const ts = parseInt(tRaw, 10);
+  if (!Number.isFinite(ts)) {
+    throw new WebhookVerificationError(
+      `Non-integer timestamp in ${SIGNATURE_HEADER}: ${JSON.stringify(tRaw)}`
+    );
+  }
+  const sigHex = parts[scheme];
+  if (sigHex === void 0 || sigHex === "") {
+    throw new WebhookVerificationError(
+      `Empty ${scheme}= value in ${SIGNATURE_HEADER}`
+    );
+  }
+  return [ts, sigHex];
+}
+function safeHexEqual(computed, expected) {
+  if (!HEX_SHA256_RE.test(expected)) {
+    return false;
+  }
+  const a = Buffer2.from(computed, "hex");
+  const b = Buffer2.from(expected, "hex");
+  if (a.length !== b.length) {
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+function verifyWebhookSignature(payload, headers, secret, opts = {}) {
+  const toleranceS = opts.toleranceS ?? DEFAULT_TIMESTAMP_TOLERANCE_S;
+  const payloadBytes = coercePayload(payload);
+  const sigHeader = getHeader(headers, SIGNATURE_HEADER);
+  if (sigHeader === void 0 || sigHeader === "") {
+    throw new WebhookVerificationError(
+      `Missing ${SIGNATURE_HEADER} header`
+    );
+  }
+  const tsHeader = getHeader(headers, TIMESTAMP_HEADER);
+  if (tsHeader === void 0 || tsHeader === "") {
+    throw new WebhookVerificationError(
+      `Missing ${TIMESTAMP_HEADER} header`
+    );
+  }
+  const [tsInSig, expectedHex] = parseSignatureHeader(sigHeader);
+  if (!/^-?\d+$/.test(tsHeader)) {
+    throw new WebhookVerificationError(
+      `Non-integer ${TIMESTAMP_HEADER}: ${JSON.stringify(tsHeader)}`
+    );
+  }
+  const tsStandalone = parseInt(tsHeader, 10);
+  if (!Number.isFinite(tsStandalone)) {
+    throw new WebhookVerificationError(
+      `Non-integer ${TIMESTAMP_HEADER}: ${JSON.stringify(tsHeader)}`
+    );
+  }
+  if (tsStandalone !== tsInSig) {
+    throw new WebhookVerificationError(
+      `Timestamp mismatch: ${TIMESTAMP_HEADER}=${tsStandalone}, signature t=${tsInSig}`
+    );
+  }
+  const now = opts._now !== void 0 ? Math.trunc(opts._now) : Math.floor(Date.now() / 1e3);
+  const skew = Math.abs(now - tsInSig);
+  if (skew > toleranceS) {
+    throw new WebhookVerificationError(
+      `Webhook timestamp outside tolerance: skew=${skew}s, max=${toleranceS}s`
+    );
+  }
+  const hmac = createHmac("sha256", secret);
+  hmac.update(`${tsInSig}.`);
+  hmac.update(payloadBytes);
+  const computed = hmac.digest("hex");
+  if (!safeHexEqual(computed, expectedHex)) {
+    throw new WebhookVerificationError("Webhook signature mismatch");
+  }
+}
 export {
   AgentRole,
+  DEFAULT_TIMESTAMP_TOLERANCE_S,
   MessageType,
   RisicareCallbackHandler,
   RisicareLlamaIndexHandler,
   SemanticPhase,
   SpanKind,
   SpanStatus,
+  WebhookVerificationError,
   agent,
   disable,
   enable,
@@ -1780,12 +3425,14 @@ export {
   getCurrentSpan,
   getCurrentSpanId,
   getCurrentTraceId,
+  getFixRuntime,
   getMetrics,
   getSpanById,
   getTraceContent,
   getTraceContext,
   getTracer2 as getTracer,
   init,
+  initFixRuntime,
   injectTraceContext,
   instrumentLangGraph,
   isEnabled,
@@ -1796,6 +3443,7 @@ export {
   score,
   session,
   shutdown,
+  shutdownFixRuntime,
   suppressProviderInstrumentation,
   traceAct,
   traceCoordinate,
@@ -1806,6 +3454,7 @@ export {
   traceThink,
   tracedStream,
   unregisterSpan,
+  verifyWebhookSignature,
   withAgent,
   withPhase,
   withSession