@theokit/sdk-budget 0.3.2 → 0.3.3

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BudgetTracker } from '@theokit/sdk';
+import { BudgetMode, BudgetSnapshot, BudgetHandle, BudgetOptions, TokenUsage, BudgetWindow, BudgetTracker } from '@theokit/sdk';
 
 /**
  * M7-6 — honest-null cost render helper. Turns the `number | undefined` cost
@@ -38,9 +38,35 @@ declare function formatCostUsd(cost: number | undefined, opts?: FormatCostUsdOpt
  *
  * @internal
  */
+/**
+ * Midnight UTC of `now`'s day — the start of a `1d` budget window.
+ *
+ * Always UTC, never the host's local timezone: "1 USD per day" resets at 00:00Z, so a budget in
+ * UTC-05:00 resets at 19:00 local. That is deliberate — a budget shared by processes in different
+ * regions must reset at one instant — but it surprises anyone reading a daily total at local
+ * midnight.
+ */
 declare function startOfDayUtc(now?: Date): Date;
+/**
+ * Midnight UTC on the MONDAY of `now`'s week — the start of a `1w` budget window.
+ *
+ * ISO 8601, so the week starts on Monday, not Sunday. This is calendar-aligned rather than rolling:
+ * "5 USD per week" resets on Monday, which is what a person reading a weekly budget expects, and not
+ * a trailing 168 hours. `30d` and `365d` are relative for the mirror-image reason — nobody expects a
+ * monthly budget to reset on the 1st.
+ */
 declare function startOfWeekUtc(now?: Date): Date;
-/** Returns the inclusive start timestamp (ms) for the given window relative to `now`. */
+/**
+ * Inclusive start timestamp (ms) of `window`, as `spentIn` uses it to decide which charges count.
+ *
+ * Two different behaviours behind one enum, and the difference is visible in every total:
+ *
+ * - `1d` / `1w` are CALENDAR-aligned to UTC (midnight; ISO Monday). Spend resets at a boundary.
+ * - `1h` / `30d` / `365d` are ROLLING — `now` minus the duration. Nothing ever "resets"; the
+ *   oldest charges simply fall out of the window.
+ *
+ * Throws on a value outside `BudgetWindow`, which TypeScript already prevents.
+ */
 declare function windowStartMs(window: BudgetWindow, now?: Date): number;
 
 /**
@@ -56,23 +82,47 @@ declare function windowStartMs(window: BudgetWindow, now?: Date): number;
  * @internal
  */
 /**
- * Throws BudgetExceededError if `mode === "block"` and any limit
- * would be exceeded. No-op for audit/warn modes (post-charge checks
- * handle those).
+ * Refuse an upcoming call that would push a `"block"`-mode budget past one of its limits. Call it
+ * BEFORE the LLM request, with your cost estimate for that request.
  *
- * Caller invokes this BEFORE the LLM call.
+ * Throws `BudgetExceededError` (carrying `budgetName`, `window`, the projected `spentUsd`, the
+ * `limitUsd` and `mode: "block"`) for the FIRST limit where `alreadySpent + estimatedUsd` exceeds
+ * the limit. The comparison is strict, so landing exactly on the limit is allowed through — while
+ * the post-charge `onExceed` callback fires at `>=`. The two boundaries do not agree.
+ *
+ * SILENTLY DOES NOTHING in three cases, and none of them is distinguishable from "you are within
+ * budget" at the call site:
+ *
+ * - `name` is not registered — a typo, or a budget deleted since. Nothing is enforced.
+ * - the budget's mode is `"warn"` or `"audit"` — those never block by design.
+ * - the estimate is low. Enforcement is only as good as `estimatedUsd`; passing 0 disables it.
  */
 declare function preflightCheck(name: string, estimatedUsd: number): void;
 /**
- * Charge the budget + dispatch threshold/exceed callbacks (EC-8 isolated).
+ * Record the ACTUAL cost of a completed call against a budget and fire its callbacks. Call it after
+ * the LLM request, paired with `preflightCheck` before it.
+ *
+ * NEVER THROWS on budget state — including when the charge tips a limit. Enforcement happens on the
+ * next `preflightCheck`; this one only records and notifies. A callback that throws is caught and
+ * logged to stderr, so your `onThreshold` / `onExceed` cannot break the run either.
+ *
+ * Per mode:
+ *
+ * - `"audit"` — charge only, no callbacks.
+ * - `"warn"` — charge, then `onThreshold` at 80% or 95%, then `onExceed` at 100%. With no
+ *   `onExceed` handler it writes a line to stderr instead.
  *
- * - In `audit` mode: charge only, no callbacks.
- * - In `warn` mode: charge + onThreshold (80/95) + onExceed (100). No throw.
- * - In `block` mode: charge + onThreshold + onExceed. No throw post-call
- *   (preflightCheck already prevented exceed for the upcoming call;
- *   this protects against simultaneous-call races where multiple sends
- *   each pass preflight independently — last one to charge may still
- *   tip a limit. We document the case rather than retroactively throw).
+ * Per limit, exactly ONE callback fires per call: the highest matched threshold, or `onExceed`,
+ * never both. But there is NO de-duplication across calls — a budget sitting at 90% fires
+ * `onThreshold(0.8)` again on every single charge, and one past its limit fires `onExceed` on
+ * every charge forever. Debounce inside your handler if it pages anyone. A budget with three
+ * limits evaluates all three, so one call can fire three callbacks.
+ * - `"block"` — same callbacks as `"warn"`, still no throw. Concurrent sends each pass their own
+ *   preflight, so the last to charge can legitimately tip a limit that preflight had cleared.
+ *
+ * A DELETED OR UNKNOWN BUDGET LOSES THE CHARGE. The function writes a warning to stderr and
+ * returns — the spend is not recorded anywhere, so a budget removed mid-flight under-reports rather
+ * than over-reports. This is the one path where the ledger and reality diverge on purpose.
  */
 declare function chargeAndCheckThresholds(name: string, actualUsd: number): Promise<void>;
 
