caplyr 0.2.2 → 0.2.4

package/dist/index.js

@@ -107,6 +107,36 @@ var LogShipper = class {
   }
 };
 
+// src/mutex.ts
+var Mutex = class {
+  constructor() {
+    this.queue = [];
+    this.locked = false;
+  }
+  async acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return this.createRelease();
+    }
+    return new Promise((resolve) => {
+      this.queue.push(() => resolve(this.createRelease()));
+    });
+  }
+  createRelease() {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const next = this.queue.shift();
+      if (next) {
+        next();
+      } else {
+        this.locked = false;
+      }
+    };
+  }
+};
+
 // src/heartbeat.ts
 var Heartbeat = class {
   constructor(config) {
@@ -124,6 +154,8 @@ var Heartbeat = class {
     };
     /** Current protection status */
     this.status = "ACTIVE";
+    /** Mutex for serializing budget check → API call → trackSpend */
+    this.budgetMutex = new Mutex();
     /** Local budget limits set via config (not from server) */
     this.localDailyLimit = null;
     this.localMonthlyLimit = null;
@@ -176,14 +208,18 @@ var Heartbeat = class {
       const data = await res.json();
       const localDailyUsed = this.budgetStatus.daily_used;
       const localMonthlyUsed = this.budgetStatus.monthly_used;
+      const serverDailyUsed = Number(data.daily_used) || 0;
+      const serverMonthlyUsed = Number(data.monthly_used) || 0;
+      const serverDailyLimit = data.daily_limit != null ? Number(data.daily_limit) : null;
+      const serverMonthlyLimit = data.monthly_limit != null ? Number(data.monthly_limit) : null;
       this.budgetStatus = {
         ...data,
         // Use whichever spend is higher — server or local tracking
-        daily_used: Math.max(data.daily_used ?? 0, localDailyUsed),
-        monthly_used: Math.max(data.monthly_used ?? 0, localMonthlyUsed),
-        // Preserve local limits if server doesn't provide them
-        daily_limit: data.daily_limit ?? this.localDailyLimit,
-        monthly_limit: data.monthly_limit ?? this.localMonthlyLimit
+        daily_used: Math.max(serverDailyUsed, localDailyUsed),
+        monthly_used: Math.max(serverMonthlyUsed, localMonthlyUsed),
+        // Use the stricter (lower) limit — local config takes priority if lower
+        daily_limit: this.pickStricterLimit(serverDailyLimit, this.localDailyLimit),
+        monthly_limit: this.pickStricterLimit(serverMonthlyLimit, this.localMonthlyLimit)
       };
       this.consecutiveFailures = 0;
       const newStatus = data.kill_switch_active ? "OFF" : data.status;
@@ -200,6 +236,22 @@ var Heartbeat = class {
       }
     }
   }
+  /**
+   * Pick the stricter (lower) of two limits.
+   * If one is null, use the other.
+   */
+  pickStricterLimit(a, b) {
+    if (a === null) return b;
+    if (b === null) return a;
+    return Math.min(a, b);
+  }
+  /**
+   * Force an immediate heartbeat poll (useful for kill switch checks).
+   * Returns a promise that resolves when the poll completes.
+   */
+  async forcePoll() {
+    await this.beat();
+  }
   /**
    * Update local budget tracking (called after each request).
    * This provides real-time budget awareness between heartbeats.
@@ -362,18 +414,98 @@ function wrapAnthropic(client, config, shipper, heartbeat) {
               });
             }
           }
-          if (config.mode === "cost_protect") {
-            if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
-              blocked = true;
-              enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
-              const blockError = {
-                code: "BUDGET_EXCEEDED",
-                message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
-                budget_used: heartbeat.budgetStatus.monthly_used,
-                budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                retry_after: getNextResetTime(enforcementReason),
-                dashboard_url: dashboardUrl
-              };
+          const release = await heartbeat.budgetMutex.acquire();
+          try {
+            if (config.mode === "cost_protect") {
+              if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
+                blocked = true;
+                enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
+                const blockError = {
+                  code: "BUDGET_EXCEEDED",
+                  message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
+                  budget_used: heartbeat.budgetStatus.monthly_used,
+                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                  retry_after: getNextResetTime(enforcementReason),
+                  dashboard_url: dashboardUrl
+                };
+                shipper.push({
+                  id: generateId(),
+                  timestamp: startTime,
+                  provider: "anthropic",
+                  model,
+                  input_tokens: 0,
+                  output_tokens: 0,
+                  cost: 0,
+                  latency_ms: Date.now() - startTime,
+                  endpoint_tag: config.endpoint_tag,
+                  downgraded: false,
+                  blocked: true,
+                  enforcement_reason: enforcementReason
+                });
+                throw Object.assign(new Error(blockError.message), {
+                  caplyr: blockError
+                });
+              }
+              if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
+                const fallback = config.fallback ?? getDefaultFallback(model);
+                if (fallback && fallback !== model) {
+                  originalModel = model;
+                  model = fallback;
+                  downgraded = true;
+                  enforcementReason = "auto_downgrade_threshold";
+                  config.onEnforcement?.({
+                    type: "downgrade",
+                    timestamp: Date.now(),
+                    reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
+                    original_model: originalModel,
+                    fallback_model: model,
+                    budget_used: heartbeat.budgetStatus.monthly_used,
+                    budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                    estimated_savings: 0
+                    // Calculated after response
+                  });
+                }
+              }
+            }
+            const requestParams = downgraded ? { ...params, model } : params;
+            try {
+              const response = await target.create.call(
+                target,
+                requestParams,
+                options
+              );
+              const latency = Date.now() - startTime;
+              const inputTokens = response?.usage?.input_tokens ?? 0;
+              const outputTokens = response?.usage?.output_tokens ?? 0;
+              const cost = calculateCost(model, inputTokens, outputTokens);
+              heartbeat.trackSpend(cost);
+              let estimatedSavings = 0;
+              if (downgraded && originalModel) {
+                const originalCost = calculateCost(
+                  originalModel,
+                  inputTokens,
+                  outputTokens
+                );
+                estimatedSavings = originalCost - cost;
+              }
+              shipper.push({
+                id: generateId(),
+                timestamp: startTime,
+                provider: "anthropic",
+                model,
+                input_tokens: inputTokens,
+                output_tokens: outputTokens,
+                cost,
+                latency_ms: latency,
+                endpoint_tag: config.endpoint_tag,
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: enforcementReason
+              });
+              return response;
+            } catch (err) {
+              if (err?.caplyr) throw err;
               shipper.push({
                 id: generateId(),
                 timestamp: startTime,
@@ -384,90 +516,15 @@ function wrapAnthropic(client, config, shipper, heartbeat) {
                 cost: 0,
                 latency_ms: Date.now() - startTime,
                 endpoint_tag: config.endpoint_tag,
-                downgraded: false,
-                blocked: true,
-                enforcement_reason: enforcementReason
-              });
-              throw Object.assign(new Error(blockError.message), {
-                caplyr: blockError
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: "provider_error"
               });
+              throw err;
             }
-            if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
-              const fallback = config.fallback ?? getDefaultFallback(model);
-              if (fallback && fallback !== model) {
-                originalModel = model;
-                model = fallback;
-                downgraded = true;
-                enforcementReason = "auto_downgrade_threshold";
-                config.onEnforcement?.({
-                  type: "downgrade",
-                  timestamp: Date.now(),
-                  reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
-                  original_model: originalModel,
-                  fallback_model: model,
-                  budget_used: heartbeat.budgetStatus.monthly_used,
-                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                  estimated_savings: 0
-                  // Calculated after response
-                });
-              }
-            }
-          }
-          const requestParams = downgraded ? { ...params, model } : params;
-          try {
-            const response = await target.create.call(
-              target,
-              requestParams,
-              options
-            );
-            const latency = Date.now() - startTime;
-            const inputTokens = response?.usage?.input_tokens ?? 0;
-            const outputTokens = response?.usage?.output_tokens ?? 0;
-            const cost = calculateCost(model, inputTokens, outputTokens);
-            heartbeat.trackSpend(cost);
-            let estimatedSavings = 0;
-            if (downgraded && originalModel) {
-              const originalCost = calculateCost(
-                originalModel,
-                inputTokens,
-                outputTokens
-              );
-              estimatedSavings = originalCost - cost;
-            }
-            shipper.push({
-              id: generateId(),
-              timestamp: startTime,
-              provider: "anthropic",
-              model,
-              input_tokens: inputTokens,
-              output_tokens: outputTokens,
-              cost,
-              latency_ms: latency,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: enforcementReason
-            });
-            return response;
-          } catch (err) {
-            if (err?.caplyr) throw err;
-            shipper.push({
-              id: generateId(),
-              timestamp: startTime,
-              provider: "anthropic",
-              model,
-              input_tokens: 0,
-              output_tokens: 0,
-              cost: 0,
-              latency_ms: Date.now() - startTime,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: "provider_error"
-            });
-            throw err;
+          } finally {
+            release();
           }
         };
       }
@@ -544,18 +601,89 @@ function wrapOpenAI(client, config, shipper, heartbeat) {
               });
             }
           }
-          if (config.mode === "cost_protect") {
-            if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
-              blocked = true;
-              enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
-              const blockError = {
-                code: "BUDGET_EXCEEDED",
-                message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
-                budget_used: heartbeat.budgetStatus.monthly_used,
-                budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                retry_after: getNextResetTime2(enforcementReason),
-                dashboard_url: dashboardUrl
-              };
+          const release = await heartbeat.budgetMutex.acquire();
+          try {
+            if (config.mode === "cost_protect") {
+              if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
+                blocked = true;
+                enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
+                const blockError = {
+                  code: "BUDGET_EXCEEDED",
+                  message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
+                  budget_used: heartbeat.budgetStatus.monthly_used,
+                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                  retry_after: getNextResetTime2(enforcementReason),
+                  dashboard_url: dashboardUrl
+                };
+                shipper.push({
+                  id: generateId2(),
+                  timestamp: startTime,
+                  provider: "openai",
+                  model,
+                  input_tokens: 0,
+                  output_tokens: 0,
+                  cost: 0,
+                  latency_ms: Date.now() - startTime,
+                  endpoint_tag: config.endpoint_tag,
+                  downgraded: false,
+                  blocked: true,
+                  enforcement_reason: enforcementReason
+                });
+                throw Object.assign(new Error(blockError.message), {
+                  caplyr: blockError
+                });
+              }
+              if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
+                const fallback = config.fallback ?? getDefaultFallback(model);
+                if (fallback && fallback !== model) {
+                  originalModel = model;
+                  model = fallback;
+                  downgraded = true;
+                  enforcementReason = "auto_downgrade_threshold";
+                  config.onEnforcement?.({
+                    type: "downgrade",
+                    timestamp: Date.now(),
+                    reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
+                    original_model: originalModel,
+                    fallback_model: model,
+                    budget_used: heartbeat.budgetStatus.monthly_used,
+                    budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                    estimated_savings: 0
+                  });
+                }
+              }
+            }
+            const requestParams = downgraded ? { ...params, model } : params;
+            try {
+              const response = await target.create.call(
+                target,
+                requestParams,
+                options
+              );
+              const latency = Date.now() - startTime;
+              const usage = response?.usage;
+              const inputTokens = usage?.prompt_tokens ?? 0;
+              const outputTokens = usage?.completion_tokens ?? 0;
+              const cost = calculateCost(model, inputTokens, outputTokens);
+              heartbeat.trackSpend(cost);
+              shipper.push({
+                id: generateId2(),
+                timestamp: startTime,
+                provider: "openai",
+                model,
+                input_tokens: inputTokens,
+                output_tokens: outputTokens,
+                cost,
+                latency_ms: latency,
+                endpoint_tag: config.endpoint_tag,
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: enforcementReason
+              });
+              return response;
+            } catch (err) {
+              if (err?.caplyr) throw err;
               shipper.push({
                 id: generateId2(),
                 timestamp: startTime,
@@ -566,81 +694,15 @@ function wrapOpenAI(client, config, shipper, heartbeat) {
                 cost: 0,
                 latency_ms: Date.now() - startTime,
                 endpoint_tag: config.endpoint_tag,
-                downgraded: false,
-                blocked: true,
-                enforcement_reason: enforcementReason
-              });
-              throw Object.assign(new Error(blockError.message), {
-                caplyr: blockError
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: "provider_error"
               });
+              throw err;
             }
-            if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
-              const fallback = config.fallback ?? getDefaultFallback(model);
-              if (fallback && fallback !== model) {
-                originalModel = model;
-                model = fallback;
-                downgraded = true;
-                enforcementReason = "auto_downgrade_threshold";
-                config.onEnforcement?.({
-                  type: "downgrade",
-                  timestamp: Date.now(),
-                  reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
-                  original_model: originalModel,
-                  fallback_model: model,
-                  budget_used: heartbeat.budgetStatus.monthly_used,
-                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                  estimated_savings: 0
-                });
-              }
-            }
-          }
-          const requestParams = downgraded ? { ...params, model } : params;
-          try {
-            const response = await target.create.call(
-              target,
-              requestParams,
-              options
-            );
-            const latency = Date.now() - startTime;
-            const usage = response?.usage;
-            const inputTokens = usage?.prompt_tokens ?? 0;
-            const outputTokens = usage?.completion_tokens ?? 0;
-            const cost = calculateCost(model, inputTokens, outputTokens);
-            heartbeat.trackSpend(cost);
-            shipper.push({
-              id: generateId2(),
-              timestamp: startTime,
-              provider: "openai",
-              model,
-              input_tokens: inputTokens,
-              output_tokens: outputTokens,
-              cost,
-              latency_ms: latency,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: enforcementReason
-            });
-            return response;
-          } catch (err) {
-            if (err?.caplyr) throw err;
-            shipper.push({
-              id: generateId2(),
-              timestamp: startTime,
-              provider: "openai",
-              model,
-              input_tokens: 0,
-              output_tokens: 0,
-              cost: 0,
-              latency_ms: Date.now() - startTime,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: "provider_error"
-            });
-            throw err;
+          } finally {
+            release();
           }
         };
       }

package/dist/index.mjs

@@ -74,6 +74,36 @@ var LogShipper = class {
   }
 };
 
+// src/mutex.ts
+var Mutex = class {
+  constructor() {
+    this.queue = [];
+    this.locked = false;
+  }
+  async acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return this.createRelease();
+    }
+    return new Promise((resolve) => {
+      this.queue.push(() => resolve(this.createRelease()));
+    });
+  }
+  createRelease() {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const next = this.queue.shift();
+      if (next) {
+        next();
+      } else {
+        this.locked = false;
+      }
+    };
+  }
+};
+
 // src/heartbeat.ts
 var Heartbeat = class {
   constructor(config) {
@@ -91,6 +121,8 @@ var Heartbeat = class {
     };
     /** Current protection status */
     this.status = "ACTIVE";
+    /** Mutex for serializing budget check → API call → trackSpend */
+    this.budgetMutex = new Mutex();
     /** Local budget limits set via config (not from server) */
     this.localDailyLimit = null;
     this.localMonthlyLimit = null;
@@ -143,14 +175,18 @@ var Heartbeat = class {
       const data = await res.json();
       const localDailyUsed = this.budgetStatus.daily_used;
       const localMonthlyUsed = this.budgetStatus.monthly_used;
+      const serverDailyUsed = Number(data.daily_used) || 0;
+      const serverMonthlyUsed = Number(data.monthly_used) || 0;
+      const serverDailyLimit = data.daily_limit != null ? Number(data.daily_limit) : null;
+      const serverMonthlyLimit = data.monthly_limit != null ? Number(data.monthly_limit) : null;
       this.budgetStatus = {
         ...data,
         // Use whichever spend is higher — server or local tracking
-        daily_used: Math.max(data.daily_used ?? 0, localDailyUsed),
-        monthly_used: Math.max(data.monthly_used ?? 0, localMonthlyUsed),
-        // Preserve local limits if server doesn't provide them
-        daily_limit: data.daily_limit ?? this.localDailyLimit,
-        monthly_limit: data.monthly_limit ?? this.localMonthlyLimit
+        daily_used: Math.max(serverDailyUsed, localDailyUsed),
+        monthly_used: Math.max(serverMonthlyUsed, localMonthlyUsed),
+        // Use the stricter (lower) limit — local config takes priority if lower
+        daily_limit: this.pickStricterLimit(serverDailyLimit, this.localDailyLimit),
+        monthly_limit: this.pickStricterLimit(serverMonthlyLimit, this.localMonthlyLimit)
       };
       this.consecutiveFailures = 0;
       const newStatus = data.kill_switch_active ? "OFF" : data.status;
@@ -167,6 +203,22 @@ var Heartbeat = class {
       }
     }
   }
