ag-common 0.0.908 → 0.0.910

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

@@ -0,0 +1,55 @@
+/**
+ * Reactive per-model rate-limit backoff.
+ *
+ * Strategy: never pace proactively and never hardcode provider limits. Every
+ * discovered model stays eligible until it returns a rate-limit response; that
+ * model is then skipped for a backoff window while rotation across the
+ * remaining models continues untouched.
+ */
+/** Stable message for deferred work. Must stay app-agnostic so error tracking groups it. */
+export declare const AI_QUOTA_EXHAUSTED_MESSAGE = "AI model pool exhausted; job deferred with backoff";
+/** Grouped error for quota-deferred queue rows. Cause chain preserves the original failure. */
+export declare class QuotaDeferredError extends Error {
+    readonly deferredIds: string[];
+    readonly quotaCause?: unknown;
+    constructor(deferredIds: string[], options?: {
+        cause?: unknown;
+    });
+}
+/** True when any message in the cause chain signals model quota/capacity exhaustion. */
+export declare const isQuotaExhaustedError: (cause: unknown) => boolean;
+/**
+ * Honor the provider's retry delay when present (observed 9-57s). Returns undefined
+ * when the failure carries no usable delay, letting callers fall back to backoff.
+ */
+export declare const getQuotaRetryDelayMs: (cause: unknown) => number | undefined;
+/**
+ * Queue backoff for a deferred row: exponential hours (1h, 2h, 4h ... capped at
+ * 24h) or the provider's own retry delay, whichever is longer, plus jitter.
+ */
+export declare const quotaBackoffDelayMs: (attempt: number, cause?: unknown, random?: () => number) => number;
+/** First backoff rung after a rate-limit response; doubles per consecutive hit. */
+export declare const MODEL_RATE_LIMIT_BASE_DELAY_MS = 60000;
+/** Upper bound for per-model backoff. */
+export declare const MODEL_RATE_LIMIT_MAX_DELAY_MS: number;
+/** Small jitter so backed-off models do not resurface in lockstep. */
+export declare const MODEL_RATE_LIMIT_JITTER_MS = 1000;
+/**
+ * Record a rate-limit response for a model. The model is skipped until the
+ * backoff window elapses: the provider's own retry delay when present,
+ * otherwise an exponential window that doubles per consecutive hit.
+ * Returns the timestamp (ms) when the model becomes eligible again.
+ */
+export declare const recordModelRateLimit: (model: string, opt?: {
+    cause?: unknown;
+    nowMs?: number;
+    random?: () => number;
+}) => number;
+/** True while a rate-limited model is still inside its backoff window. */
+export declare const isModelBackedOff: (model: string, nowMs?: number) => boolean;
+/** Remaining backoff for a model in ms, or 0 when it is eligible. */
+export declare const modelBackoffRemainingMs: (model: string, nowMs?: number) => number;
+/** Mark a model eligible again, e.g. after it serves a request successfully. */
+export declare const clearModelBackoff: (model: string) => void;
+/** Test seam: clear all per-model backoff state. */
+export declare const resetModelBackoff: () => void;

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

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetModelBackoff = exports.clearModelBackoff = exports.modelBackoffRemainingMs = exports.isModelBackedOff = exports.recordModelRateLimit = exports.MODEL_RATE_LIMIT_JITTER_MS = exports.MODEL_RATE_LIMIT_MAX_DELAY_MS = exports.MODEL_RATE_LIMIT_BASE_DELAY_MS = exports.quotaBackoffDelayMs = exports.getQuotaRetryDelayMs = exports.isQuotaExhaustedError = exports.QuotaDeferredError = exports.AI_QUOTA_EXHAUSTED_MESSAGE = void 0;
+const retryOnError_1 = require("../retryOnError");
+/**
+ * Reactive per-model rate-limit backoff.
+ *
+ * Strategy: never pace proactively and never hardcode provider limits. Every
+ * discovered model stays eligible until it returns a rate-limit response; that
+ * model is then skipped for a backoff window while rotation across the
+ * remaining models continues untouched.
+ */
+/** Stable message for deferred work. Must stay app-agnostic so error tracking groups it. */
+exports.AI_QUOTA_EXHAUSTED_MESSAGE = "AI model pool exhausted; job deferred with backoff";
+/** Grouped error for quota-deferred queue rows. Cause chain preserves the original failure. */
+class QuotaDeferredError extends Error {
+    deferredIds;
+    quotaCause;
+    constructor(deferredIds, options) {
+        super(`${exports.AI_QUOTA_EXHAUSTED_MESSAGE}: deferred ${deferredIds.length} job(s)`);
+        this.name = "QuotaDeferredError";
+        this.deferredIds = deferredIds;
+        if (options?.cause !== undefined) {
+            this.quotaCause = options.cause;
+        }
+    }
+}
+exports.QuotaDeferredError = QuotaDeferredError;
+/** True when any message in the cause chain signals model quota/capacity exhaustion. */
+const isQuotaExhaustedError = (cause) => (0, retryOnError_1.isOverloadedApiKeyError)(cause);
+exports.isQuotaExhaustedError = isQuotaExhaustedError;
+const RETRY_DELAY_PATTERNS = [
+    /"retryDelay"\s*:\s*"(\d+(?:\.\d+)?)s"/i,
+    /retry in (\d+(?:\.\d+)?)\s*s/i,
+];
+const collectCauseText = (cause, seen = new Set()) => {
+    if (cause === null || cause === undefined || seen.has(cause)) {
+        return "";
+    }
+    if (typeof cause === "string") {
+        return cause;
+    }
+    seen.add(cause);
+    if (cause instanceof Error) {
+        const nested = cause.cause;
+        const nestedText = nested === undefined ? "" : `\n${collectCauseText(nested, seen)}`;
+        return `${cause.message}${nestedText}`;
+    }
+    if (typeof cause === "object") {
+        try {
+            return JSON.stringify(cause);
+        }
+        catch {
+            return Object.prototype.toString.call(cause);
+        }
+    }
+    return Object.prototype.toString.call(cause);
+};
+/**
+ * Honor the provider's retry delay when present (observed 9-57s). Returns undefined
+ * when the failure carries no usable delay, letting callers fall back to backoff.
+ */
+const getQuotaRetryDelayMs = (cause) => {
+    const combined = collectCauseText(cause);
+    for (const pattern of RETRY_DELAY_PATTERNS) {
+        const match = combined.match(pattern);
+        if (match?.[1]) {
+            const seconds = Number(match[1]);
+            if (Number.isFinite(seconds) && seconds > 0) {
+                return Math.min(Math.ceil(seconds * 1000), 15 * 60 * 1000);
+            }
+        }
+    }
+    return undefined;
+};
+exports.getQuotaRetryDelayMs = getQuotaRetryDelayMs;
+/**
+ * Queue backoff for a deferred row: exponential hours (1h, 2h, 4h ... capped at
+ * 24h) or the provider's own retry delay, whichever is longer, plus jitter.
+ */
+const quotaBackoffDelayMs = (attempt, cause, random = Math.random) => {
+    // Cap the exponential component at 16h so attempt 5+ lands on the 16h rung
+    // with up to 1h jitter, still strictly under the 24h ceiling.
+    const clamped = Math.min(Math.max(Math.floor(attempt) || 1, 1), 5);
+    const exponential = Math.min(3_600_000 * 2 ** (clamped - 1), 16 * 3_600_000);
+    const serverDelay = cause === undefined ? undefined : (0, exports.getQuotaRetryDelayMs)(cause);
+    return Math.max(serverDelay ?? 0, exponential) + Math.floor(random() * 60_000);
+};
+exports.quotaBackoffDelayMs = quotaBackoffDelayMs;
+/** First backoff rung after a rate-limit response; doubles per consecutive hit. */
+exports.MODEL_RATE_LIMIT_BASE_DELAY_MS = 60_000;
+/** Upper bound for per-model backoff. */
+exports.MODEL_RATE_LIMIT_MAX_DELAY_MS = 15 * 60_000;
+/** Small jitter so backed-off models do not resurface in lockstep. */
+exports.MODEL_RATE_LIMIT_JITTER_MS = 1_000;
+const modelBackoffUntilMs = new Map();
+const modelBackoffHits = new Map();
+/**
+ * Record a rate-limit response for a model. The model is skipped until the
+ * backoff window elapses: the provider's own retry delay when present,
+ * otherwise an exponential window that doubles per consecutive hit.
+ * Returns the timestamp (ms) when the model becomes eligible again.
+ */
+const recordModelRateLimit = (model, opt) => {
+    const now = opt?.nowMs ?? Date.now();
+    const serverDelay = opt?.cause === undefined ? undefined : (0, exports.getQuotaRetryDelayMs)(opt.cause);
+    const hits = (modelBackoffHits.get(model) ?? 0) + 1;
+    modelBackoffHits.set(model, hits);
+    const exponential = Math.min(exports.MODEL_RATE_LIMIT_BASE_DELAY_MS * 2 ** (hits - 1), exports.MODEL_RATE_LIMIT_MAX_DELAY_MS);
+    const jitter = Math.floor((opt?.random ?? Math.random)() * exports.MODEL_RATE_LIMIT_JITTER_MS);
+    const until = now + Math.max(serverDelay ?? 0, exponential) + jitter;
+    modelBackoffUntilMs.set(model, until);
+    return until;
+};
+exports.recordModelRateLimit = recordModelRateLimit;
+/** True while a rate-limited model is still inside its backoff window. */
+const isModelBackedOff = (model, nowMs) => {
+    const until = modelBackoffUntilMs.get(model);
+    if (until === undefined)
+        return false;
+    const now = nowMs ?? Date.now();
+    if (now >= until) {
+        modelBackoffUntilMs.delete(model);
+        return false;
+    }
+    return true;
+};
+exports.isModelBackedOff = isModelBackedOff;
+/** Remaining backoff for a model in ms, or 0 when it is eligible. */
+const modelBackoffRemainingMs = (model, nowMs) => {
+    const until = modelBackoffUntilMs.get(model);
+    if (until === undefined)
+        return 0;
+    return Math.max(0, until - (nowMs ?? Date.now()));
+};
+exports.modelBackoffRemainingMs = modelBackoffRemainingMs;
+/** Mark a model eligible again, e.g. after it serves a request successfully. */
+const clearModelBackoff = (model) => {
+    modelBackoffUntilMs.delete(model);
+    modelBackoffHits.delete(model);
+};
+exports.clearModelBackoff = clearModelBackoff;
+/** Test seam: clear all per-model backoff state. */
+const resetModelBackoff = () => {
+    modelBackoffUntilMs.clear();
+    modelBackoffHits.clear();
+};
+exports.resetModelBackoff = resetModelBackoff;

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

