@axlsdk/axl 0.17.9 → 0.18.0

package/dist/index.js

@@ -142,27 +142,180 @@ function sleep2(ms, signal) {
     );
   });
 }
-async function fetchWithRetry(input, init, maxRetries = MAX_RETRIES) {
-  for (let attempt = 0; ; attempt++) {
-    const res = await fetch(input, init);
-    if (res.ok || !RETRYABLE_STATUS_CODES.has(res.status) || attempt >= maxRetries) {
-      return res;
-    }
-    if (init?.signal?.aborted) {
-      return res;
-    }
-    const retryAfter = res.headers.get("retry-after");
-    let delay;
-    if (retryAfter && !isNaN(Number(retryAfter))) {
-      delay = Number(retryAfter) * 1e3;
-    } else {
-      delay = BASE_DELAY_MS * 2 ** attempt;
+async function fetchWithRetry(input, init, opts) {
+  const maxRetries = opts?.maxRetries ?? MAX_RETRIES;
+  const governor = opts?.governor;
+  let acquired = false;
+  if (governor) {
+    await governor.acquire(init?.signal ?? void 0);
+    acquired = true;
+  }
+  try {
+    for (let attempt = 0; ; attempt++) {
+      const res = await fetch(input, init);
+      governor?.observe(res);
+      if (res.ok || !RETRYABLE_STATUS_CODES.has(res.status) || attempt >= maxRetries) {
+        return res;
+      }
+      if (init?.signal?.aborted) {
+        return res;
+      }
+      const retryAfter = res.headers.get("retry-after");
+      let delay;
+      if (retryAfter && !isNaN(Number(retryAfter))) {
+        delay = Number(retryAfter) * 1e3;
+      } else {
+        delay = BASE_DELAY_MS * 2 ** attempt;
+      }
+      delay *= 0.75 + Math.random() * 0.5;
+      await sleep2(delay, init?.signal ?? void 0);
     }
-    delay *= 0.75 + Math.random() * 0.5;
-    await sleep2(delay, init?.signal ?? void 0);
+  } finally {
+    if (acquired) governor.release();
   }
 }
 
+// src/providers/rate-limiter.ts
+function abortError() {
+  return Object.assign(new Error("The operation was aborted"), { name: "AbortError" });
+}
+var RateLimiter = class {
+  maxConcurrent;
+  minIntervalMs;
+  acquireTimeoutMs;
+  active = 0;
+  // `-Infinity` (not 0) so the FIRST grant is always immediate regardless of the
+  // wall clock: `Date.now() - (-Infinity) === Infinity`, which always satisfies
+  // `minIntervalMs`. Initializing to 0 would (only under a mocked/near-zero clock)
+  // wrongly delay the first grant by a full interval, since the limiter has never
+  // actually granted anything yet.
+  lastGrantAt = Number.NEGATIVE_INFINITY;
+  queue = [];
+  spacingTimer;
+  warnedQueued = false;
+  constructor(config = {}) {
+    const mc = config.maxConcurrent;
+    if (mc == null) {
+      this.maxConcurrent = Infinity;
+    } else if (!Number.isFinite(mc) || mc < 1) {
+      console.warn(
+        `[axl] RateLimiter: ignoring invalid maxConcurrent (${mc}); expected an integer >= 1. No concurrency cap applied.`
+      );
+      this.maxConcurrent = Infinity;
+    } else {
+      this.maxConcurrent = Math.floor(mc);
+      if (this.maxConcurrent < 2) {
+        console.warn(
+          `[axl] RateLimiter: maxConcurrent=${this.maxConcurrent} serializes every request to this provider. Nested same-provider calls still complete (permits aren't held across a nested ask), but throughput is a floor, not a guarantee.`
+        );
+      }
+    }
+    this.minIntervalMs = config.minIntervalMs != null && Number.isFinite(config.minIntervalMs) && config.minIntervalMs > 0 ? config.minIntervalMs : 0;
+    this.acquireTimeoutMs = config.acquireTimeoutMs != null && Number.isFinite(config.acquireTimeoutMs) && config.acquireTimeoutMs > 0 ? config.acquireTimeoutMs : void 0;
+  }
+  /**
+   * Acquire a permit. Resolves when one is granted (respecting `maxConcurrent`
+   * and `minIntervalMs`). The caller MUST pair every resolved `acquire()` with
+   * exactly one {@link release}.
+   *
+   * Abort handling:
+   * - Pre-aborted signal ⇒ rejects immediately, no permit taken.
+   * - Aborted while queued ⇒ spliced out of the queue, no counter change, rejects.
+   * - (Once granted, the abort listener is removed — the holder owns the permit
+   *   and releases it via `fetchWithRetry`'s `finally`.)
+   *
+   * With `acquireTimeoutMs`, a waiter that sits in the queue too long rejects.
+   */
+  acquire(signal) {
+    if (signal?.aborted) return Promise.reject(abortError());
+    return new Promise((resolve2, reject) => {
+      const waiter = { resolve: resolve2, reject, signal };
+      if (signal) {
+        waiter.onAbort = () => this.settleWaiter(waiter, abortError());
+        signal.addEventListener("abort", waiter.onAbort, { once: true });
+      }
+      if (this.acquireTimeoutMs != null) {
+        waiter.timer = setTimeout(
+          () => this.settleWaiter(
+            waiter,
+            new Error(`RateLimiter.acquire timed out after ${this.acquireTimeoutMs}ms`)
+          ),
+          this.acquireTimeoutMs
+        );
+      }
+      this.queue.push(waiter);
+      this.pump();
+      if (!waiter.granted && !this.warnedQueued) {
+        this.warnedQueued = true;
+        console.warn(
+          `[axl] RateLimiter: request queued (maxConcurrent=${this.maxConcurrent}${this.minIntervalMs ? `, minIntervalMs=${this.minIntervalMs}` : ""}). This is expected backpressure; lower fan-out or raise the cap if throughput suffers.`
+        );
+      }
+    });
+  }
+  /** Release a previously acquired permit and wake the next waiter. */
+  release() {
+    if (this.active === 0) {
+      console.warn(
+        "[axl] RateLimiter.release() called with no active permits \u2014 likely a double-release bug."
+      );
+      return;
+    }
+    this.active--;
+    this.pump();
+  }
+  /** v1 no-op seam for a future adaptive (rate-limit-header-driven) pacing follow-up. */
+  observe(_res) {
+  }
+  /** Drain the queue: grant head waiters while a permit is free and spacing allows. */
+  pump() {
+    while (this.queue.length > 0 && this.active < this.maxConcurrent) {
+      if (this.minIntervalMs > 0) {
+        const waitMs = this.minIntervalMs - (Date.now() - this.lastGrantAt);
+        if (waitMs > 0) {
+          if (!this.spacingTimer) {
+            this.spacingTimer = setTimeout(() => {
+              this.spacingTimer = void 0;
+              this.pump();
+            }, waitMs);
+          }
+          return;
+        }
+      }
+      const waiter = this.queue.shift();
+      this.grant(waiter);
+    }
+  }
+  grant(waiter) {
+    waiter.settled = true;
+    waiter.granted = true;
+    this.active++;
+    this.lastGrantAt = Date.now();
+    this.clearWaiterTimers(waiter);
+    waiter.resolve();
+  }
+  /** Reject a still-queued waiter (abort or timeout) and remove it cleanly. */
+  settleWaiter(waiter, err) {
+    if (waiter.settled) return;
+    waiter.settled = true;
+    const idx = this.queue.indexOf(waiter);
+    if (idx !== -1) this.queue.splice(idx, 1);
+    this.clearWaiterTimers(waiter);
+    waiter.reject(err);
+    this.pump();
+  }
+  clearWaiterTimers(waiter) {
+    if (waiter.timer) {
+      clearTimeout(waiter.timer);
+      waiter.timer = void 0;
+    }
+    if (waiter.signal && waiter.onAbort) {
+      waiter.signal.removeEventListener("abort", waiter.onAbort);
+      waiter.onAbort = void 0;
+    }
+  }
+};
+
 // src/providers/openai.ts
 var OPENAI_PRICING = {
   // gpt-4o era — cache reads at 50% of input rate
@@ -190,7 +343,10 @@ var OPENAI_PRICING = {
   "gpt-5.2": [175e-8, 14e-6, 0.1],
   "gpt-5.3": [175e-8, 14e-6, 0.1],
   "gpt-5.4": [25e-7, 15e-6, 0.1],
-  "gpt-5.4-pro": [3e-5, 18e-5, 0.1]
+  "gpt-5.4-pro": [3e-5, 18e-5, 0.1],
+  // gpt-5.5 era (flagship released 2026-04) — cache reads at 10% of input rate
+  "gpt-5.5": [5e-6, 3e-5, 0.1],
+  "gpt-5.5-pro": [3e-5, 18e-5, 0.1]
 };
 var PRICING_KEYS_BY_LENGTH = Object.keys(OPENAI_PRICING).sort((a, b) => b.length - a.length);
 function estimateOpenAICost(model, promptTokens, completionTokens, cachedTokens) {
@@ -239,9 +395,11 @@ var OpenAIProvider = class {
   name = "openai";
   baseUrl;
   apiKey;
+  governor;
   constructor(options = {}) {
     this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     if (!this.apiKey) {
       throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.");
     }
@@ -251,15 +409,19 @@ var OpenAIProvider = class {
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
     const body = this.buildRequestBody(messages, options, false);
-    const res = await fetchWithRetry(`${this.baseUrl}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/chat/completions`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(body),
+        signal: options.signal
       },
-      body: JSON.stringify(body),
-      signal: options.signal
-    });
+      { governor: this.governor }
+    );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
@@ -299,15 +461,19 @@ var OpenAIProvider = class {
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
     const body = this.buildRequestBody(messages, options, true);
-    const res = await fetchWithRetry(`${this.baseUrl}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/chat/completions`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(body),
+        signal: options.signal
       },
-      body: JSON.stringify(body),
-      signal: options.signal
-    });
+      { governor: this.governor }
+    );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
@@ -480,9 +646,11 @@ var OpenAIResponsesProvider = class {
   name = "openai-responses";
   baseUrl;
   apiKey;
+  governor;
   constructor(options = {}) {
     this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     if (!this.apiKey) {
       throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.");
     }
@@ -492,15 +660,19 @@ var OpenAIResponsesProvider = class {
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
     const body = this.buildRequestBody(messages, options, false);
-    const res = await fetchWithRetry(`${this.baseUrl}/responses`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/responses`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(body),
+        signal: options.signal
       },
-      body: JSON.stringify(body),
-      signal: options.signal
-    });
+      { governor: this.governor }
+    );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
@@ -514,15 +686,19 @@ var OpenAIResponsesProvider = class {
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
     const body = this.buildRequestBody(messages, options, true);
-    const res = await fetchWithRetry(`${this.baseUrl}/responses`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/responses`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(body),
+        signal: options.signal
       },
-      body: JSON.stringify(body),
-      signal: options.signal
-    });
+      { governor: this.governor }
+    );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
@@ -839,6 +1015,7 @@ var OpenAIResponsesProvider = class {
 // src/providers/anthropic.ts
 var ANTHROPIC_API_VERSION = "2023-06-01";
 var ANTHROPIC_PRICING = {
+  "claude-opus-4-8": [5e-6, 25e-6],
   "claude-opus-4-7": [5e-6, 25e-6],
   "claude-opus-4-6": [5e-6, 25e-6],
   "claude-sonnet-4-6": [3e-6, 15e-6],
@@ -884,16 +1061,16 @@ var THINKING_BUDGETS = {
   max: 3e4
 };
 function supportsAdaptiveThinking(model) {
-  return model.startsWith("claude-opus-4-7") || model.startsWith("claude-opus-4-6") || model.startsWith("claude-sonnet-4-6");
+  return model.startsWith("claude-opus-4-8") || model.startsWith("claude-opus-4-7") || model.startsWith("claude-opus-4-6") || model.startsWith("claude-sonnet-4-6");
 }
 function supportsMaxEffort(model) {
-  return model.startsWith("claude-opus-4-7") || model.startsWith("claude-opus-4-6");
+  return model.startsWith("claude-opus-4-8") || model.startsWith("claude-opus-4-7") || model.startsWith("claude-opus-4-6");
 }
 function supportsXhigh2(model) {
-  return model.startsWith("claude-opus-4-7");
+  return model.startsWith("claude-opus-4-8") || model.startsWith("claude-opus-4-7");
 }
 function supportsEffort(model) {
-  return model.startsWith("claude-opus-4-7") || model.startsWith("claude-opus-4-6") || model.startsWith("claude-sonnet-4-6") || model.startsWith("claude-opus-4-5");
+  return model.startsWith("claude-opus-4-8") || model.startsWith("claude-opus-4-7") || model.startsWith("claude-opus-4-6") || model.startsWith("claude-sonnet-4-6") || model.startsWith("claude-opus-4-5");
 }
 function clampAnthropicEffort(model, effort) {
   if (effort === "max" && !supportsMaxEffort(model)) return "high";
@@ -905,9 +1082,11 @@ var AnthropicProvider = class {
   baseUrl;
   apiKey;
   currentModel;
+  governor;
   constructor(options = {}) {
     this.apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? "https://api.anthropic.com/v1").replace(/\/$/, "");
+    this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     if (!this.apiKey) {
       throw new Error(
         "Anthropic API key is required. Set ANTHROPIC_API_KEY or pass apiKey in options."
@@ -920,12 +1099,16 @@ var AnthropicProvider = class {
   async chat(messages, options) {
     this.currentModel = options.model;
     const body = this.buildRequestBody(messages, options, false);
-    const res = await fetchWithRetry(`${this.baseUrl}/messages`, {
-      method: "POST",
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-      signal: options.signal
-    });
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/messages`,
+      {
+        method: "POST",
+        headers: this.buildHeaders(),
+        body: JSON.stringify(body),
+        signal: options.signal
+      },
+      { governor: this.governor }
+    );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
@@ -939,12 +1122,16 @@ var AnthropicProvider = class {
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
     const body = this.buildRequestBody(messages, options, true);
-    const res = await fetchWithRetry(`${this.baseUrl}/messages`, {
-      method: "POST",
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-      signal: options.signal
-    });
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/messages`,
+      {
+        method: "POST",
+        headers: this.buildHeaders(),
+        body: JSON.stringify(body),
+        signal: options.signal
+      },
+      { governor: this.governor }
+    );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
@@ -1431,12 +1618,14 @@ var GeminiProvider = class {
   baseUrl;
   apiKey;
   callCounter = 0;
+  governor;
   constructor(options = {}) {
     this.apiKey = options.apiKey ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta").replace(
       /\/$/,
       ""
     );
+    this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     if (!this.apiKey) {
       throw new Error("Google API key is required. Set GOOGLE_API_KEY or pass apiKey in options.");
     }
@@ -1446,12 +1635,16 @@ var GeminiProvider = class {
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
     const body = this.buildRequestBody(messages, options);
-    const res = await fetchWithRetry(`${this.baseUrl}/models/${options.model}:generateContent`, {
-      method: "POST",
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-      signal: options.signal
-    });
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/models/${options.model}:generateContent`,
+      {
+        method: "POST",
+        headers: this.buildHeaders(),
+        body: JSON.stringify(body),
+        signal: options.signal
+      },
+      { governor: this.governor }
+    );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
@@ -1472,7 +1665,8 @@ var GeminiProvider = class {
         headers: this.buildHeaders(),
         body: JSON.stringify(body),
         signal: options.signal
-      }
+      },
+      { governor: this.governor }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -1851,19 +2045,39 @@ var GeminiProvider = class {
 var builtinFactories = {
   openai: (config) => {
     const opts = config.providers?.openai ?? {};
-    return new OpenAIProvider({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+    return new OpenAIProvider({
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      rateLimit: opts.rateLimit
+    });
   },
+  // NB: each adapter builds its OWN RateLimiter from its config — caps are
+  // per-adapter-instance, not pooled. Configuring `openai` AND using both
+  // `openai:` and `openai-responses:` yields two independent governors against
+  // the same key (effective concurrency = the sum). Documented in providers.md.
   "openai-responses": (config) => {
     const opts = config.providers?.["openai-responses"] ?? config.providers?.openai ?? {};
-    return new OpenAIResponsesProvider({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+    return new OpenAIResponsesProvider({
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      rateLimit: opts.rateLimit
+    });
   },
   anthropic: (config) => {
     const opts = config.providers?.anthropic ?? {};
-    return new AnthropicProvider({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+    return new AnthropicProvider({
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      rateLimit: opts.rateLimit
+    });
   },
   google: (config) => {
     const opts = config.providers?.google ?? {};
-    return new GeminiProvider({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+    return new GeminiProvider({
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      rateLimit: opts.rateLimit
+    });
   }
 };
 var ProviderRegistry = class {
@@ -8596,14 +8810,11 @@ var AxlRuntime = class extends EventEmitter2 {
         captureTraces: options?.captureTraces
       });
     } else {
-      result = await this.eval(
-        entry.config,
-        {
-          onProgress: options?.onProgress,
-          signal: options?.signal,
-          captureTraces: options?.captureTraces
-        }
-      );
+      result = await this.eval(entry.config, {
+        onProgress: options?.onProgress,
+        signal: options?.signal,
+        captureTraces: options?.captureTraces
+      });
     }
     const resultObj = result;
     if (options?.metadata) {
@@ -10542,6 +10753,7 @@ export {
   QuorumNotMet,
   REDACTED,
   REDACTION_RULES,
+  RateLimiter,
   RedisStore,
   SQLiteStore,
   Session,