@@ -90,9 +140,40 @@ declare function chargeAndCheckThresholds(name: string, actualUsd: number): Prom
  *
  * @internal
  */
-/** Charge a budget. Idempotent across concurrent calls via withCwdMutex. */
+/**
+ * Append `amountUsd` to the spend ledger for the budget called `name`, timestamped now.
+ *
+ * NOT idempotent. `withCwdMutex` SERIALIZES concurrent calls so two appends cannot interleave; it
+ * does not deduplicate them. Calling this twice with the same arguments records the spend twice,
+ * and there is no charge id to reconcile against — an at-least-once caller needs its own guard.
+ *
+ * NOT VALIDATED against the registry either: charging a name that was never passed to
+ * `createBudget` (a typo, say) succeeds silently and accumulates spend that no limit enforces and
+ * that `snapshotAll` — which iterates the REGISTRY — will never show.
+ *
+ * `chargeAndCheckThresholds` does not rescue you from that, and swapping to it trades one silent
+ * failure for another: on an unknown or already-deleted name it writes one line to stderr and
+ * RETURNS WITHOUT CHARGING, so the spend is lost rather than merely invisible. Neither function
+ * throws. Validate the name against `getBudgetOptionsRaw` / `getBudget` if it matters which of the
+ * two failures you get.
+ *
+ * `amountUsd <= 0` is a no-op, so a refund cannot be expressed here.
+ *
+ * The ledger is a MODULE-LEVEL SINGLETON: process-wide, shared by every budget and every agent in
+ * the process, and lost on exit — there is no persistence across restarts. Entries older than a
+ * year are garbage-collected opportunistically.
+ */
 declare function charge(name: string, amountUsd: number): Promise<void>;