@@ -0,0 +1,118 @@
+export type AIOutputType = "text" | "image" | "audio" | "video" | "file";
+export type AIModelPreference = "fast" | "quality";
+export type AIInputRole = "user" | "assistant" | "system" | "developer";
+export type AITextPart = {
+    type: "text";
+    text: string;
+};
+export type AIMediaPart = {
+    type: Exclude<AIOutputType, "text">;
+    mimeType: string;
+    data: string;
+    name?: string;
+};
+export type AIPart = AITextPart | AIMediaPart;
+export type AIInput = {
+    role: AIInputRole;
+    content: AIPart[];
+};
+/** A provider endpoint. Codex endpoints must be direct private LAN IPv4 URLs. */
+export type AIEndpoint = {
+    protocol: "codex";
+    url: string;
+    token: string;
+};
+export type AIOutputSchema = {
+    name: string;
+    schema: Record<string, unknown>;
+};
+export type GenerationMetadata = {
+    model: string;
+    generatedAt: number;
+};
+export type GenerationUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+};
+export type GenerationResult = GenerationMetadata & {
+    output: AIPart[];
+    usage?: GenerationUsage;
+};
+/**
+ * Provider-neutral model metadata. Providers may omit capabilities they do not
+ * publish; the model id is always preserved exactly as returned by the provider.
+ */
+export type AIModel = {
+    id: string;
+    inputModalities?: AIOutputType[];
+    outputModalities?: AIOutputType[];
+    supportedReasoningEfforts?: string[];
+    defaultReasoningEffort?: string;
+    prefer?: AIModelPreference[];
+    webSearch?: boolean;
+    isDefault?: boolean;
+    ready?: boolean;
+};
+export type AIRequest = {
+    instructions?: string;
+    input: AIInput[];
+    output?: AIOutputType[];
+    ident?: string;
+    endpoint?: AIEndpoint;
+    model?: string;
+    prefer?: "fast" | "quality";
+    reasoningEffort?: string;
+    maxOutputTokens?: number;
+    outputSchema?: AIOutputSchema;
+    webSearch?: boolean;
+    onGenerated?: (metadata: GenerationMetadata) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type BinaryMedia = {
+    arraybuffer: ArrayBuffer;
+    type: string;
+    name?: string;
+};
+export type AIRequestOptions = Omit<AIRequest, "input" | "output"> & {
+    output?: AIOutputType[];
+};
+export type GenerateTextOptions = AIRequestOptions & {
+    prompt?: string;
+    input?: AIInput[];
+    images?: BinaryMedia[];
+    urls?: string[];
+};
+export type PromptDirectOptions = AIRequestOptions & {
+    prompt: string;
+    images?: BinaryMedia[];
+};
+export type PromptImageOptions = AIRequestOptions & {
+    prompt: string;
+    urls?: string[];
+    images?: BinaryMedia[];
+};
+export type AIClientDependencies = {
+    fetch?: typeof globalThis.fetch;
+    sleep?: (milliseconds: number) => Promise<void>;
+    now?: () => number;
+    createIdempotencyKey?: () => string;
+};
+export type AIClientDefaults = AIRequestOptions & AIClientDependencies & {
+    dependencies?: AIClientDependencies;
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+};
+export type AIClient = {
+    generate: (request: AIRequest) => Promise<GenerationResult>;
+    generateText: {
+        (prompt: string, options?: GenerateTextOptions): Promise<string>;
+        (options: GenerateTextOptions): Promise<string>;
+    };
+    promptDirect: (options: PromptDirectOptions) => Promise<string>;
+    promptImage: (options: PromptImageOptions) => Promise<string>;
+    models: (options?: {
+        endpoint?: AIEndpoint;
+    }) => Promise<AIModel[]>;
+};

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,2 +1 @@
 export * from "./apikey";
-export * from "./gemini";

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

@@ -15,4 +15,3 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./apikey"), exports);
-__exportStar(require("./gemini"), exports);

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

@@ -1,4 +1,5 @@
 export * from "./acm";
+export * from "./ai";
 export * from "./api";
 export * from "./apigw";
 export * from "./aws";

package/dist/api/helpers/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./acm"), exports);
+__exportStar(require("./ai"), exports);
 __exportStar(require("./api"), exports);
 __exportStar(require("./apigw"), exports);
 __exportStar(require("./aws"), exports);

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

@@ -1,8 +1,8 @@
 export declare const overloadedMessages: string[];
 export declare const retryableErrorMessages: string[];
-export declare const isOverloadedApiKeyError: (error: Error) => boolean;
-export declare const isRetryableApiError: (error: Error) => boolean;
+export declare const isOverloadedApiKeyError: (error: unknown) => boolean;
+export declare const isRetryableApiError: (error: unknown) => boolean;
 export declare function retryOnError<T>(
 /** so we can log retries with useful info */
-debugIdent: string, fn: () => Promise<T>, retries?: number, errorDelay?: number, errorCheck?: (error: Error) => boolean): Promise<T>;
+debugIdent: string, fn: () => Promise<T>, retries?: number, errorDelay?: number, errorCheck?: (error: unknown) => boolean, signal?: AbortSignal): Promise<T>;
 export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/api/helpers/retryOnError.js

