ag-common 0.0.911 → 0.0.913

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

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1,148 +0,0 @@
-"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

@@ -1,118 +0,0 @@
-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

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

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

@@ -1,5 +0,0 @@
-export declare const getAvailableCombinations: (service: string, resetIfExhausted?: boolean) => {
-    service: string;
-    key: string;
-}[];
-export declare const blockKeyService: (apiKey: string, service: string) => void;

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

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.blockKeyService = exports.getAvailableCombinations = void 0;
-const array_1 = require("../../../common/helpers/array");
-const log_1 = require("../../../common/helpers/log");
-const node_cache_1 = require("../../../common/helpers/node-cache");
-const truncate_1 = require("../../../common/helpers/string/truncate");
-// Initialize NodeCache with 1 hour TTL for blocklisted key combinations
-const blocklist = new node_cache_1.TypedNodeCache({ stdTTL: 3600 });
-// Helper to generate blocklist key
-const getBlocklistKey = (apiKey, service) => `${(0, truncate_1.truncate)(apiKey, 10)}_${service}`;
-// Helper to check if a key+service combination is blocklisted
-const isBlocklisted = (apiKey, service) => {
-    return blocklist.has(getBlocklistKey(apiKey, service));
-};
-// Helper to add a key+service combination to the blocklist
-const addToBlocklist = (apiKey, service) => {
-    blocklist.set(getBlocklistKey(apiKey, service), true);
-};
-// Get available API keys from environment (internal use only)
-const getApiKeys = () => {
-    return (process.env.GOOGLE_API_KEY ?? "").split(",").filter(array_1.notEmpty);
-};
-// Get available key+service combinations
-const getAvailableCombinations = (service, resetIfExhausted = true) => {
-    const keys = getApiKeys();
-    (0, log_1.debug)(`got ${keys.length} GOOGLE_API_KEY keys`);
-    const combinations = [];
-    for (const key of keys) {
-        if (!isBlocklisted(key, service)) {
-            combinations.push({ service, key });
-        }
-    }
-    // If all combinations are blocklisted, clear the blocklist and try again
-    if (combinations.length === 0 && resetIfExhausted) {
-        (0, log_1.warn)(`All API key + service combinations were blocklisted for ${service}. Clearing blocklist and trying again.`);
-        blocklist.flushAll();
-        for (const key of keys) {
-            combinations.push({ service, key });
-        }
-    }
-    (0, log_1.debug)(`returning ${combinations.length} google combinations`);
-    return combinations;
-};
-exports.getAvailableCombinations = getAvailableCombinations;
-// Block a key+service combination
-const blockKeyService = (apiKey, service) => {
-    (0, log_1.warn)(`key+service blocklisted for ${service}`);
-    addToBlocklist(apiKey, service);
-};
-exports.blockKeyService = blockKeyService;

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

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

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

@@ -1,17 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-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 });
-__exportStar(require("./apikey"), exports);