@retinue/agentkit 0.1.0

package/dist/usage/quota.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Rollup buckets and quota enforcement (#139).
+ *
+ * Phase 5 gave usage a recording hook and #100 made it durable. Nothing aggregated it and nothing enforced a
+ * limit, so one customer's consumption was unbounded.
+ *
+ * Four decisions carry this module.
+ *
+ * **Buckets are identified by their start, truncated to the period.** Two writers asking "which bucket does T
+ * belong to" must agree, and they do because truncation is a pure function of T rather than a range someone
+ * chooses.
+ *
+ * **The quota check happens at admission, before any provider call.** AC-2's wording is "before work starts",
+ * and the reason is what the alternative costs: a limit enforced mid-run leaves a half-written answer, a
+ * partial charge, and a user who has to guess whether to retry. Refusing admission is a complete outcome.
+ *
+ * **The warning fires below the limit, not at it.** A customer told at 100% is told when work is already
+ * failing. The threshold is a fraction so it scales with the limit rather than being a constant that is
+ * meaningless at one plan size and useless at another.
+ *
+ * **Enforcement reads a rollup, not the ledger.** Admission is on the hot path of every message; a check that
+ * scanned raw events would make the platform slower in exact proportion to how much it had been used.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { QuotaWindow, RollupPeriod, UsageLimitStore, UsageRollupStore, UsageStore, UsageTotals } from "../persistence/index.js";
+import type { PrincipalId } from "../core/ids.js";
+/** Zero, as a total. Named because "no usage" appears in several places and an object literal invites drift. */
+export declare const NO_USAGE: UsageTotals;
+/**
+ * The instant a period's bucket opens, for a given moment.
+ *
+ * Truncation in UTC, deliberately. A tenant-local day would make a bucket's identity depend on a timezone
+ * setting that can change, and a rollup already written under the old offset would silently belong to a
+ * different day than one written after — so "yesterday" would double-count an hour or lose one. Presenting
+ * totals in local time is a display concern; *storing* them in one is a correctness bug.
+ */
+export declare const bucketStartFor: (period: RollupPeriod, at: string) => string;
+/** The bucket after this one. For tiling a range without arithmetic at the call site. */
+export declare const nextBucket: (period: RollupPeriod, bucketStart: string) => string;
+/** Every bucket start covering `[from, to)`, in order. */
+export declare const bucketsBetween: (period: RollupPeriod, from: string, to: string) => readonly string[];
+/**
+ * What a tenant may consume in a period.
+ *
+ * Every field optional, and an omitted field is *unbounded* rather than zero. That direction is deliberate: a
+ * misconfigured quota that blocks everything is an outage, and a misconfigured quota that blocks nothing is a
+ * bill — and the bill is visible in the rollups this module also provides, whereas the outage is only visible
+ * to the customer it is happening to.
+ */
+/** How the window reads in a sentence: "your 5,000 spend limit for **the day** / **any 5 hours**". */
+export declare const describeWindow: (window: QuotaWindow) => string;
+export type QuotaLimits = {
+    /**
+     * The span this allowance covers.
+     *
+     * Was `period: RollupPeriod` until #181. Widened rather than supplemented, so there is exactly one place a
+     * window is described and no combination of fields that means two things at once.
+     */
+    readonly window: QuotaWindow;
+    /**
+     * Whose allowance this is — absent means the whole tenant's (#175).
+     *
+     * Load-bearing, not informational: it decides **which rollup the usage is read from**. A per-person limit
+     * checked against the tenant's total is not a per-person limit — the first busy colleague exhausts everyone's
+     * allowance, and the person refused has spent nothing. That was the shape of the bug before this existed: the
+     * guard already accepted per-principal *limits* through `resolveLimits`, and always compared them against
+     * tenant-wide usage.
+     */
+    readonly principalId?: PrincipalId;
+    /**
+     * The model this allowance covers, or absent for any model — #182.
+     *
+     * Load-bearing in the same way `principalId` is: it decides **which records the usage is read from**. A limit
+     * on an expensive model checked against all traffic is not a per-model limit — a busy hour on a cheap model
+     * exhausts it, and the person refused has not touched the model they are being refused for.
+     */
+    readonly modelId?: string;
+    readonly costMinorUnits?: number;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    /**
+     * Fraction of a limit at which a warning fires. Defaults to 0.8.
+     *
+     * A fraction rather than an absolute, so it scales with the limit instead of being meaningless on a large
+     * plan and constantly tripping on a small one.
+     */
+    readonly warnAt?: number;
+};
+export declare const DEFAULT_WARN_AT = 0.8;
+/** Which limit was hit. Separate values because the sentence a user reads differs. */
+export declare const QUOTA_DIMENSIONS: readonly ["cost", "input-tokens", "output-tokens"];
+export type QuotaDimension = (typeof QUOTA_DIMENSIONS)[number];
+/**
+ * The admission answer.
+ *
+ * A union, so "refused" has no `allowed` shape to hide in: a caller cannot read a refusal as a permissive
+ * default, which for a spend limit is the failure that costs money.
+ */
+export type QuotaDecision = {
+    readonly admitted: true;
+    readonly usage: UsageTotals;
+    readonly warnings: readonly QuotaWarning[];
+} | {
+    readonly admitted: false;
+    readonly dimension: QuotaDimension;
+    readonly limit: number;
+    readonly used: number;
+    /** Present when the limit that refused is scoped to one model — #182. */
+    readonly modelId?: string;
+    readonly message: string;
+    readonly retryAfter: string;
+};
+/**
+ * One limit, with what it allows, what has been used, and when that changes — #183.
+ *
+ * Shaped for rendering: the window as words rather than a union to switch on, the scope as a word rather than an
+ * optional id to test for presence, and the fraction computed once here rather than in every client.
+ */
+export type QuotaExplanation = {
+    readonly window: string;
+    readonly modelId?: string;
+    readonly scope: "workspace" | "personal";
+    readonly resetsAt: string;
+    /** The sentence a refusal would use — "It resets at T", or the sliding-window wording. Empty when neither. */
+    readonly resetNote: string;
+    readonly dimensions: readonly {
+        readonly dimension: QuotaDimension;
+        readonly limit: number;
+        readonly used: number;
+        readonly fraction: number;
+    }[];
+};
+export type QuotaWarning = {
+    readonly dimension: QuotaDimension;
+    readonly limit: number;
+    readonly used: number;
+    readonly fraction: number;
+    /** Present when the limit is scoped to one model — #182. */
+    readonly modelId?: string;
+    readonly message: string;
+};
+/**
+ * Told when a tenant crosses a warning threshold.
+ *
+ * A sink of its own rather than a `RunEvent`, because a `RunEvent` carries a `runId` and a quota warning fires
+ * *before* a run exists — which is the whole point of warning at admission. Squeezing it into the run stream
+ * would mean inventing a run id for an event about not starting one.
+ */
+export interface QuotaObserver {
+    onWarning(context: ExecutionContext, warning: QuotaWarning): Promise<void> | void;
+    onRefusal?(context: ExecutionContext, refusal: Extract<QuotaDecision, {
+        admitted: false;
+    }>): Promise<void> | void;
+}
+/**
+ * What is being admitted, beyond who is asking — #182.
+ *
+ * The model belongs here rather than on `ExecutionContext`: the context is who and where, and a per-model limit
+ * is about *what this run will use*. Two runs by the same person in the same workspace can be subject to
+ * different limits, which is not something an identity can express.
+ *
+ * Absent `modelId` means model-scoped limits do not apply. That is the safe direction for a *check* — it cannot
+ * refuse the wrong work — and the caller that knows the model is the one that must say so.
+ */
+export type QuotaSubject = {
+    readonly at?: string;
+    readonly modelId?: string;
+};
+export type QuotaGuardDeps = {
+    readonly rollups: UsageRollupStore;
+    /**
+     * The limits for this tenant, or undefined for unlimited.
+     *
+     * A function rather than a value: limits are per tenant and change without a redeploy, and a value captured
+     * at construction would be the limits of whoever booted the process.
+     */
+    /**
+     * **Every** limit that applies, shortest span first — widened from a single limit by #182.
+     *
+     * A list rather than one, because a person is subject to several at once and all of them bind: a five-hour
+     * cap, a monthly cap, a per-model cap. Returning the most specific one meant the others were configured,
+     * visible and unenforced. An empty list is unbounded.
+     */
+    readonly resolveLimits: (context: ExecutionContext, about: QuotaSubject) => Promise<readonly QuotaLimits[]> | readonly QuotaLimits[];
+    /**
+     * The ledger, needed **only** for a rolling window (#181) — rollups are calendar buckets and cannot answer an
+     * arbitrary interval.
+     *
+     * Optional, so a deployment with only calendar limits wires nothing new. A rolling limit configured without it
+     * throws at admission with a message naming the missing piece, rather than admitting the run: a spend guard
+     * that cannot read spend must not be the thing that says yes.
+     */
+    readonly usage?: Pick<UsageStore, "totalsBetween">;
+    readonly observer?: QuotaObserver;
+    readonly clock?: () => string;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+};
+export declare const createQuotaGuard: (deps: QuotaGuardDeps) => {
+    /**
+     * Decide whether a run may start — AC-2.
+     *
+     * Reads the current period's rollup, not the ledger: admission is on the hot path of every message, and a
+     * check that scanned raw events would make the platform slower in proportion to how much it had been used.
+     */
+    admit(context: ExecutionContext, about?: QuotaSubject): Promise<QuotaDecision>;
+    /**
+     * The limits in force for this context — an empty list for unlimited.
+     *
+     * Exposed so a UI can render "you have used X of Y" without a second source for Y — a panel that took its
+     * limit from configuration while enforcement took it from here would eventually disagree, and the version a
+     * user sees would be the wrong one.
+     */
+    limits(context: ExecutionContext, about?: QuotaSubject): Promise<readonly QuotaLimits[]>;
+    /**
+     * Every limit with its usage and its reset — #183.
+     *
+     * A limit nobody can see is a limit that surprises people, and once several apply at once "how much have I
+     * got left" stops being answerable by reading one number. This is the same `read` the refusal path uses, so
+     * a panel cannot disagree with enforcement about either the figure or the reset time — the failure that a
+     * second implementation of "how full is it" always eventually produces.
+     *
+     * Ordered as the resolver ordered them, shortest span first, which puts the limit most likely to stop you at
+     * the top without the caller having to sort by anything.
+     */
+    explain(context: ExecutionContext, about?: QuotaSubject): Promise<readonly QuotaExplanation[]>;
+    /** Throws the refusal, for a caller that would rather not branch. Same decision, different ergonomics. */
+    assertAdmitted(context: ExecutionContext, about?: QuotaSubject): Promise<QuotaDecision>;
+};
+export type QuotaGuard = ReturnType<typeof createQuotaGuard>;
+/**
+ * `resolveLimits` backed by the admin-configured store — #175.
+ *
+ * The guard already took `resolveLimits` as a function so limits could change without a redeploy. What was
+ * missing was anything to resolve them *from*: every deployment had to hardcode them, which is not a
+ * configuration.
+ *
+ * **Per-person first, tenant default second, unbounded last.** The store decides which row applies; this decides
+ * what to do when a person has no override — and it deliberately does *not* fall back to checking the tenant
+ * default against the person's own usage. That would compare a tenant-sized allowance to one person's spend, so
+ * nobody would ever hit it and the limit would silently do nothing.
+ *
+ * So the resolved limit carries the grain it was configured at, and the guard reads the matching rollup. A limit
+ * and the usage it is compared against have to be the same shape, and this is the one place that can guarantee
+ * it.
+ */
+export declare const createStoredLimitResolver: (deps: {
+    readonly limits: UsageLimitStore;
+}) => (context: ExecutionContext, about?: QuotaSubject) => Promise<readonly QuotaLimits[]>;
+/**
+ * The order periods are considered in, shortest first.
+ *
+ * Shortest first because a shorter window is the tighter constraint in practice: someone with a monthly
+ * allowance who has burned it in a day is stopped by the daily limit a day earlier, and being stopped early is
+ * recoverable where a surprise at month end is not. It is a default, and a deployment that disagrees passes its
+ * own order.
+ */
+export declare const PERIOD_PRECEDENCE: readonly RollupPeriod[];
+//# sourceMappingURL=quota.d.ts.map