+  /**
+   * Pick the stricter (lower) of two limits.
+   * If one is null, use the other.
+   */
+  pickStricterLimit(a, b) {
+    if (a === null) return b;
+    if (b === null) return a;
+    return Math.min(a, b);
+  }
+  /**
+   * Force an immediate heartbeat poll (useful for kill switch checks).
+   * Returns a promise that resolves when the poll completes.
+   */
+  async forcePoll() {
+    await this.beat();
+  }
   /**
    * Update local budget tracking (called after each request).
    * This provides real-time budget awareness between heartbeats.
@@ -329,18 +381,98 @@ function wrapAnthropic(client, config, shipper, heartbeat) {
               });
             }
           }
-          if (config.mode === "cost_protect") {
-            if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
-              blocked = true;
-              enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
-              const blockError = {
-                code: "BUDGET_EXCEEDED",
-                message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
-                budget_used: heartbeat.budgetStatus.monthly_used,
-                budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                retry_after: getNextResetTime(enforcementReason),
-                dashboard_url: dashboardUrl
-              };
+          const release = await heartbeat.budgetMutex.acquire();
+          try {
+            if (config.mode === "cost_protect") {
+              if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
+                blocked = true;
+                enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
+                const blockError = {
+                  code: "BUDGET_EXCEEDED",
+                  message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
+                  budget_used: heartbeat.budgetStatus.monthly_used,
+                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                  retry_after: getNextResetTime(enforcementReason),
+                  dashboard_url: dashboardUrl
+                };
+                shipper.push({
+                  id: generateId(),
+                  timestamp: startTime,
+                  provider: "anthropic",
+                  model,
+                  input_tokens: 0,
+                  output_tokens: 0,
+                  cost: 0,
+                  latency_ms: Date.now() - startTime,
+                  endpoint_tag: config.endpoint_tag,
+                  downgraded: false,
+                  blocked: true,
+                  enforcement_reason: enforcementReason
+                });
+                throw Object.assign(new Error(blockError.message), {
+                  caplyr: blockError
+                });
+              }
+              if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
+                const fallback = config.fallback ?? getDefaultFallback(model);
+                if (fallback && fallback !== model) {
+                  originalModel = model;
+                  model = fallback;
+                  downgraded = true;
+                  enforcementReason = "auto_downgrade_threshold";
+                  config.onEnforcement?.({
+                    type: "downgrade",
+                    timestamp: Date.now(),
+                    reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
+                    original_model: originalModel,
+                    fallback_model: model,
+                    budget_used: heartbeat.budgetStatus.monthly_used,
+                    budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                    estimated_savings: 0
+                    // Calculated after response
+                  });
+                }
+              }
+            }
+            const requestParams = downgraded ? { ...params, model } : params;
+            try {
+              const response = await target.create.call(
+                target,
+                requestParams,
+                options
+              );
+              const latency = Date.now() - startTime;
+              const inputTokens = response?.usage?.input_tokens ?? 0;
+              const outputTokens = response?.usage?.output_tokens ?? 0;
+              const cost = calculateCost(model, inputTokens, outputTokens);
+              heartbeat.trackSpend(cost);
+              let estimatedSavings = 0;
+              if (downgraded && originalModel) {
+                const originalCost = calculateCost(
+                  originalModel,
+                  inputTokens,
+                  outputTokens
+                );
+                estimatedSavings = originalCost - cost;
+              }
+              shipper.push({
+                id: generateId(),
+                timestamp: startTime,
+                provider: "anthropic",
+                model,
+                input_tokens: inputTokens,
+                output_tokens: outputTokens,
+                cost,
+                latency_ms: latency,
+                endpoint_tag: config.endpoint_tag,
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: enforcementReason
+              });
+              return response;
+            } catch (err) {
+              if (err?.caplyr) throw err;
               shipper.push({
                 id: generateId(),
                 timestamp: startTime,
@@ -351,90 +483,15 @@ function wrapAnthropic(client, config, shipper, heartbeat) {
                 cost: 0,
                 latency_ms: Date.now() - startTime,
                 endpoint_tag: config.endpoint_tag,
-                downgraded: false,
-                blocked: true,
-                enforcement_reason: enforcementReason
-              });
-              throw Object.assign(new Error(blockError.message), {
-                caplyr: blockError
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: "provider_error"
               });
+              throw err;
             }
-            if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
-              const fallback = config.fallback ?? getDefaultFallback(model);
-              if (fallback && fallback !== model) {
-                originalModel = model;
-                model = fallback;
-                downgraded = true;
-                enforcementReason = "auto_downgrade_threshold";
-                config.onEnforcement?.({
-                  type: "downgrade",
-                  timestamp: Date.now(),
-                  reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
-                  original_model: originalModel,
-                  fallback_model: model,
-                  budget_used: heartbeat.budgetStatus.monthly_used,
-                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                  estimated_savings: 0
-                  // Calculated after response
-                });
-              }
-            }
-          }
-          const requestParams = downgraded ? { ...params, model } : params;
-          try {
-            const response = await target.create.call(
-              target,
-              requestParams,
-              options
-            );
-            const latency = Date.now() - startTime;
-            const inputTokens = response?.usage?.input_tokens ?? 0;
-            const outputTokens = response?.usage?.output_tokens ?? 0;
-            const cost = calculateCost(model, inputTokens, outputTokens);
-            heartbeat.trackSpend(cost);
-            let estimatedSavings = 0;
-            if (downgraded && originalModel) {
-              const originalCost = calculateCost(
-                originalModel,
-                inputTokens,
-                outputTokens
-              );
-              estimatedSavings = originalCost - cost;
-            }
-            shipper.push({
-              id: generateId(),
-              timestamp: startTime,
-              provider: "anthropic",
-              model,
-              input_tokens: inputTokens,
-              output_tokens: outputTokens,
-              cost,
-              latency_ms: latency,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: enforcementReason
-            });
-            return response;
-          } catch (err) {
-            if (err?.caplyr) throw err;
-            shipper.push({
-              id: generateId(),
-              timestamp: startTime,
-              provider: "anthropic",
-              model,
-              input_tokens: 0,
-              output_tokens: 0,
-              cost: 0,
-              latency_ms: Date.now() - startTime,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: "provider_error"
-            });
-            throw err;
+          } finally {
+            release();
           }
         };
       }
@@ -511,18 +568,89 @@ function wrapOpenAI(client, config, shipper, heartbeat) {
               });
             }
           }
-          if (config.mode === "cost_protect") {
-            if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
-              blocked = true;
-              enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
-              const blockError = {
-                code: "BUDGET_EXCEEDED",
-                message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
-                budget_used: heartbeat.budgetStatus.monthly_used,
-                budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                retry_after: getNextResetTime2(enforcementReason),
-                dashboard_url: dashboardUrl
-              };
+          const release = await heartbeat.budgetMutex.acquire();
+          try {
+            if (config.mode === "cost_protect") {
+              if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
+                blocked = true;
+                enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
+                const blockError = {
+                  code: "BUDGET_EXCEEDED",
+                  message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
+                  budget_used: heartbeat.budgetStatus.monthly_used,
+                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                  retry_after: getNextResetTime2(enforcementReason),
+                  dashboard_url: dashboardUrl
+                };
+                shipper.push({
+                  id: generateId2(),
+                  timestamp: startTime,
+                  provider: "openai",
+                  model,
+                  input_tokens: 0,
+                  output_tokens: 0,
+                  cost: 0,
+                  latency_ms: Date.now() - startTime,
+                  endpoint_tag: config.endpoint_tag,
+                  downgraded: false,
+                  blocked: true,
+                  enforcement_reason: enforcementReason
+                });
+                throw Object.assign(new Error(blockError.message), {
+                  caplyr: blockError
+                });
+              }
+              if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
+                const fallback = config.fallback ?? getDefaultFallback(model);
+                if (fallback && fallback !== model) {
+                  originalModel = model;
+                  model = fallback;
+                  downgraded = true;
+                  enforcementReason = "auto_downgrade_threshold";
+                  config.onEnforcement?.({
+                    type: "downgrade",
+                    timestamp: Date.now(),
+                    reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
+                    original_model: originalModel,
+                    fallback_model: model,
+                    budget_used: heartbeat.budgetStatus.monthly_used,
+                    budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                    estimated_savings: 0
+                  });
+                }
+              }
+            }
+            const requestParams = downgraded ? { ...params, model } : params;
+            try {
+              const response = await target.create.call(
+                target,
+                requestParams,
+                options
+              );
+              const latency = Date.now() - startTime;
+              const usage = response?.usage;
+              const inputTokens = usage?.prompt_tokens ?? 0;
+              const outputTokens = usage?.completion_tokens ?? 0;
+              const cost = calculateCost(model, inputTokens, outputTokens);
+              heartbeat.trackSpend(cost);
+              shipper.push({
+                id: generateId2(),
+                timestamp: startTime,
+                provider: "openai",
+                model,
+                input_tokens: inputTokens,
+                output_tokens: outputTokens,
+                cost,
+                latency_ms: latency,
+                endpoint_tag: config.endpoint_tag,
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: enforcementReason
+              });
+              return response;
+            } catch (err) {
+              if (err?.caplyr) throw err;
               shipper.push({
                 id: generateId2(),
                 timestamp: startTime,
@@ -533,81 +661,15 @@ function wrapOpenAI(client, config, shipper, heartbeat) {
                 cost: 0,
                 latency_ms: Date.now() - startTime,
                 endpoint_tag: config.endpoint_tag,
-                downgraded: false,
-                blocked: true,
-                enforcement_reason: enforcementReason
-              });
-              throw Object.assign(new Error(blockError.message), {
-                caplyr: blockError
+                downgraded,
+                original_model: originalModel,
+                blocked: false,
+                enforcement_reason: "provider_error"
               });
+              throw err;
             }
-            if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
-              const fallback = config.fallback ?? getDefaultFallback(model);
-              if (fallback && fallback !== model) {
-                originalModel = model;
-                model = fallback;
-                downgraded = true;
-                enforcementReason = "auto_downgrade_threshold";
-                config.onEnforcement?.({
-                  type: "downgrade",
-                  timestamp: Date.now(),
-                  reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
-                  original_model: originalModel,
-                  fallback_model: model,
-                  budget_used: heartbeat.budgetStatus.monthly_used,
-                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
-                  estimated_savings: 0
-                });
-              }
-            }
-          }
-          const requestParams = downgraded ? { ...params, model } : params;
-          try {
-            const response = await target.create.call(
-              target,
-              requestParams,
-              options
-            );
-            const latency = Date.now() - startTime;
-            const usage = response?.usage;
-            const inputTokens = usage?.prompt_tokens ?? 0;
-            const outputTokens = usage?.completion_tokens ?? 0;
-            const cost = calculateCost(model, inputTokens, outputTokens);
-            heartbeat.trackSpend(cost);
-            shipper.push({
-              id: generateId2(),
-              timestamp: startTime,
-              provider: "openai",
-              model,
-              input_tokens: inputTokens,
-              output_tokens: outputTokens,
-              cost,
-              latency_ms: latency,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: enforcementReason
-            });
-            return response;
-          } catch (err) {
-            if (err?.caplyr) throw err;
-            shipper.push({
-              id: generateId2(),
-              timestamp: startTime,
-              provider: "openai",
-              model,
-              input_tokens: 0,
-              output_tokens: 0,
-              cost: 0,
-              latency_ms: Date.now() - startTime,
-              endpoint_tag: config.endpoint_tag,
-              downgraded,
-              original_model: originalModel,
-              blocked: false,
-              enforcement_reason: "provider_error"
-            });
-            throw err;
+          } finally {
+            release();
           }
         };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caplyr",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "AI Cost Control Plane — budget guardrails, auto-downgrade, and kill switch for AI API calls",
   "main": "dist/index.js",
   "module": "dist/index.mjs",