-/** Return total spend in the given window for `name`. Snapshot read (no mutex needed). */
+/**
+ * Total USD recorded for `name` inside `window`, summed at call time.
+ *
+ * Returns `0` for a name that was never charged — indistinguishable from a budget that exists and
+ * has spent nothing. Use `getBudget(name)` when you need to tell those apart.
+ *
+ * Lock-free: it reads the live array without taking the mutex, so a charge landing mid-read is
+ * simply included or not. Window boundaries are those of {@link windowStartMs} — `1d` and `1w` are
+ * UTC calendar-aligned, the rest are rolling.
+ */
 declare function spentIn(name: string, window: BudgetWindow, now?: Date): number;
 
 /**
@@ -117,7 +198,34 @@ declare function spentIn(name: string, window: BudgetWindow, now?: Date): number
  * @internal
  */
 type ApiMode = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+/**
+ * Which usage dialect a provider reports in, inferred from its name.
+ *
+ * Providers do not agree on the shape of a usage object: Anthropic reports `input_tokens` /
+ * `output_tokens`, OpenAI's Responses API reports yet another, and the large
+ * OpenAI-chat-compatible family (openai, openrouter, deepseek, google, ollama, lmstudio, …) shares
+ * one. This maps a provider name onto that choice.
+ *
+ * UNKNOWN NAMES FALL BACK to the OpenAI chat-completions shape, because that is what almost every
+ * compatible endpoint speaks — a new proxy usually works without a change here. Pass
+ * {@link normalizeUsage}'s `apiMode` explicitly when a provider is compatible in its wire format but
+ * not in its name.
+ */
 declare function inferApiMode(provider: string): ApiMode;
