rate-budget 0.1.0

package/dist/cjs/token-budget.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculatePerRequestTokenBudget = calculatePerRequestTokenBudget;
+exports.calculateTokenBudgetPortion = calculateTokenBudgetPortion;
+exports.distributeFlexibleTokenBudget = distributeFlexibleTokenBudget;
+const limits_js_1 = require("./limits.js");
+function normalizeRatio(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.min(1, Math.max(0, value));
+}
+function calculatePerRequestTokenBudget(input) {
+    const tokensPerWindow = (0, limits_js_1.toPositiveInteger)(input.tokensPerWindow);
+    const requestSpacingMs = (0, limits_js_1.toPositiveInteger)(input.requestSpacingMs);
+    const windowMs = (0, limits_js_1.toPositiveInteger)(input.windowMs ?? limits_js_1.DEFAULT_LIMIT_WINDOW_MS, limits_js_1.DEFAULT_LIMIT_WINDOW_MS);
+    const requestsPerWindow = windowMs / requestSpacingMs;
+    const minimumTokens = (0, limits_js_1.toPositiveInteger)(input.minimumTokens ?? 1);
+    return Math.max(minimumTokens, Math.floor(tokensPerWindow / Math.max(1, requestsPerWindow)));
+}
+function calculateTokenBudgetPortion(totalBudget, ratio) {
+    return Math.max(1, Math.floor((0, limits_js_1.toPositiveInteger)(totalBudget) * normalizeRatio(ratio)));
+}
+function distributeFlexibleTokenBudget(input) {
+    const parentBudget = (0, limits_js_1.toPositiveInteger)(input.parentBudget);
+    let remainingTokens = (0, limits_js_1.toNonNegativeInteger)(input.availableTokens);
+    const allocations = Object.create(null);
+    for (const partition of input.partitions) {
+        const targetBudget = Math.floor(parentBudget * normalizeRatio(partition.targetRatio));
+        const allocated = Math.min(targetBudget, remainingTokens);
+        allocations[partition.name] = allocated;
+        remainingTokens -= allocated;
+    }
+    for (const partition of input.partitions) {
+        if (remainingTokens <= 0) {
+            break;
+        }
+        const currentAllocation = allocations[partition.name] ?? 0;
+        const maxBudget = Math.max(currentAllocation, Math.floor(parentBudget * normalizeRatio(partition.maxRatio)));
+        const additionalTokens = Math.min(maxBudget - currentAllocation, remainingTokens);
+        allocations[partition.name] = currentAllocation + additionalTokens;
+        remainingTokens -= additionalTokens;
+    }
+    return allocations;
+}
+//# sourceMappingURL=token-budget.js.map

package/dist/cjs/token-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.js","sourceRoot":"","sources":["../../src/token-budget.ts"],"names":[],"mappings":";;AA2BA,wEAgBC;AAED,kEAQC;AAED,sEAsCC;AA7FD,2CAIqB;AAerB,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAgB,8BAA8B,CAC5C,KAAiC;IAEjC,MAAM,eAAe,GAAG,IAAA,6BAAiB,EAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACjE,MAAM,gBAAgB,GAAG,IAAA,6BAAiB,EAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,IAAA,6BAAiB,EAChC,KAAK,CAAC,QAAQ,IAAI,mCAAuB,EACzC,mCAAuB,CACxB,CAAC;IACF,MAAM,iBAAiB,GAAG,QAAQ,GAAG,gBAAgB,CAAC;IACtD,MAAM,aAAa,GAAG,IAAA,6BAAiB,EAAC,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC;IAElE,OAAO,IAAI,CAAC,GAAG,CACb,aAAa,EACb,IAAI,CAAC,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAC7D,CAAC;AACJ,CAAC;AAED,SAAgB,2BAA2B,CACzC,WAAmB,EACnB,KAAa;IAEb,OAAO,IAAI,CAAC,GAAG,CACb,CAAC,EACD,IAAI,CAAC,KAAK,CAAC,IAAA,6BAAiB,EAAC,WAAW,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,CACnE,CAAC;AACJ,CAAC;AAED,SAAgB,6BAA6B,CAAsB,KAIlE;IACC,MAAM,YAAY,GAAG,IAAA,6BAAiB,EAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC3D,IAAI,eAAe,GAAG,IAAA,gCAAoB,EAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAClE,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAyB,CAAC;IAEhE,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAC7B,YAAY,GAAG,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,CACrD,CAAC;QACF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;QAC1D,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;QACxC,eAAe,IAAI,SAAS,CAAC;IAC/B,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACzC,IAAI,eAAe,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM;QACR,CAAC;QAED,MAAM,iBAAiB,GAAG,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CACxB,iBAAiB,EACjB,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAC9D,CAAC;QACF,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAC/B,SAAS,GAAG,iBAAiB,EAC7B,eAAe,CAChB,CAAC;QAEF,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;QACnE,eAAe,IAAI,gBAAgB,CAAC;IACtC,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./limits.js";
+export * from "./memory-cooldown.js";
+export * from "./retry.js";
+export * from "./token-budget.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export * from "./limits.js";
+export * from "./memory-cooldown.js";
+export * from "./retry.js";
+export * from "./token-budget.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC"}