@@ -3,7 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sleep = exports.isRetryableApiError = exports.isOverloadedApiKeyError = exports.retryableErrorMessages = exports.overloadedMessages = void 0;
 exports.retryOnError = retryOnError;
 const log_1 = require("../../common/helpers/log");
-exports.overloadedMessages = ["429", "current usage", "current quota", "overloaded"];
+exports.overloadedMessages = [
+    "429",
+    "current usage",
+    "current quota",
+    "overloaded",
+    "quota exceeded",
+    "quota failure",
+    "rate limited",
+    "too many requests",
+    "generate_content_free_tier_requests",
+    "generaterequestsperday",
+    "high demand",
+    "model pool exhausted",
+    "no available model",
+];
 exports.retryableErrorMessages = [
     ...exports.overloadedMessages,
     "500",
@@ -12,27 +26,63 @@ exports.retryableErrorMessages = [
     "invalid_type",
     "expected",
 ];
+const errorText = (error) => {
+    if (typeof error === "string") {
+        return error;
+    }
+    if (error instanceof Error) {
+        const nested = error.cause;
+        const nestedText = nested === undefined ? "" : ` ${errorText(nested)}`;
+        return `${error.message}${nestedText}`;
+    }
+    if (typeof error === "object" && error !== null) {
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return Object.prototype.toString.call(error);
+        }
+    }
+    return String(error);
+};
 const errorContainsAnyMessage = (error, messages) => {
-    const message = error.message.toLowerCase();
+    const message = errorText(error).toLowerCase();
     return messages.some((m) => message.includes(m.toLowerCase()));
 };
 const isOverloadedApiKeyError = (error) => errorContainsAnyMessage(error, exports.overloadedMessages);
 exports.isOverloadedApiKeyError = isOverloadedApiKeyError;
 const isRetryableApiError = (error) => errorContainsAnyMessage(error, exports.retryableErrorMessages);
 exports.isRetryableApiError = isRetryableApiError;
