@theokit/sdk-budget 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,191 @@
+import { BudgetTracker } from '@theokit/sdk';
+
+/**
+ * UTC-aligned calendar window helpers (ADR D382).
+ *
+ * - `1h` — relative (now - 1 hour).
+ * - `1d` — UTC midnight (current UTC day).
+ * - `1w` — UTC monday 00:00:00 (current UTC week, Monday is week start).
+ * - `30d` — relative 30 days.
+ * - `365d` — relative 365 days.
+ *
+ * `1d` and `1w` are calendar-aligned because users expect "1 USD per day"
+ * = "since midnight UTC", not a rolling 24h.
+ * `30d`/`365d` are relative because nobody expects "since the 1st".
+ *
+ * @internal
+ */
+declare function startOfDayUtc(now?: Date): Date;
+declare function startOfWeekUtc(now?: Date): Date;
+/** Returns the inclusive start timestamp (ms) for the given window relative to `now`. */
+declare function windowStartMs(window: BudgetWindow, now?: Date): number;
+
+/**
+ * Budget enforcement (ADRs D383, D386, EC-7/8/9).
+ *
+ * - `preflightCheck(name, estimatedUsd)` — em `block` mode, throw
+ *   `BudgetExceededError` antes da LLM call se qualquer limit seria
+ *   excedido (EC-9 — caller chama dentro do mutex section).
+ * - `chargeAndCheckThresholds(name, actualUsd)` — apply charge ao
+ *   ledger + invoca onThreshold/onExceed callbacks isolated em
+ *   try/catch (EC-8).
+ *
+ * @internal
+ */
+/**
+ * Throws BudgetExceededError if `mode === "block"` and any limit
+ * would be exceeded. No-op for audit/warn modes (post-charge checks
+ * handle those).
+ *
+ * Caller invokes this BEFORE the LLM call.
+ */
+declare function preflightCheck(name: string, estimatedUsd: number): void;
+/**
+ * Charge the budget + dispatch threshold/exceed callbacks (EC-8 isolated).
+ *
+ * - 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).
+ */
+declare function chargeAndCheckThresholds(name: string, actualUsd: number): Promise<void>;
+
+/**
+ * In-process Budget ledger (ADR D385).
+ *
+ * Singleton mutex-protected. Stores per-budget ChargeLog[] arrays;
+ * `spentIn(window)` filters by timestamp.
+ *
+ * EC-6: GC eviction runs DENTRO do mesmo mutex que charge — sem race.
+ * EC-9: charge() é called inside same critical section as preflight
+ * check by Budget enforcement.
+ *
+ * Persistence cross-restart: deferred to v0.2 (JsonFile pattern).
+ *
+ * @internal
+ */
+/** Charge a budget. Idempotent across concurrent calls via withCwdMutex. */
+declare function charge(name: string, amountUsd: number): Promise<void>;
+/** Return total spend in the given window for `name`. Snapshot read (no mutex needed). */
+declare function spentIn(name: string, window: BudgetWindow, now?: Date): number;
+
+/**
+ * normalizeUsage — convert provider-shaped raw `usage` object to
+ * canonical `TokenUsage`. Ports Hermes Agent's `normalize_usage`
+ * (referencia/hermes-agent/agent/usage_pricing.py:672-742).
+ *
+ * Handles 3 API shapes:
+ *   - Anthropic Messages: 4 explicit buckets (input/output/cache_read/cache_creation).
+ *   - OpenAI Chat Completions: prompt_tokens INCLUDES cache; subtract cached_tokens.
+ *   - OpenAI Responses (Codex): input_tokens INCLUDES cache; same subtraction.
+ *
+ * Edge cases:
+ *   - cline#10266 — OpenAI-compat proxies (OpenRouter, Vercel AI Gateway,
+ *     Cline) routing Claude expose Anthropic-style top-level fields
+ *     (cache_read_input_tokens / cache_creation_input_tokens). Both
+ *     locations are checked with top-level fallback.
+ *   - Null/undefined fields → 0 via `int()` coerce.
+ *   - String token counts → parsed via int.
+ *   - Negative values → clamped to 0 (defensive against proxy bugs).
+ *
+ * @internal
+ */
+type ApiMode = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+declare function inferApiMode(provider: string): ApiMode;
+declare function normalizeUsage(rawUsage: unknown, opts: {
+    provider: string;
+    apiMode?: ApiMode;
+}): TokenUsage;
+
+/**
+ * Internal Budget registry — keeps live `BudgetOptions` per name.
+ * Singleton; no persistence (D385).
+ *
+ * @internal
+ */
+declare function createBudget(opts: BudgetOptions): BudgetHandle;
+declare function getBudget(name: string): BudgetHandle | undefined;
+declare function listBudgets(): readonly BudgetHandle[];
+declare function deleteBudget(name: string): boolean;
+declare function snapshotAll(): readonly BudgetSnapshot[];
+declare function getBudgetOptionsRaw(name: string): BudgetOptions | undefined;
+declare function defaultMode(opts: BudgetOptions): BudgetMode;
+
+/**
+ * Built-in per-model USD pricing table (SDK 2.0 Phase 2 / sdk-budget T2.X).
+ *
+ * Prices are in USD per 1M tokens (input / output). Sources: each
+ * provider's public pricing page; values verified 2026-06 against
+ * the same tier used in sdk-core's `internal/budget/pricing-data.json`.
+ *
+ * The table is intentionally CONSERVATIVE — only the most-used models
+ * land here. Consumers needing exhaustive coverage can supply an
+ * override via `createUsdBudgetTracker({ pricing })`.
+ *
+ * @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. */
+declare const BUILTIN_PRICING: Readonly<Record<string, ModelPricing>>;
+/**
+ * Compute USD cost for a single token event. Returns 0 (NOT throws)
+ * when the model is unknown — consumers should override the pricing
+ * table to add their model.
+ */
+declare function computeUsdCost(pricing: Readonly<Record<string, ModelPricing>>, model: string, type: "input" | "output", tokens: number): number;
+
+/**
+ * `createUsdBudgetTracker` — USD-cost-aware `BudgetTracker` impl shipped
+ * in `@theokit/sdk-budget` (SDK 2.0 Phase 2 / T2.X).
+ *
+ * Extends the counter pattern from `createCounterBudgetTracker`
+ * (sdk-core reference impl) with per-model USD cost computation via
+ * the `BUILTIN_PRICING` table.
+ *
+ * Use cases:
+ *   - Cap total spend per agent run (`maxUsd`).
+ *   - Cap total tokens (`maxTokens`) AND USD ceiling simultaneously.
+ *   - Observe cumulative USD from outside (`getTotalUsd()`).
+ *
+ * Tracker.check() returns `allowed: false` when ANY of the configured
+ * caps is exceeded. `reason` is one of:
+ *   - `"token_limit"` — `maxTokens` reached
+ *   - `"cost_limit"`  — `maxUsd` reached
+ *
+ * Layered design (mirrors counter impl):
+ *   - `track()` is sync + non-throwing (clamps invalid values).
+ *   - `check()` is sync (allowed: true unless a cap is exceeded).
+ *   - `getTotal()` returns the SDK-required token + iteration totals
+ *     ONLY (USD is exposed via the bonus `getTotalUsd()` method).
+ *
+ * @public
+ */
+
+/** Options for `createUsdBudgetTracker`. */
+interface UsdBudgetTrackerOptions {
+    /** Hard ceiling on total tokens (input + output combined). */
+    readonly maxTokens?: number;
+    /** Hard ceiling on cumulative USD spend. */
+    readonly maxUsd?: number;
+    /** Optional override map — model id → pricing entry. Merged onto BUILTIN_PRICING. */
+    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.
+ */
+declare function createUsdBudgetTracker(options?: UsdBudgetTrackerOptions): BudgetTracker & {
+    nextIteration(): void;
+    getTotalUsd(): number;
+};
+
+export { BUILTIN_PRICING, type ModelPricing, type UsdBudgetTrackerOptions, charge, chargeAndCheckThresholds, computeUsdCost, createBudget, createUsdBudgetTracker, defaultMode, deleteBudget, getBudget, getBudgetOptionsRaw, inferApiMode, listBudgets, normalizeUsage, preflightCheck, snapshotAll, spentIn, startOfDayUtc, startOfWeekUtc, windowStartMs };

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+import { BudgetTracker } from '@theokit/sdk';
+
+/**
+ * UTC-aligned calendar window helpers (ADR D382).
+ *
+ * - `1h` — relative (now - 1 hour).
+ * - `1d` — UTC midnight (current UTC day).
+ * - `1w` — UTC monday 00:00:00 (current UTC week, Monday is week start).
+ * - `30d` — relative 30 days.
+ * - `365d` — relative 365 days.
+ *
+ * `1d` and `1w` are calendar-aligned because users expect "1 USD per day"
+ * = "since midnight UTC", not a rolling 24h.
+ * `30d`/`365d` are relative because nobody expects "since the 1st".
+ *
+ * @internal
+ */
+declare function startOfDayUtc(now?: Date): Date;
+declare function startOfWeekUtc(now?: Date): Date;
+/** Returns the inclusive start timestamp (ms) for the given window relative to `now`. */
+declare function windowStartMs(window: BudgetWindow, now?: Date): number;
+
+/**
+ * Budget enforcement (ADRs D383, D386, EC-7/8/9).
+ *
+ * - `preflightCheck(name, estimatedUsd)` — em `block` mode, throw
+ *   `BudgetExceededError` antes da LLM call se qualquer limit seria
+ *   excedido (EC-9 — caller chama dentro do mutex section).
+ * - `chargeAndCheckThresholds(name, actualUsd)` — apply charge ao
+ *   ledger + invoca onThreshold/onExceed callbacks isolated em
+ *   try/catch (EC-8).
+ *
+ * @internal
+ */
+/**
+ * Throws BudgetExceededError if `mode === "block"` and any limit
+ * would be exceeded. No-op for audit/warn modes (post-charge checks
+ * handle those).
+ *
+ * Caller invokes this BEFORE the LLM call.
+ */
+declare function preflightCheck(name: string, estimatedUsd: number): void;
+/**
+ * Charge the budget + dispatch threshold/exceed callbacks (EC-8 isolated).
+ *
+ * - 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).
+ */
+declare function chargeAndCheckThresholds(name: string, actualUsd: number): Promise<void>;
+
+/**
+ * In-process Budget ledger (ADR D385).
+ *
+ * Singleton mutex-protected. Stores per-budget ChargeLog[] arrays;
+ * `spentIn(window)` filters by timestamp.
+ *
+ * EC-6: GC eviction runs DENTRO do mesmo mutex que charge — sem race.
+ * EC-9: charge() é called inside same critical section as preflight
+ * check by Budget enforcement.
+ *
+ * Persistence cross-restart: deferred to v0.2 (JsonFile pattern).
+ *
+ * @internal
+ */
+/** Charge a budget. Idempotent across concurrent calls via withCwdMutex. */
+declare function charge(name: string, amountUsd: number): Promise<void>;
+/** Return total spend in the given window for `name`. Snapshot read (no mutex needed). */
+declare function spentIn(name: string, window: BudgetWindow, now?: Date): number;
+
+/**
+ * normalizeUsage — convert provider-shaped raw `usage` object to
+ * canonical `TokenUsage`. Ports Hermes Agent's `normalize_usage`
+ * (referencia/hermes-agent/agent/usage_pricing.py:672-742).
+ *
+ * Handles 3 API shapes:
+ *   - Anthropic Messages: 4 explicit buckets (input/output/cache_read/cache_creation).
+ *   - OpenAI Chat Completions: prompt_tokens INCLUDES cache; subtract cached_tokens.
+ *   - OpenAI Responses (Codex): input_tokens INCLUDES cache; same subtraction.
+ *
+ * Edge cases:
+ *   - cline#10266 — OpenAI-compat proxies (OpenRouter, Vercel AI Gateway,
+ *     Cline) routing Claude expose Anthropic-style top-level fields
+ *     (cache_read_input_tokens / cache_creation_input_tokens). Both
+ *     locations are checked with top-level fallback.
+ *   - Null/undefined fields → 0 via `int()` coerce.
+ *   - String token counts → parsed via int.
+ *   - Negative values → clamped to 0 (defensive against proxy bugs).
+ *
+ * @internal
+ */
+type ApiMode = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+declare function inferApiMode(provider: string): ApiMode;
+declare function normalizeUsage(rawUsage: unknown, opts: {
+    provider: string;
+    apiMode?: ApiMode;
+}): TokenUsage;
+
+/**
+ * Internal Budget registry — keeps live `BudgetOptions` per name.
+ * Singleton; no persistence (D385).
+ *
+ * @internal
+ */
+declare function createBudget(opts: BudgetOptions): BudgetHandle;
+declare function getBudget(name: string): BudgetHandle | undefined;
+declare function listBudgets(): readonly BudgetHandle[];
+declare function deleteBudget(name: string): boolean;
+declare function snapshotAll(): readonly BudgetSnapshot[];
+declare function getBudgetOptionsRaw(name: string): BudgetOptions | undefined;
+declare function defaultMode(opts: BudgetOptions): BudgetMode;
+
+/**
+ * Built-in per-model USD pricing table (SDK 2.0 Phase 2 / sdk-budget T2.X).
+ *
+ * Prices are in USD per 1M tokens (input / output). Sources: each
+ * provider's public pricing page; values verified 2026-06 against
+ * the same tier used in sdk-core's `internal/budget/pricing-data.json`.
+ *
+ * The table is intentionally CONSERVATIVE — only the most-used models
+ * land here. Consumers needing exhaustive coverage can supply an
+ * override via `createUsdBudgetTracker({ pricing })`.
+ *
+ * @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. */
+declare const BUILTIN_PRICING: Readonly<Record<string, ModelPricing>>;
+/**
+ * Compute USD cost for a single token event. Returns 0 (NOT throws)
+ * when the model is unknown — consumers should override the pricing
+ * table to add their model.
+ */
+declare function computeUsdCost(pricing: Readonly<Record<string, ModelPricing>>, model: string, type: "input" | "output", tokens: number): number;
+
+/**
+ * `createUsdBudgetTracker` — USD-cost-aware `BudgetTracker` impl shipped
+ * in `@theokit/sdk-budget` (SDK 2.0 Phase 2 / T2.X).
+ *
+ * Extends the counter pattern from `createCounterBudgetTracker`
+ * (sdk-core reference impl) with per-model USD cost computation via
+ * the `BUILTIN_PRICING` table.
+ *
+ * Use cases:
+ *   - Cap total spend per agent run (`maxUsd`).
+ *   - Cap total tokens (`maxTokens`) AND USD ceiling simultaneously.
+ *   - Observe cumulative USD from outside (`getTotalUsd()`).
+ *
+ * Tracker.check() returns `allowed: false` when ANY of the configured
+ * caps is exceeded. `reason` is one of:
+ *   - `"token_limit"` — `maxTokens` reached
+ *   - `"cost_limit"`  — `maxUsd` reached
+ *
+ * Layered design (mirrors counter impl):
+ *   - `track()` is sync + non-throwing (clamps invalid values).
+ *   - `check()` is sync (allowed: true unless a cap is exceeded).
+ *   - `getTotal()` returns the SDK-required token + iteration totals
+ *     ONLY (USD is exposed via the bonus `getTotalUsd()` method).
+ *
+ * @public
+ */
+
+/** Options for `createUsdBudgetTracker`. */
+interface UsdBudgetTrackerOptions {
+    /** Hard ceiling on total tokens (input + output combined). */
+    readonly maxTokens?: number;
+    /** Hard ceiling on cumulative USD spend. */
+    readonly maxUsd?: number;
+    /** Optional override map — model id → pricing entry. Merged onto BUILTIN_PRICING. */
+    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.
+ */
+declare function createUsdBudgetTracker(options?: UsdBudgetTrackerOptions): BudgetTracker & {
+    nextIteration(): void;
+    getTotalUsd(): number;
+};
+
+export { BUILTIN_PRICING, type ModelPricing, type UsdBudgetTrackerOptions, charge, chargeAndCheckThresholds, computeUsdCost, createBudget, createUsdBudgetTracker, defaultMode, deleteBudget, getBudget, getBudgetOptionsRaw, inferApiMode, listBudgets, normalizeUsage, preflightCheck, snapshotAll, spentIn, startOfDayUtc, startOfWeekUtc, windowStartMs };