package/dist/esm/limits.d.ts

@@ -0,0 +1,91 @@
+export declare const DEFAULT_LIMIT_WINDOW_MS = 60000;
+export declare const DEFAULT_LIMIT_SAFETY_BUFFER_MS = 1000;
+export declare const DEFAULT_INACTIVE_COOLDOWN_MULTIPLIER = 2;
+export type TimestampInput = Date | number | string | null | undefined;
+export type LimitWindowOptions = {
+    windowMs?: number;
+    safetyBufferMs?: number;
+};
+export type RequestLimitProfileInput = {
+    rpmLimit: number;
+    tpmLimit: number;
+    rpdLimit: number;
+    dailyThresholdPercent?: number;
+    windowMs?: number;
+    safetyBufferMs?: number;
+    inactiveCooldownMultiplier?: number;
+};
+export type RequestLimitProfile = {
+    rpmLimit: number;
+    tpmLimit: number;
+    rpdLimit: number;
+    dailyThresholdPercent: number;
+    dailyThresholdRequests: number;
+    cooldownMs: number;
+    inactiveCooldownMs: number;
+};
+export type CountLimitDecision = {
+    allowed: true;
+    usedCount: number;
+    thresholdCount: number;
+    remainingCount: number;
+} | {
+    allowed: false;
+    usedCount: number;
+    thresholdCount: number;
+    remainingCount: 0;
+};
+export type WindowUsageEntry = {
+    occurredAt: TimestampInput;
+    cost: number;
+};
+export type WindowUsageInput = LimitWindowOptions & {
+    currentCost?: number;
+    incomingCost: number;
+    limit: number;
+    entries: readonly WindowUsageEntry[];
+    now?: number;
+    entriesSortedOldestFirst?: boolean;
+};
+export type WindowUsageDecision = {
+    allowed: true;
+    reason: "within_limit";
+    projectedCost: number;
+    limit: number;
+    retryAfterMs: 0;
+} | {
+    allowed: false;
+    reason: "single_request_exceeds_limit";
+    projectedCost: number;
+    limit: number;
+    retryAfterMs: null;
+} | {
+    allowed: false;
+    reason: "window_exhausted";
+    projectedCost: number;
+    limit: number;
+    retryAfterMs: number;
+};
+export declare function toPositiveInteger(value: number, fallback?: number): number;
+export declare function toNonNegativeInteger(value: number, fallback?: number): number;
+export declare function clampPercent(value: number, fallback?: number): number;
+export declare function toTimestampMs(value: TimestampInput): number | null;
+export declare function calculateLimitSpacingMs(limitPerWindow: number, options?: LimitWindowOptions): number;
+export declare function calculateInactiveLimitSpacingMs(limitPerWindow: number, options?: LimitWindowOptions & {
+    multiplier?: number;
+}): number;
+export declare function calculateThresholdCount(limit: number, thresholdPercent?: number): number;
+export declare function evaluateCountLimit(input: {
+    usedCount: number;
+    limit: number;
+    thresholdPercent?: number;
+}): CountLimitDecision;
+export declare function calculateCooldownWaitMs(input: {
+    lastAcceptedAt: TimestampInput;
+    cooldownMs: number;
+    now?: number;
+}): number;
+export declare function evaluateWindowUsage(input: WindowUsageInput): WindowUsageDecision;
+export declare function calculateWindowUsageWaitMs(input: WindowUsageInput): number;
+export declare function buildRequestLimitProfile(input: RequestLimitProfileInput): RequestLimitProfile;
+//# sourceMappingURL=limits.d.ts.map

package/dist/esm/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/limits.ts"],"names":[],"mappings":"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"}