+const createAbortError = () => {
+    const error = new Error("Operation aborted");
+    error.name = "AbortError";
+    return error;
+};
+const awaitWithSignal = async (promise, signal) => {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        throw createAbortError();
+    const abort = new Promise((_, reject) => {
+        const onAbort = () => reject(createAbortError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        void promise.then(() => signal.removeEventListener("abort", onAbort), () => signal.removeEventListener("abort", onAbort));
+    });
+    return Promise.race([promise, abort]);
+};
 async function retryOnError(
 /** so we can log retries with useful info */
-debugIdent, fn, retries = 1, errorDelay = 2000, errorCheck = exports.isRetryableApiError) {
+debugIdent, fn, retries = 1, errorDelay = 2000, errorCheck = exports.isRetryableApiError, signal) {
     try {
-        return fn();
+        const result = await fn();
+        return result;
     }
     catch (error) {
-        const e = error;
-        const em = e.message;
-        if (retries > 0 && errorCheck(e)) {
-            (0, log_1.info)(`Operation ${debugIdent} failed. Retrying after ${errorDelay}ms...`, em);
-            await (0, exports.sleep)(errorDelay);
-            return retryOnError(debugIdent, fn, retries - 1, errorDelay, errorCheck);
+        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);
         }
         throw error;
     }

package/package.json

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

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

@@ -1,26 +0,0 @@
-export type ModelPreference = "quality" | "fast" | undefined;
-/** Provenance of a successful response, with generation time in Unix milliseconds. */
-export type GenerationMetadata = {
-    model: string;
-    generatedAt: number;
-};
-export declare const isTextGenerationModel: (name: string) => boolean;
-export declare const geminiPromptImage: ({ prompt, urls, ident, prefer, onGenerated, }: {
-    prompt: string;
-    urls?: string[];
-    ident: string | undefined;
-    prefer?: ModelPreference;
-    onGenerated?: (metadata: GenerationMetadata) => void;
-}) => Promise<string>;
-export declare const geminiPromptDirect: ({ prompt, images, ident, prefer, groundedSearch, onGenerated, }: {
-    prompt: string;
-    images?: {
-        arraybuffer: ArrayBuffer;
-        type: string;
-    }[];
-    ident: string | undefined;
-    prefer?: ModelPreference;
-    groundedSearch?: boolean;
-    onGenerated?: (metadata: GenerationMetadata) => void;
-}) => Promise<string>;
-export declare const resolveGroundedUrl: (url: string) => Promise<string>;