ag-common 0.0.910 → 0.0.912

package/dist/api/helpers/ai/adapters/google.js

@@ -45,6 +45,41 @@ const sortModelsByPreference = (models, prefer) => {
     return modelArray;
 };
 const getFetch = (dependencies) => dependencies?.fetch ?? globalThis.fetch;
+/**
+ * Extract an HTTP status from a generation failure. The SDK surfaces ApiError
+ * with `status` plus a JSON body in `message`; REST failures arrive as
+ * Response objects or status-carrying records, so probe all shapes.
+ */
+const generationFailureStatus = (error) => {
+    if (error instanceof Response)
+        return error.status;
+    if (typeof error !== "object" || error === null) {
+        return typeof error === "number" && Number.isInteger(error) ? error : undefined;
+    }
+    const record = error;
+    const candidates = [
+        record.status,
+        record.statusCode,
+        record.response?.status,
+        record.response?.statusCode,
+        record.error?.code,
+    ];
+    for (const candidate of candidates) {
+        const status = typeof candidate === "string" && /^\d+$/.test(candidate) ? Number(candidate) : candidate;
+        if (typeof status === "number" && Number.isInteger(status))
+            return status;
+    }
+    const nested = error.cause;
+    if (nested !== undefined && nested !== error)
+        return generationFailureStatus(nested);
+    const message = error instanceof Error ? error.message : undefined;
+    if (message !== undefined) {
+        const match = /"code"\s*:\s*(\d{3})/.exec(message) ?? /\bstatus\D{0,16}(\d{3})\b/i.exec(message);
+        if (match?.[1])
+            return Number(match[1]);
+    }
+    return undefined;
+};
 const createAbortError = () => {
     const error = new Error("Google AI request aborted");
     error.name = "AbortError";
@@ -338,6 +373,11 @@ const generateGoogle = async (request, config = {}) => {
     const effectiveRequest = { ...request, signal: controller.signal };
     try {
         const requestConfig = toRequestConfig(effectiveRequest);
+        const staggerMs = Math.max(0, request.staggerMs ?? 0);
+        const sleep = config.dependencies?.sleep ??
+            ((ms) => new Promise((resolve) => {
+                setTimeout(resolve, ms);
+            }));
         const result = await (0, retryOnError_1.retryOnError)(`generation:${request.ident ?? "unknown"}`, async () => {
             const combinations = await getCombinations(request.model, request.prefer, request.output, controller.signal, config);
             if (combinations.length === 0)
@@ -377,18 +417,19 @@ const generateGoogle = async (request, config = {}) => {
                 catch (error) {
                     if (controller.signal.aborted)
                         throw createAbortError();
-                    const status = error.status;
+                    const failureStatus = generationFailureStatus(error);
                     const message = error instanceof Error ? error.message : String(error);
-                    const rateLimited = status === 429 || (0, retryOnError_1.isOverloadedApiKeyError)(error);
-                    const unavailableModel = status === 404 && message.includes(selectedModel);
+                    const rateLimited = failureStatus === 429 || (0, retryOnError_1.isOverloadedApiKeyError)(error);
+                    const overloadedModel = failureStatus === 503 || failureStatus === 500 || failureStatus === 502;
+                    const unavailableModel = failureStatus === 404 && message.includes(selectedModel);
                     // Fallback only; per-model backoff below is keyed by rate limiting.
-                    if (rateLimited || unavailableModel) {
+                    if (rateLimited || overloadedModel || unavailableModel) {
                         (0, log_1.warn)("generation attempt failed; trying next available combination", {
                             model: selectedModel,
-                            status,
+                            status: failureStatus,
                         });
                         (0, apikey_1.blockKeyService)(key, `gemini-${selectedModel}`);
-                        if (rateLimited) {
+                        if (rateLimited || overloadedModel) {
                             (0, quota_1.recordModelRateLimit)(selectedModel, {
                                 cause: error,
                                 nowMs: config.dependencies?.now?.(),
@@ -401,7 +442,15 @@ const generateGoogle = async (request, config = {}) => {
                 }
             }
             throw lastFailure ?? new Error("No available model for this request");
-        }, 1, 5000, undefined, controller.signal);
+        }, {
+            retries: 1,
+            errorDelay: 5000,
+            initialDelayMs: staggerMs,
+            signal: controller.signal,
+            sleepFn: async (ms) => {
+                await sleep(ms);
+            },
+        });
         return result;
     }
     catch (error) {

package/dist/api/helpers/ai/client.js

@@ -114,6 +114,7 @@ const mergeRequest = (defaults, request) => ({
     onGenerated: request.onGenerated ?? defaults.onGenerated,
     signal: request.signal ?? defaults.signal,
     timeoutMs: request.timeoutMs ?? defaults.timeoutMs,
+    staggerMs: request.staggerMs ?? defaults.staggerMs,
 });
 const requestInput = async (options, dependencies, signal, timeoutMs) => {
     const images = options.images ?? [];

package/dist/api/helpers/ai/types.d.ts

@@ -69,6 +69,12 @@ export type AIRequest = {
     onGenerated?: (metadata: GenerationMetadata) => void;
     signal?: AbortSignal;
     timeoutMs?: number;
+    /**
+     * Fixed pacing delay before the generation attempt, in ms. Lets bursty
+     * fan-out callers (e.g. a nightly job over N sites) stagger requests against
+     * low provider quotas without serializing the whole job. Defaults to 0.
+     */
+    staggerMs?: number;
 };
 export type BinaryMedia = {
     arraybuffer: ArrayBuffer;

package/dist/api/helpers/google/index.d.ts

@@ -1 +1,4 @@
 export * from "./apikey";
+export { generate, generateText, models, promptDirect, promptImage } from "../ai/client";
+export type { AIClient, AIClientDefaults, AIClientDependencies, AIEndpoint, AIInput, AIModel, AIModelPreference, AIPart, AIRequest, BinaryMedia, GenerateTextOptions, GenerationResult, PromptDirectOptions, PromptImageOptions, } from "../ai/types";
+export { AI_QUOTA_EXHAUSTED_MESSAGE, QuotaDeferredError, clearModelBackoff, getQuotaRetryDelayMs, isModelBackedOff, isQuotaExhaustedError, modelBackoffRemainingMs, quotaBackoffDelayMs, recordModelRateLimit, resetModelBackoff, } from "../ai/quota";

package/dist/api/helpers/google/index.js

@@ -14,4 +14,22 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetModelBackoff = exports.recordModelRateLimit = exports.quotaBackoffDelayMs = exports.modelBackoffRemainingMs = exports.isQuotaExhaustedError = exports.isModelBackedOff = exports.getQuotaRetryDelayMs = exports.clearModelBackoff = exports.QuotaDeferredError = exports.AI_QUOTA_EXHAUSTED_MESSAGE = exports.promptImage = exports.promptDirect = exports.models = exports.generateText = exports.generate = void 0;
 __exportStar(require("./apikey"), exports);
+var client_1 = require("../ai/client");
+Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return client_1.generate; } });
+Object.defineProperty(exports, "generateText", { enumerable: true, get: function () { return client_1.generateText; } });
+Object.defineProperty(exports, "models", { enumerable: true, get: function () { return client_1.models; } });
+Object.defineProperty(exports, "promptDirect", { enumerable: true, get: function () { return client_1.promptDirect; } });
+Object.defineProperty(exports, "promptImage", { enumerable: true, get: function () { return client_1.promptImage; } });
+var quota_1 = require("../ai/quota");
+Object.defineProperty(exports, "AI_QUOTA_EXHAUSTED_MESSAGE", { enumerable: true, get: function () { return quota_1.AI_QUOTA_EXHAUSTED_MESSAGE; } });
+Object.defineProperty(exports, "QuotaDeferredError", { enumerable: true, get: function () { return quota_1.QuotaDeferredError; } });
+Object.defineProperty(exports, "clearModelBackoff", { enumerable: true, get: function () { return quota_1.clearModelBackoff; } });
+Object.defineProperty(exports, "getQuotaRetryDelayMs", { enumerable: true, get: function () { return quota_1.getQuotaRetryDelayMs; } });
+Object.defineProperty(exports, "isModelBackedOff", { enumerable: true, get: function () { return quota_1.isModelBackedOff; } });
+Object.defineProperty(exports, "isQuotaExhaustedError", { enumerable: true, get: function () { return quota_1.isQuotaExhaustedError; } });
+Object.defineProperty(exports, "modelBackoffRemainingMs", { enumerable: true, get: function () { return quota_1.modelBackoffRemainingMs; } });
+Object.defineProperty(exports, "quotaBackoffDelayMs", { enumerable: true, get: function () { return quota_1.quotaBackoffDelayMs; } });
+Object.defineProperty(exports, "recordModelRateLimit", { enumerable: true, get: function () { return quota_1.recordModelRateLimit; } });
+Object.defineProperty(exports, "resetModelBackoff", { enumerable: true, get: function () { return quota_1.resetModelBackoff; } });

package/dist/api/helpers/retryOnError.d.ts

@@ -2,7 +2,25 @@ export declare const overloadedMessages: string[];
 export declare const retryableErrorMessages: string[];
 export declare const isOverloadedApiKeyError: (error: unknown) => boolean;
 export declare const isRetryableApiError: (error: unknown) => boolean;
+export type RetryOnErrorOptions = {
+    /** Number of retries after the initial attempt. Defaults to 1. */
+    retries?: number;
+    /** Delay between attempts in ms. Defaults to 2000. */
+    errorDelay?: number;
+    /** Predicate deciding whether a failure is worth retrying. */
+    errorCheck?: (error: unknown) => boolean;
+    /** AbortSignal cancelling the backoff sleep and further attempts. */
+    signal?: AbortSignal;
+    /**
+     * Delay before each attempt after the first, in ms. It composes with
+     * errorDelay: the attempt waits for initialDelayMs plus errorDelay.
+     * Defaults to 0 (no pacing).
+     */
+    initialDelayMs?: number;
+    /** Sleep implementation, overridable in tests. */
+    sleepFn?: (ms: number) => Promise<unknown>;
+};
 export declare function retryOnError<T>(
 /** so we can log retries with useful info */
-debugIdent: string, fn: () => Promise<T>, retries?: number, errorDelay?: number, errorCheck?: (error: unknown) => boolean, signal?: AbortSignal): Promise<T>;
+debugIdent: string, fn: () => Promise<T>, retriesOrOptions?: number | RetryOnErrorOptions, errorDelay?: number, errorCheck?: (error: unknown) => boolean, signal?: AbortSignal): Promise<T>;
 export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/api/helpers/retryOnError.js

@@ -70,19 +70,51 @@ const awaitWithSignal = async (promise, signal) => {
     });
     return Promise.race([promise, abort]);
 };
+const normalizeRetryOnErrorOptions = (retriesOrOptions, errorDelay, errorCheck, signal) => ({
+    retries: typeof retriesOrOptions === "number" ? retriesOrOptions : (retriesOrOptions?.retries ?? 1),
+    errorDelay: typeof retriesOrOptions === "number"
+        ? (errorDelay ?? 2000)
+        : (retriesOrOptions?.errorDelay ?? 2000),
+    errorCheck: typeof retriesOrOptions === "number"
+        ? (errorCheck ?? exports.isRetryableApiError)
+        : (retriesOrOptions?.errorCheck ?? exports.isRetryableApiError),
+    signal: typeof retriesOrOptions === "number" ? signal : (retriesOrOptions?.signal ?? signal),
+    initialDelayMs: typeof retriesOrOptions === "number" ? 0 : Math.max(0, retriesOrOptions?.initialDelayMs ?? 0),
+    sleepFn: typeof retriesOrOptions === "number" ? undefined : retriesOrOptions?.sleepFn,
+});
 async function retryOnError(
 /** so we can log retries with useful info */
-debugIdent, fn, retries = 1, errorDelay = 2000, errorCheck = exports.isRetryableApiError, signal) {
+debugIdent, fn, retriesOrOptions, errorDelay, errorCheck = exports.isRetryableApiError, signal) {
+    const options = normalizeRetryOnErrorOptions(retriesOrOptions, errorDelay, errorCheck, signal);
+    const sleepWithSignal = async (ms) => {
+        if (ms <= 0)
+            return;
+        if (options.sleepFn !== undefined) {
+            await options.sleepFn(ms);
+            return;
+        }
+        await awaitWithSignal((0, exports.sleep)(ms), options.signal);
+    };
+    // Pacing delay before attempts after the first: it spreads bursty fan-out
+    // (e.g. nightly jobs hitting a low free-tier quota) without changing the
+    // retry semantics for direct callers.
+    await sleepWithSignal(options.initialDelayMs);
     try {
         const result = await fn();
         return result;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        if (retries > 0 && errorCheck(error)) {
-            (0, log_1.info)(`Operation ${debugIdent} failed. Retrying after ${errorDelay}ms...`, message);
-            await awaitWithSignal((0, exports.sleep)(errorDelay), signal);
-            return retryOnError(debugIdent, fn, retries - 1, errorDelay, errorCheck, signal);
+        if (options.retries > 0 && options.errorCheck(error)) {
+            (0, log_1.info)(`Operation ${debugIdent} failed. Retrying after ${options.errorDelay}ms...`, message);
+            await sleepWithSignal(options.errorDelay);
+            return retryOnError(debugIdent, fn, {
+                retries: options.retries - 1,
+                errorDelay: options.errorDelay,
+                errorCheck: options.errorCheck,
+                signal: options.signal,
+                sleepFn: options.sleepFn,
+            });
         }
         throw error;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ag-common",
-  "version": "0.0.910",
+  "version": "0.0.912",
   "license": "ISC",
   "author": "admin@gec.dev",
   "repository": {