package/dist/esm/limits.js

@@ -0,0 +1,170 @@
+export const DEFAULT_LIMIT_WINDOW_MS = 60000;
+export const DEFAULT_LIMIT_SAFETY_BUFFER_MS = 1000;
+export const DEFAULT_INACTIVE_COOLDOWN_MULTIPLIER = 2;
+function normalizeFiniteNumber(value, fallback) {
+    return Number.isFinite(value) ? value : fallback;
+}
+export function toPositiveInteger(value, fallback = 1) {
+    return Math.max(1, Math.floor(normalizeFiniteNumber(value, fallback)));
+}
+export function toNonNegativeInteger(value, fallback = 0) {
+    return Math.max(0, Math.floor(normalizeFiniteNumber(value, fallback)));
+}
+export function clampPercent(value, fallback = 100) {
+    const safeValue = normalizeFiniteNumber(value, fallback);
+    return Math.min(100, Math.max(0, safeValue));
+}
+export function toTimestampMs(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : null;
+    }
+    const timestamp = value instanceof Date ? value.getTime() : Date.parse(value);
+    return Number.isFinite(timestamp) ? timestamp : null;
+}
+export function calculateLimitSpacingMs(limitPerWindow, options = {}) {
+    const limit = toPositiveInteger(limitPerWindow);
+    const windowMs = toPositiveInteger(options.windowMs ?? DEFAULT_LIMIT_WINDOW_MS, DEFAULT_LIMIT_WINDOW_MS);
+    const safetyBufferMs = toNonNegativeInteger(options.safetyBufferMs ?? DEFAULT_LIMIT_SAFETY_BUFFER_MS, DEFAULT_LIMIT_SAFETY_BUFFER_MS);
+    return Math.ceil(windowMs / limit + safetyBufferMs);
+}
+export function calculateInactiveLimitSpacingMs(limitPerWindow, options = {}) {
+    const multiplier = Math.max(1, normalizeFiniteNumber(options.multiplier ?? DEFAULT_INACTIVE_COOLDOWN_MULTIPLIER, DEFAULT_INACTIVE_COOLDOWN_MULTIPLIER));
+    return Math.ceil(calculateLimitSpacingMs(limitPerWindow, options) * multiplier);
+}
+export function calculateThresholdCount(limit, thresholdPercent = 100) {
+    const safeLimit = toPositiveInteger(limit);
+    const safeThresholdPercent = clampPercent(thresholdPercent);
+    return Math.max(1, Math.ceil(safeLimit * (safeThresholdPercent / 100)));
+}
+export function evaluateCountLimit(input) {
+    const usedCount = toNonNegativeInteger(input.usedCount);
+    const thresholdCount = calculateThresholdCount(input.limit, input.thresholdPercent);
+    const remainingCount = Math.max(0, thresholdCount - usedCount);
+    if (remainingCount <= 0) {
+        return {
+            allowed: false,
+            usedCount,
+            thresholdCount,
+            remainingCount: 0,
+        };
+    }
+    return {
+        allowed: true,
+        usedCount,
+        thresholdCount,
+        remainingCount,
+    };
+}
+export function calculateCooldownWaitMs(input) {
+    const lastAcceptedAt = toTimestampMs(input.lastAcceptedAt);
+    if (lastAcceptedAt === null) {
+        return 0;
+    }
+    const now = normalizeFiniteNumber(input.now ?? Date.now(), Date.now());
+    const cooldownMs = toNonNegativeInteger(input.cooldownMs);
+    return Math.max(0, cooldownMs - (now - lastAcceptedAt));
+}
+function normalizeWindowEntries(entries, entriesSortedOldestFirst, input) {
+    const normalized = entries.flatMap((entry) => {
+        const occurredAtMs = toTimestampMs(entry.occurredAt);
+        if (occurredAtMs === null ||
+            occurredAtMs < input.now - input.windowMs ||
+            occurredAtMs > input.now) {
+            return [];
+        }
+        return [
+            {
+                occurredAtMs,
+                cost: toNonNegativeInteger(entry.cost),
+            },
+        ];
+    });
+    if (entriesSortedOldestFirst) {
+        return normalized;
+    }
+    return normalized.sort((left, right) => left.occurredAtMs - right.occurredAtMs);
+}
+export function evaluateWindowUsage(input) {
+    const limit = toPositiveInteger(input.limit);
+    const incomingCost = toNonNegativeInteger(input.incomingCost);
+    const now = normalizeFiniteNumber(input.now ?? Date.now(), Date.now());
+    const windowMs = toPositiveInteger(input.windowMs ?? DEFAULT_LIMIT_WINDOW_MS, DEFAULT_LIMIT_WINDOW_MS);
+    const entries = normalizeWindowEntries(input.entries, input.entriesSortedOldestFirst ?? true, { now, windowMs });
+    const currentCost = input.currentCost === undefined
+        ? entries.reduce((sum, entry) => sum + entry.cost, 0)
+        : toNonNegativeInteger(input.currentCost);
+    const projectedCost = currentCost + incomingCost;
+    if (incomingCost > limit) {
+        return {
+            allowed: false,
+            reason: "single_request_exceeds_limit",
+            projectedCost,
+            limit,
+            retryAfterMs: null,
+        };
+    }
+    if (projectedCost <= limit) {
+        return {
+            allowed: true,
+            reason: "within_limit",
+            projectedCost,
+            limit,
+            retryAfterMs: 0,
+        };
+    }
+    const safetyBufferMs = toNonNegativeInteger(input.safetyBufferMs ?? DEFAULT_LIMIT_SAFETY_BUFFER_MS, DEFAULT_LIMIT_SAFETY_BUFFER_MS);
+    let remainingCost = projectedCost;
+    for (const entry of entries) {
+        remainingCost -= entry.cost;
+        if (remainingCost <= limit) {
+            return {
+                allowed: false,
+                reason: "window_exhausted",
+                projectedCost,
+                limit,
+                retryAfterMs: Math.max(0, windowMs - (now - entry.occurredAtMs) + safetyBufferMs),
+            };
+        }
+    }
+    return {
+        allowed: false,
+        reason: "window_exhausted",
+        projectedCost,
+        limit,
+        retryAfterMs: windowMs,
+    };
+}
+export function calculateWindowUsageWaitMs(input) {
+    const decision = evaluateWindowUsage(input);
+    if (decision.allowed) {
+        return 0;
+    }
+    return (decision.retryAfterMs ??
+        toPositiveInteger(input.windowMs ?? DEFAULT_LIMIT_WINDOW_MS, DEFAULT_LIMIT_WINDOW_MS));
+}
+export function buildRequestLimitProfile(input) {
+    const rpmLimit = toPositiveInteger(input.rpmLimit);
+    const tpmLimit = toPositiveInteger(input.tpmLimit);
+    const rpdLimit = toPositiveInteger(input.rpdLimit);
+    const dailyThresholdPercent = clampPercent(input.dailyThresholdPercent ?? 100);
+    const cooldownOptions = {
+        windowMs: input.windowMs,
+        safetyBufferMs: input.safetyBufferMs,
+    };
+    return {
+        rpmLimit,
+        tpmLimit,
+        rpdLimit,
+        dailyThresholdPercent,
+        dailyThresholdRequests: calculateThresholdCount(rpdLimit, dailyThresholdPercent),
+        cooldownMs: calculateLimitSpacingMs(rpmLimit, cooldownOptions),
+        inactiveCooldownMs: calculateInactiveLimitSpacingMs(rpmLimit, {
+            ...cooldownOptions,
+            multiplier: input.inactiveCooldownMultiplier,
+        }),
+    };
+}
+//# sourceMappingURL=limits.js.map