+/**
+ * Turn a provider's raw usage object into the SDK's canonical {@link TokenUsage}.
+ *
+ * NEVER THROWS, and that is the point: usage arrives from a third party at the end of a successful
+ * call, so a missing or malformed field must not fail a request the model already answered. `null`,
+ * `undefined` and non-objects all yield an all-zero usage, and unrecognised fields are dropped.
+ *
+ * The cost of that tolerance is that a zero is ambiguous — it means "the provider reported nothing
+ * usable" as readily as "no tokens". A budget that suddenly stops accruing is the symptom of a
+ * dialect mismatch, not of free traffic.
+ *
+ * `apiMode` overrides the guess {@link inferApiMode} makes from the provider name; supply it for a
+ * compatible endpoint whose name is not recognised.
+ */
 declare function normalizeUsage(rawUsage: unknown, opts: {
     provider: string;
     apiMode?: ApiMode;
@@ -129,12 +237,81 @@ declare function normalizeUsage(rawUsage: unknown, opts: {
  *
  * @internal
  */
+/**
+ * Register a budget under `opts.name` and return its live handle.
+ *
+ * ```ts
+ * const b = createBudget({ name: "daily", mode: "block", limits: [{ window: "1d", limitUsd: 5 }] });
+ * ```
+ *
+ * THROWS `ConfigurationError(code: "invalid_budget_name")` in two cases: a name that does not match
+ * `^[a-z0-9][a-z0-9_-]*$` (lowercase only — `"Daily"` and `"my.budget"` are rejected), and a name
+ * already registered. Duplicate registration is deliberately an error rather than an idempotent
+ * return, so a second `createBudget("daily", …)` with different limits cannot silently win.
+ *
+ * Registering does NOT reset spend. The ledger is keyed by NAME and outlives the registry entry, so
+ * re-creating a budget after `deleteBudget` inherits everything charged under that name — a
+ * config reload keeps enforcing the day's spend, which is usually right and is a surprise if you
+ * expected a fresh start.
+ *
+ * Process-local and non-persistent: nothing survives a restart, so re-create budgets at startup.
+ * `mode` defaults to `"warn"` (see {@link defaultMode}) — a budget created without one observes and
+ * does not block.
+ */
 declare function createBudget(opts: BudgetOptions): BudgetHandle;
+/**
+ * The live handle for a registered budget, or `undefined` when the name is unknown.
+ *
+ * `undefined` is the honest answer for "never created" — it does NOT mean "zero spend". A budget
+ * that exists but has not been charged returns a handle whose `spentIn(...)` is 0, and the two are
+ * different facts: the first means nothing is enforcing a limit.
+ *
+ * The registry is per-PROCESS and holds no persistence, so a fresh process starts with no budgets
+ * and no ledger. Re-create them at startup.
+ */
 declare function getBudget(name: string): BudgetHandle | undefined;
+/**
+ * Every budget registered in this process, in insertion order.
+ *
+ * Empty after a restart — see {@link getBudget} on process-local state. Use it to enumerate what is
+ * being enforced; use {@link snapshotAll} when you want the numbers rather than the handles.
+ */
 declare function listBudgets(): readonly BudgetHandle[];
+/**
+ * Remove a budget from the registry. Returns `false` when the name was not registered.
+ *
+ * This stops ENFORCEMENT; it does not refund or clear the ledger. Re-creating a budget under the
+ * same name inherits the spend already recorded for that name, which is usually what you want after
+ * a config reload and a surprise if you were expecting a reset.
+ */
 declare function deleteBudget(name: string): boolean;
+/**
+ * One row per budget PER WINDOW — a budget with three limits produces three rows, not one.
+ *
+ * `ratio` is `spentUsd / limitUsd`, and is 0 when the limit is 0 rather than `Infinity`, so a
+ * zero-limit budget does not poison a dashboard that sums or charts these. Spend is computed at call
+ * time from the ledger, counting only entries inside each window, so the same budget reports
+ * different numbers for `1d` and `30d`.
+ */
 declare function snapshotAll(): readonly BudgetSnapshot[];
+/**
+ * The stored {@link BudgetOptions} exactly as registered, or `undefined` when the name is unknown.
+ *
+ * Distinct from {@link getBudget}, which returns a HANDLE with live accessors. Use this when you
+ * need the configuration itself — the limits array, the callbacks, the declared mode — for example
+ * to render it or to re-register the same shape elsewhere.
+ *
+ * The object is the registry's own, held by reference: mutating it changes what the budget enforces
+ * without going through `Budget.create`, which is a bug waiting to happen. Copy before editing.
+ */
 declare function getBudgetOptionsRaw(name: string): BudgetOptions | undefined;
+/**
+ * The mode a budget enforces, resolving the omitted case to `"warn"`.
+ *
+ * `"warn"` fires the callbacks and lets the call through; `"block"` refuses it. The default is
+ * deliberate: a budget added for observability must not start rejecting traffic because someone
+ * forgot a field.
+ */
 declare function defaultMode(opts: BudgetOptions): BudgetMode;
 
 /**
@@ -150,13 +327,36 @@ declare function defaultMode(opts: BudgetOptions): BudgetMode;
  *
  * @public
  */
+/**
+ * The two rates needed to price one model, in USD per 1,000,000 tokens.
+ *
+ * List prices only — this package models no cached-input discount, no batch tier and no negotiated
+ * rate, so a cost computed here is an upper bound for anyone on a discount and simply wrong for a
+ * provider that bills per request.
+ *
+ * @public
+ */
 interface ModelPricing {
     /** USD per 1,000,000 input tokens. */
     readonly inputPerMillionUsd: number;
     /** USD per 1,000,000 output tokens. */
     readonly outputPerMillionUsd: number;
 }
-/** Built-in pricing table — exhaustive enough for v0.1; users supply overrides for niche models. */
+/**
+ * The nine models this package prices out of the box, keyed by the exact `model` string a
+ * `BudgetUsageEvent` carries: four OpenAI, three Anthropic, two Google.
+ *
+ * Lookup is exact-match. No prefix stripping, no aliasing, no fuzzy fallback — `"gpt-4o"` and
+ * `"openrouter/openai/gpt-4o"` both MISS the `"openai/gpt-4o"` entry, and a miss means unknown
+ * cost, which under a `maxUsd` cap denies the run. Pass overrides through
+ * `createUsdBudgetTracker({ pricing })` rather than expecting a match.
+ *
+ * Prices are a dated snapshot (verified 2026-06) of public list prices and DRIFT — treat a total
+ * derived from them as an estimate, not as a bill. `Object.freeze` here is shallow: the map cannot
+ * gain keys, but the `ModelPricing` objects inside it are mutable.
+ *
+ * @public
+ */
 declare const BUILTIN_PRICING: Readonly<Record<string, ModelPricing>>;
 /**
  * Compute USD cost for a single token event.
@@ -197,19 +397,71 @@ declare function computeUsdCost(pricing: Readonly<Record<string, ModelPricing>>,
  * @public
  */
 
-/** Options for `createUsdBudgetTracker`. */
+/**
+ * Options for {@link createUsdBudgetTracker}. Omitting all of them builds a tracker that counts and
+ * never denies.
+ *
+ * @public
+ */
 interface UsdBudgetTrackerOptions {
-    /** Hard ceiling on total tokens (input + output combined). */
+    /**
+     * Ceiling on total tokens, input and output combined. `check()` denies with
+     * `reason: "token_limit"` once the running total REACHES it (`>=`, not `>`).
+     */
     readonly maxTokens?: number;
-    /** Hard ceiling on cumulative USD spend. */
+    /**
+     * Ceiling on cumulative USD. `check()` denies with `reason: "cost_limit"` once the total reaches
+     * it.
+     *
+     * TRAP — setting this makes an UNPRICED MODEL DENY EVERYTHING. If any tracked event names a model
+     * absent from the pricing table, the total cost becomes permanently unknown, and a cap that
+     * cannot be verified fails CLOSED: every subsequent `check()` returns
+     * `{ allowed: false, reason: "cost_limit", detail: "cost unknown — …" }`. This is intentional
+     * (better than spending unbounded), but it means a model id that merely differs in spelling from
+     * a {@link BUILTIN_PRICING} key halts the agent. Supply `pricing` for anything not in that table,
+     * or leave `maxUsd` unset and gate on `maxTokens`.
+     */
     readonly maxUsd?: number;
-    /** Optional override map — model id → pricing entry. Merged onto BUILTIN_PRICING. */
+    /**
+     * Per-model prices, spread OVER {@link BUILTIN_PRICING} — so an entry here replaces a built-in of
+     * the same key, and built-ins you do not name are kept.
+     *
+     * Keys are matched EXACTLY against `BudgetUsageEvent.model`. There is no prefix, alias or
+     * provider-stripping logic: `"gpt-4o"` does not match the built-in `"openai/gpt-4o"`. Use the
+     * same id string you pass to `Agent.create({ model })`.
+     */
     readonly pricing?: Readonly<Record<string, ModelPricing>>;
 }
 /**
- * Build a fresh USD-aware tracker. The returned object exposes the
- * `BudgetTracker` contract PLUS `getTotalUsd()` + `nextIteration()`
- * helpers for explicit iteration counting.
+ * Build a `BudgetTracker` that caps an agent run on tokens, on USD, or on both.
+ *
+ * ```ts
+ * const agent = await Agent.create({
+ *   model: { id: "openai/gpt-4o-mini" },
+ *   budgetTracker: createUsdBudgetTracker({ maxUsd: 0.5 }),
+ * });
+ * ```
+ *
+ * The agent loop drives it: `track()` on every usage event, `nextIteration()` once per turn, and
+ * `check()` before each turn — a denial halts the loop. Everything is per-instance and in-memory,
+ * so one tracker is one run; reuse it across runs and the caps carry over.
+ *
+ * Three things a caller gets wrong here:
+ *
+ * - **`getTotal()` has no cost in it.** It returns `{ tokens, iterations }` only, and
+ *   `BudgetTotal.costUsd` is always `undefined` however much was spent. USD comes from the extra
+ *   `getTotalUsd()` on the returned object, which is `number | undefined` — `undefined` meaning
+ *   UNKNOWN, never zero.
+ * - **Unknown cost is a one-way door.** The first event naming a model outside the pricing table
+ *   makes `getTotalUsd()` `undefined` for the rest of the run; a later priced event does not
+ *   restore it. Combined with `maxUsd`, that also denies every later `check()` — see
+ *   {@link UsdBudgetTrackerOptions.maxUsd}.
+ * - **There is no iteration cap.** `iterations` is counted and reported, and nothing ever gates on
+ *   it. Use `createCounterBudgetTracker` from `@theokit/sdk` when you need `maxIterations`.
+ *
+ * `check()` evaluates the cost cap first, so a run breaching both caps reports `"cost_limit"`.
+ * `track()` never throws and never rejects input — a non-finite or non-positive `tokens` is
+ * discarded, silently.
  */
 declare function createUsdBudgetTracker(options?: UsdBudgetTrackerOptions): BudgetTracker & {
     nextIteration(): void;