package/dist/esm/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/limits.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory-cooldown.d.ts

@@ -0,0 +1,38 @@
+export type ActorCooldownState = {
+    lastAcceptedAt: number;
+    lastActorId: string;
+};
+export type ActorCooldownDecision = {
+    allowed: true;
+    state: ActorCooldownState;
+} | {
+    allowed: false;
+    retryAfterMs: number;
+    state: ActorCooldownState;
+};
+export type ActorCooldownOptions = {
+    sameActorCooldownMs: number;
+    differentActorCooldownMs: number;
+    stateTtlMs?: number;
+    cleanupInterval?: number;
+};
+export declare function consumeActorCooldown(currentState: ActorCooldownState | null | undefined, input: {
+    actorId: string;
+    now?: number;
+    sameActorCooldownMs: number;
+    differentActorCooldownMs: number;
+}): ActorCooldownDecision;
+export declare class InMemoryActorCooldownLimiter {
+    private readonly states;
+    private readonly sameActorCooldownMs;
+    private readonly differentActorCooldownMs;
+    private readonly stateTtlMs;
+    private readonly cleanupInterval;
+    private touches;
+    constructor(options: ActorCooldownOptions);
+    consume(scopeId: string, actorId: string, now?: number): ActorCooldownDecision;
+    reset(scopeId?: string): void;
+    size(): number;
+    private cleanup;
+}
+//# sourceMappingURL=memory-cooldown.d.ts.map

package/dist/esm/memory-cooldown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cooldown.d.ts","sourceRoot":"","sources":["../../src/memory-cooldown.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,GAC5C;IACE,OAAO,EAAE,KAAK,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,kBAAkB,CAAC;CAC3B,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAAG;IACjC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wBAAwB,EAAE,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,EACnD,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wBAAwB,EAAE,MAAM,CAAC;CAClC,GACA,qBAAqB,CAkCvB;AAED,qBAAa,4BAA4B;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,OAAO,CAAK;gBAER,OAAO,EAAE,oBAAoB;IAYzC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAa;IAiB1D,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM;IAStB,IAAI;IAIJ,OAAO,CAAC,OAAO;CAahB"}

package/dist/esm/memory-cooldown.js

@@ -0,0 +1,76 @@
+import { toNonNegativeInteger } from "./limits.js";
+export function consumeActorCooldown(currentState, input) {
+    const now = Number.isFinite(input.now) ? input.now ?? Date.now() : Date.now();
+    if (!currentState) {
+        return {
+            allowed: true,
+            state: {
+                lastAcceptedAt: now,
+                lastActorId: input.actorId,
+            },
+        };
+    }
+    const requiredCooldownMs = currentState.lastActorId === input.actorId
+        ? toNonNegativeInteger(input.sameActorCooldownMs)
+        : toNonNegativeInteger(input.differentActorCooldownMs);
+    const elapsedMs = now - currentState.lastAcceptedAt;
+    if (elapsedMs < requiredCooldownMs) {
+        return {
+            allowed: false,
+            retryAfterMs: requiredCooldownMs - elapsedMs,
+            state: currentState,
+        };
+    }
+    return {
+        allowed: true,
+        state: {
+            lastAcceptedAt: now,
+            lastActorId: input.actorId,
+        },
+    };
+}
+export class InMemoryActorCooldownLimiter {
+    constructor(options) {
+        this.states = new Map();
+        this.touches = 0;
+        this.sameActorCooldownMs = toNonNegativeInteger(options.sameActorCooldownMs);
+        this.differentActorCooldownMs = toNonNegativeInteger(options.differentActorCooldownMs);
+        this.stateTtlMs = toNonNegativeInteger(options.stateTtlMs ?? 5 * 60000);
+        this.cleanupInterval = Math.max(1, toNonNegativeInteger(options.cleanupInterval ?? 256, 256));
+    }
+    consume(scopeId, actorId, now = Date.now()) {
+        this.cleanup(now);
+        const decision = consumeActorCooldown(this.states.get(scopeId), {
+            actorId,
+            now,
+            sameActorCooldownMs: this.sameActorCooldownMs,
+            differentActorCooldownMs: this.differentActorCooldownMs,
+        });
+        if (decision.allowed) {
+            this.states.set(scopeId, decision.state);
+        }
+        return decision;
+    }
+    reset(scopeId) {
+        if (scopeId) {
+            this.states.delete(scopeId);
+            return;
+        }
+        this.states.clear();
+    }
+    size() {
+        return this.states.size;
+    }
+    cleanup(now) {
+        this.touches += 1;
+        if (this.touches % this.cleanupInterval !== 0) {
+            return;
+        }
+        for (const [scopeId, state] of this.states.entries()) {
+            if (now - state.lastAcceptedAt > this.stateTtlMs) {
+                this.states.delete(scopeId);
+            }
+        }
+    }
+}
+//# sourceMappingURL=memory-cooldown.js.map

package/dist/esm/memory-cooldown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cooldown.js","sourceRoot":"","sources":["../../src/memory-cooldown.ts"],"names":[],"mappings":"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"}

package/dist/esm/retry.d.ts

@@ -0,0 +1,29 @@
+export type RetryableErrorOptions = {
+    statusCodes?: readonly number[];
+    messageIncludes?: readonly string[];
+};
+export type RetryDelay = number | ((input: {
+    attemptIndex: number;
+    error: unknown;
+}) => number);
+export type RetryAsyncInput<T> = {
+    task: (input: {
+        attemptIndex: number;
+    }) => Promise<T>;
+    retryAttempts: number;
+    delayMs?: RetryDelay;
+    shouldRetry?: (error: unknown, input: {
+        attemptIndex: number;
+    }) => boolean;
+    onRetry?: (input: {
+        attemptIndex: number;
+        nextDelayMs: number;
+        error: unknown;
+    }) => void | Promise<void>;
+};
+export declare function delay(ms: number): Promise<unknown>;
+export declare function getErrorStatus(error: unknown): number | null;
+export declare function getErrorMessage(error: unknown): string;
+export declare function isRetryableError(error: unknown, options?: RetryableErrorOptions): boolean;
+export declare function retryAsync<T>(input: RetryAsyncInput<T>): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/esm/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/retry.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,CAAC,CAAC,KAAK,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,KAAK,MAAM,CAAC,CAAC;AAElE,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,IAAI,EAAE,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IAC3E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,OAAO,CAAC;KAChB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAEF,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,oBAU/B;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,iBAQ5C;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,UAU7C;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,qBAA0B,WAcpC;AAaD,wBAAsB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,cAsC5D"}

package/dist/esm/retry.js

@@ -0,0 +1,75 @@
+import { toNonNegativeInteger } from "./limits.js";
+export function delay(ms) {
+    const safeMs = toNonNegativeInteger(ms);
+    if (safeMs <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        setTimeout(resolve, safeMs);
+    });
+}
+export function getErrorStatus(error) {
+    if (!error || typeof error !== "object" || !("status" in error)) {
+        return null;
+    }
+    const status = error.status;
+    return typeof status === "number" && Number.isFinite(status) ? status : null;
+}
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    return "";
+}
+export function isRetryableError(error, options = {}) {
+    const statusCodes = options.statusCodes ?? [429, 500, 503];
+    const status = getErrorStatus(error);
+    if (status !== null && statusCodes.includes(status)) {
+        return true;
+    }
+    const message = getErrorMessage(error).toLowerCase();
+    return (options.messageIncludes ?? []).some((fragment) => message.includes(fragment.toLowerCase()));
+}
+function resolveRetryDelay(delayMs, input) {
+    if (typeof delayMs === "function") {
+        return toNonNegativeInteger(delayMs(input));
+    }
+    return toNonNegativeInteger(delayMs ?? 0);
+}
+export async function retryAsync(input) {
+    const retryAttempts = toNonNegativeInteger(input.retryAttempts);
+    const maxAttempts = retryAttempts + 1;
+    let lastError = null;
+    for (let attemptIndex = 0; attemptIndex < maxAttempts; attemptIndex += 1) {
+        try {
+            return await input.task({ attemptIndex });
+        }
+        catch (error) {
+            lastError = error;
+            if (attemptIndex >= maxAttempts - 1) {
+                break;
+            }
+            const shouldRetry = input.shouldRetry
+                ? input.shouldRetry(error, { attemptIndex })
+                : isRetryableError(error);
+            if (!shouldRetry) {
+                break;
+            }
+            const nextDelayMs = resolveRetryDelay(input.delayMs, {
+                attemptIndex,
+                error,
+            });
+            await input.onRetry?.({
+                attemptIndex,
+                nextDelayMs,
+                error,
+            });
+            await delay(nextDelayMs);
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/esm/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/esm/token-budget.d.ts

@@ -0,0 +1,19 @@
+export type PerRequestTokenBudgetInput = {
+    tokensPerWindow: number;
+    requestSpacingMs: number;
+    windowMs?: number;
+    minimumTokens?: number;
+};
+export type FlexibleTokenBudgetPartition<Name extends string = string> = {
+    name: Name;
+    targetRatio: number;
+    maxRatio: number;
+};
+export declare function calculatePerRequestTokenBudget(input: PerRequestTokenBudgetInput): number;
+export declare function calculateTokenBudgetPortion(totalBudget: number, ratio: number): number;
+export declare function distributeFlexibleTokenBudget<Name extends string>(input: {
+    parentBudget: number;
+    availableTokens: number;
+    partitions: readonly FlexibleTokenBudgetPartition<Name>[];
+}): Record<Name, number>;
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/esm/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../../src/token-budget.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,0BAA0B,GAAG;IACvC,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,4BAA4B,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI;IACvE,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAUF,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,0BAA0B,UAelC;AAED,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,UAMd;AAED,wBAAgB,6BAA6B,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,EAAE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,SAAS,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC;CAC3D,wBAkCA"}