@aumos/agent-energy-budget 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,121 @@
+/**
+ * HTTP client for the agent-energy-budget service API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentEnergyBudgetClient } from "@aumos/agent-energy-budget";
+ *
+ * const client = createAgentEnergyBudgetClient({ baseUrl: "http://localhost:8095" });
+ *
+ * // Check current budget
+ * const budget = await client.getBudget("my-agent");
+ * if (budget.ok) {
+ *   console.log("Daily limit:", budget.data.daily_limit, "USD");
+ * }
+ *
+ * // Record a completed LLM call
+ * await client.trackCost({
+ *   agent_id: "my-agent",
+ *   model: "claude-haiku-4",
+ *   input_tokens: 2048,
+ *   output_tokens: 512,
+ * });
+ *
+ * // Predict cost before making an LLM call
+ * const forecast = await client.predictCost({
+ *   agent_id: "my-agent",
+ *   model: "gpt-4o-mini",
+ *   prompt_text: "Summarize the report.",
+ *   max_output_tokens: 256,
+ * });
+ * ```
+ */
+import type { ApiResult, Budget, CostEntry, ModelPricing, PredictCostRequest, SetBudgetLimitRequest, TokenUsage, UsageReport, WorkloadForecast } from "./types.js";
+/** Configuration options for the AgentEnergyBudgetClient. */
+export interface AgentEnergyBudgetClientConfig {
+    /** Base URL of the agent-energy-budget server (e.g. "http://localhost:8095"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-energy-budget service. */
+export interface AgentEnergyBudgetClient {
+    /**
+     * Retrieve the current budget configuration for an agent.
+     *
+     * Returns daily, weekly, and monthly limits alongside the configured
+     * degradation strategy, alert thresholds, and model preferences.
+     *
+     * @param agentId - The unique agent identifier.
+     * @returns The Budget configuration record for this agent.
+     */
+    getBudget(agentId: string): Promise<ApiResult<Budget>>;
+    /**
+     * Record the actual cost of a completed LLM call.
+     *
+     * Persists the call record to JSONL storage and fires any alert
+     * thresholds that have been crossed as a result of this spend.
+     *
+     * @param entry - Cost record with agent, model, token counts, and optional cost.
+     * @returns The persisted TokenUsage record with calculated cost_usd.
+     */
+    trackCost(entry: CostEntry): Promise<ApiResult<TokenUsage>>;
+    /**
+     * Predict the cost of an LLM call before it is executed.
+     *
+     * Uses the pricing tables and token estimation heuristics to return
+     * an upper-bound cost estimate with a confidence score.
+     *
+     * @param request - Prediction request with model, prompt text, and token cap.
+     * @returns WorkloadForecast with estimated tokens, cost, and confidence.
+     */
+    predictCost(request: PredictCostRequest): Promise<ApiResult<WorkloadForecast>>;
+    /**
+     * Update the budget limits for an agent.
+     *
+     * Supports updating daily, weekly, and monthly limits independently.
+     * Only fields provided in the request are modified; omitted fields retain
+     * their current values.
+     *
+     * @param request - Budget limit update payload.
+     * @returns The updated Budget configuration record.
+     */
+    setBudgetLimit(request: SetBudgetLimitRequest): Promise<ApiResult<Budget>>;
+    /**
+     * Retrieve a consolidated usage report for an agent across all periods.
+     *
+     * Returns daily, weekly, and monthly BudgetStatus snapshots plus a
+     * lifetime total spend.
+     *
+     * @param agentId - The unique agent identifier.
+     * @param options - Optional filter by period ("daily" | "weekly" | "monthly").
+     * @returns UsageReport with per-period snapshots and lifetime totals.
+     */
+    getUsageReport(agentId: string, options?: {
+        period?: "daily" | "weekly" | "monthly";
+    }): Promise<ApiResult<UsageReport>>;
+    /**
+     * Retrieve pricing information for a specific model.
+     *
+     * Supports fuzzy model name resolution including aliases (e.g. "haiku"
+     * resolves to "claude-haiku-4"). Returns null in the data field if the
+     * model cannot be resolved.
+     *
+     * @param model - Model identifier string (exact or alias).
+     * @returns ModelPricing with per-million token rates, tier, and context window.
+     */
+    getModelPricing(model: string): Promise<ApiResult<ModelPricing>>;
+}
+/**
+ * Create a typed HTTP client for the agent-energy-budget service.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentEnergyBudgetClient instance.
+ */
+export declare function createAgentEnergyBudgetClient(config: AgentEnergyBudgetClientConfig): AgentEnergyBudgetClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,MAAM,EACN,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,UAAU,EACV,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAMpB,6DAA6D;AAC7D,MAAM,WAAW,6BAA6B;IAC5C,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAEvD;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5D;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAE/E;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAE3E;;;;;;;;;OASG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;KAAE,GACpD,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAEnC;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;CAClE;AAMD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,6BAA6B,GACpC,uBAAuB,CAgFzB"}

package/dist/client.js

@@ -0,0 +1,129 @@
+/**
+ * HTTP client for the agent-energy-budget service API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentEnergyBudgetClient } from "@aumos/agent-energy-budget";
+ *
+ * const client = createAgentEnergyBudgetClient({ baseUrl: "http://localhost:8095" });
+ *
+ * // Check current budget
+ * const budget = await client.getBudget("my-agent");
+ * if (budget.ok) {
+ *   console.log("Daily limit:", budget.data.daily_limit, "USD");
+ * }
+ *
+ * // Record a completed LLM call
+ * await client.trackCost({
+ *   agent_id: "my-agent",
+ *   model: "claude-haiku-4",
+ *   input_tokens: 2048,
+ *   output_tokens: 512,
+ * });
+ *
+ * // Predict cost before making an LLM call
+ * const forecast = await client.predictCost({
+ *   agent_id: "my-agent",
+ *   model: "gpt-4o-mini",
+ *   prompt_text: "Summarize the report.",
+ *   max_output_tokens: 256,
+ * });
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-energy-budget service.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentEnergyBudgetClient instance.
+ */
+export function createAgentEnergyBudgetClient(config) {
+    const { baseUrl, timeoutMs = 30000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async getBudget(agentId) {
+            return fetchJson(`${baseUrl}/budgets/${encodeURIComponent(agentId)}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async trackCost(entry) {
+            return fetchJson(`${baseUrl}/costs`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(entry),
+            }, timeoutMs);
+        },
+        async predictCost(request) {
+            return fetchJson(`${baseUrl}/costs/predict`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async setBudgetLimit(request) {
+            return fetchJson(`${baseUrl}/budgets/${encodeURIComponent(request.agent_id)}/limits`, {
+                method: "PATCH",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async getUsageReport(agentId, options) {
+            const params = new URLSearchParams();
+            if (options?.period !== undefined) {
+                params.set("period", options.period);
+            }
+            const queryString = params.toString();
+            const url = queryString
+                ? `${baseUrl}/reports/${encodeURIComponent(agentId)}?${queryString}`
+                : `${baseUrl}/reports/${encodeURIComponent(agentId)}`;
+            return fetchJson(url, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async getModelPricing(model) {
+            return fetchJson(`${baseUrl}/pricing/${encodeURIComponent(model)}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-energy-budget
+ *
+ * TypeScript client for the AumOS agent-energy-budget service.
+ * Provides HTTP client and type definitions for token cost tracking,
+ * budget enforcement, cost prediction, and model pricing lookup.
+ */
+export type { AgentEnergyBudgetClient, AgentEnergyBudgetClientConfig } from "./client.js";
+export { createAgentEnergyBudgetClient } from "./client.js";
+export type { DegradationStrategy, ProviderName, ModelTier, AlertLevel, TokenUsage, AlertThresholds, ModelPreferences, Budget, BudgetStatus, CostEntry, ModelPricing, BudgetAlert, WorkloadForecast, PredictCostRequest, SetBudgetLimitRequest, ThrottleConfig, UsageReport, ApiError, ApiResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAG5D,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-energy-budget
+ *
+ * TypeScript client for the AumOS agent-energy-budget service.
+ * Provides HTTP client and type definitions for token cost tracking,
+ * budget enforcement, cost prediction, and model pricing lookup.
+ */
+export { createAgentEnergyBudgetClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,278 @@
+/**
+ * TypeScript interfaces for the agent-energy-budget service.
+ *
+ * Mirrors the Pydantic models and dataclasses defined in:
+ *   agent_energy_budget.budget.config
+ *   agent_energy_budget.budget.tracker
+ *   agent_energy_budget.budget.alerts
+ *   agent_energy_budget.pricing.tables
+ *   agent_energy_budget.estimator.cost_estimator
+ *
+ * All interfaces use readonly fields to match Python's frozen dataclasses.
+ */
+/**
+ * Action to take when a budget limit is approached or exceeded.
+ * Maps to DegradationStrategy enum in agent_energy_budget.budget.config.
+ */
+export type DegradationStrategy = "model_downgrade" | "token_reduction" | "block_with_error" | "cached_fallback";
+/**
+ * LLM provider identifier.
+ * Maps to ProviderName enum in agent_energy_budget.pricing.tables.
+ */
+export type ProviderName = "anthropic" | "openai" | "google" | "mistral" | "meta" | "deepseek" | "custom";
+/**
+ * Quality/cost tier classification for models.
+ * Maps to ModelTier enum in agent_energy_budget.pricing.tables.
+ *
+ * nano      — ultra-cheap, small context, fast
+ * efficient — good value, solid quality
+ * standard  — mainstream flagship-class models
+ * premium   — top capability, highest cost
+ */
+export type ModelTier = "nano" | "efficient" | "standard" | "premium";
+/**
+ * Alert severity level.
+ * Maps to AlertLevel enum in agent_energy_budget.budget.alerts.
+ */
+export type AlertLevel = "warning" | "critical" | "exhausted";
+/**
+ * Token consumption record for a single LLM call.
+ * Mirrors the _CallRecord internal dataclass in agent_energy_budget.budget.tracker.
+ */
+export interface TokenUsage {
+    /** Agent that made this call. */
+    readonly agent_id: string;
+    /** Model identifier used for this call. */
+    readonly model: string;
+    /** Number of input (prompt) tokens consumed. */
+    readonly input_tokens: number;
+    /** Number of output (completion) tokens generated. */
+    readonly output_tokens: number;
+    /** Actual cost in USD for this call. */
+    readonly cost_usd: number;
+    /** ISO-8601 UTC timestamp when this call was recorded. */
+    readonly recorded_at: string;
+}
+/**
+ * Alert threshold configuration as utilisation percentages.
+ * Maps to AlertThresholds in agent_energy_budget.budget.config.
+ */
+export interface AlertThresholds {
+    /** First alert threshold (default 50%). */
+    readonly warning: number;
+    /** Second alert threshold (default 80%). */
+    readonly critical: number;
+    /** Third alert threshold (default 100%). */
+    readonly exhausted: number;
+}
+/**
+ * Model selection preferences for degradation and estimation.
+ * Maps to ModelPreferences in agent_energy_budget.budget.config.
+ */
+export interface ModelPreferences {
+    /** Ordered list of model IDs to try first (most preferred first). */
+    readonly preferred_models: readonly string[];
+    /** Model to use when all others are exhausted or over budget. */
+    readonly fallback_model: string;
+    /** Model IDs that must never be used. */
+    readonly blocked_models: readonly string[];
+    /** When true, restrict model selection to vision-capable models only. */
+    readonly require_vision: boolean;
+}
+/**
+ * Top-level budget configuration for a single agent or agent group.
+ * Maps to BudgetConfig in agent_energy_budget.budget.config.
+ */
+export interface Budget {
+    /** Unique identifier for the agent this budget belongs to. */
+    readonly agent_id: string;
+    /** Maximum USD spend per calendar day (0 = disabled). */
+    readonly daily_limit: number;
+    /** Maximum USD spend per calendar week Mon-Sun (0 = disabled). */
+    readonly weekly_limit: number;
+    /** Maximum USD spend per calendar month (0 = disabled). */
+    readonly monthly_limit: number;
+    /** Strategy to apply when a limit is breached. */
+    readonly degradation_strategy: DegradationStrategy;
+    /** Utilisation percentage levels that trigger alerts. */
+    readonly alert_thresholds: AlertThresholds;
+    /** Model selection configuration for degradation. */
+    readonly model_preferences: ModelPreferences;
+    /** ISO currency code for display purposes (default "USD"). */
+    readonly currency: string;
+    /** Arbitrary key-value metadata attached to this budget. */
+    readonly tags: Readonly<Record<string, string>>;
+}
+/**
+ * Snapshot of current budget usage for a single period.
+ * Maps to BudgetStatus dataclass in agent_energy_budget.budget.tracker.
+ */
+export interface BudgetStatus {
+    /** The agent whose budget this describes. */
+    readonly agent_id: string;
+    /** Period label: "daily", "weekly", or "monthly". */
+    readonly period: "daily" | "weekly" | "monthly";
+    /** Budget cap in USD for this period. */
+    readonly limit_usd: number;
+    /** Amount spent so far this period in USD. */
+    readonly spent_usd: number;
+    /** Amount remaining (limit - spent); may be negative if overspent. */
+    readonly remaining_usd: number;
+    /** Percentage of budget consumed (0-100+). */
+    readonly utilisation_pct: number;
+    /** Number of LLM calls recorded this period. */
+    readonly call_count: number;
+    /** Average cost per call in USD. */
+    readonly avg_cost_per_call: number;
+}
+/**
+ * Request payload for recording actual LLM call costs.
+ */
+export interface CostEntry {
+    /** Agent that made the call. */
+    readonly agent_id: string;
+    /** Model identifier used. */
+    readonly model: string;
+    /** Actual input tokens consumed. */
+    readonly input_tokens: number;
+    /** Actual output tokens generated. */
+    readonly output_tokens: number;
+    /** Actual cost in USD (if null, calculated from pricing tables). */
+    readonly cost_usd?: number;
+}
+/**
+ * Per-model pricing in USD per million tokens.
+ * Maps to ModelPricing dataclass in agent_energy_budget.pricing.tables.
+ */
+export interface ModelPricing {
+    /** Canonical model identifier string. */
+    readonly model: string;
+    /** The provider that operates this model. */
+    readonly provider: ProviderName;
+    /** Quality/cost tier classification. */
+    readonly tier: ModelTier;
+    /** Cost in USD for one million input (prompt) tokens. */
+    readonly input_per_million: number;
+    /** Cost in USD for one million output (completion) tokens. */
+    readonly output_per_million: number;
+    /** Maximum context window in tokens (0 = unknown). */
+    readonly context_window: number;
+    /** Whether the model accepts image inputs. */
+    readonly supports_vision: boolean;
+}
+/**
+ * Immutable record of a fired budget alert event.
+ * Maps to AlertEvent dataclass in agent_energy_budget.budget.alerts.
+ */
+export interface BudgetAlert {
+    /** The agent whose budget triggered the alert. */
+    readonly agent_id: string;
+    /** Alert severity level. */
+    readonly level: AlertLevel;
+    /** Current utilisation percentage at the time of the alert. */
+    readonly utilisation_pct: number;
+    /** Amount spent in USD at the time of the alert. */
+    readonly spent_usd: number;
+    /** Budget limit in USD that was approached or exceeded. */
+    readonly limit_usd: number;
+    /** Budget period label ("daily", "weekly", or "monthly"). */
+    readonly period: string;
+    /** Human-readable description of the alert condition. */
+    readonly message: string;
+    /** ISO-8601 UTC timestamp when the alert was fired. */
+    readonly fired_at: string;
+}
+/**
+ * Pre-execution cost estimate for an LLM call.
+ * Maps to CostEstimate dataclass in agent_energy_budget.estimator.cost_estimator.
+ */
+export interface WorkloadForecast {
+    /** Model identifier used for the estimate. */
+    readonly model: string;
+    /** Estimated number of input (prompt) tokens. */
+    readonly estimated_input_tokens: number;
+    /** Estimated number of output (completion) tokens. */
+    readonly estimated_output_tokens: number;
+    /** Estimated total cost in USD. */
+    readonly estimated_cost_usd: number;
+    /** Confidence score for the estimate in [0.0, 1.0]. */
+    readonly confidence: number;
+}
+/**
+ * Request payload for predicting the cost of an LLM call before execution.
+ */
+export interface PredictCostRequest {
+    /** Agent identifier requesting the cost prediction. */
+    readonly agent_id: string;
+    /** Model to use for cost estimation. */
+    readonly model: string;
+    /** Prompt text to estimate input tokens from. */
+    readonly prompt_text: string;
+    /** Maximum output tokens (used as worst-case upper bound). */
+    readonly max_output_tokens?: number;
+}
+/**
+ * Request payload for updating budget limits for an agent.
+ */
+export interface SetBudgetLimitRequest {
+    /** Agent identifier to update limits for. */
+    readonly agent_id: string;
+    /** New daily limit in USD (0 = disabled, omit to leave unchanged). */
+    readonly daily_limit?: number;
+    /** New weekly limit in USD (0 = disabled, omit to leave unchanged). */
+    readonly weekly_limit?: number;
+    /** New monthly limit in USD (0 = disabled, omit to leave unchanged). */
+    readonly monthly_limit?: number;
+    /** Degradation strategy to apply on limit breach. */
+    readonly degradation_strategy?: DegradationStrategy;
+}
+/**
+ * Throttling configuration applied when budget limits approach exhaustion.
+ * Maps to options in agent_energy_budget.budget.config.
+ */
+export interface ThrottleConfig {
+    /** Agent identifier this throttle configuration applies to. */
+    readonly agent_id: string;
+    /** Whether throttling is currently active for this agent. */
+    readonly throttle_active: boolean;
+    /** Maximum calls per minute allowed under throttle. */
+    readonly max_calls_per_minute: number;
+    /** Maximum input tokens per call under throttle. */
+    readonly max_input_tokens_per_call: number;
+    /** Maximum output tokens per call under throttle. */
+    readonly max_output_tokens_per_call: number;
+    /** ISO-8601 UTC timestamp when throttling was last applied. */
+    readonly throttle_applied_at: string | null;
+}
+/**
+ * Aggregated usage report across all periods for an agent.
+ */
+export interface UsageReport {
+    /** Agent identifier this report covers. */
+    readonly agent_id: string;
+    /** Daily usage snapshot. */
+    readonly daily: BudgetStatus;
+    /** Weekly usage snapshot. */
+    readonly weekly: BudgetStatus;
+    /** Monthly usage snapshot. */
+    readonly monthly: BudgetStatus;
+    /** Total USD spent across all recorded history. */
+    readonly lifetime_spend_usd: number;
+    /** ISO-8601 UTC timestamp when this report was generated. */
+    readonly generated_at: string;
+}
+/** Standard error payload returned by the agent-energy-budget API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * TypeScript interfaces for the agent-energy-budget service.
+ *
+ * Mirrors the Pydantic models and dataclasses defined in:
+ *   agent_energy_budget.budget.config
+ *   agent_energy_budget.budget.tracker
+ *   agent_energy_budget.budget.alerts
+ *   agent_energy_budget.pricing.tables
+ *   agent_energy_budget.estimator.cost_estimator
+ *
+ * All interfaces use readonly fields to match Python's frozen dataclasses.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aumos/agent-energy-budget",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-energy-budget service — token cost tracking, budget enforcement, cost prediction, and model pricing",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-energy-budget",
+    "budget",
+    "cost-tracking",
+    "token-usage",
+    "model-pricing",
+    "llm-costs",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-energy-budget"
+  }
+}

package/src/client.ts

@@ -0,0 +1,288 @@
+/**
+ * HTTP client for the agent-energy-budget service API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentEnergyBudgetClient } from "@aumos/agent-energy-budget";
+ *
+ * const client = createAgentEnergyBudgetClient({ baseUrl: "http://localhost:8095" });
+ *
+ * // Check current budget
+ * const budget = await client.getBudget("my-agent");
+ * if (budget.ok) {
+ *   console.log("Daily limit:", budget.data.daily_limit, "USD");
+ * }
+ *
+ * // Record a completed LLM call
+ * await client.trackCost({
+ *   agent_id: "my-agent",
+ *   model: "claude-haiku-4",
+ *   input_tokens: 2048,
+ *   output_tokens: 512,
+ * });
+ *
+ * // Predict cost before making an LLM call
+ * const forecast = await client.predictCost({
+ *   agent_id: "my-agent",
+ *   model: "gpt-4o-mini",
+ *   prompt_text: "Summarize the report.",
+ *   max_output_tokens: 256,
+ * });
+ * ```
+ */
+
+import type {
+  ApiError,
+  ApiResult,
+  Budget,
+  CostEntry,
+  ModelPricing,
+  PredictCostRequest,
+  SetBudgetLimitRequest,
+  TokenUsage,
+  UsageReport,
+  WorkloadForecast,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentEnergyBudgetClient. */
+export interface AgentEnergyBudgetClientConfig {
+  /** Base URL of the agent-energy-budget server (e.g. "http://localhost:8095"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-energy-budget service. */
+export interface AgentEnergyBudgetClient {
+  /**
+   * Retrieve the current budget configuration for an agent.
+   *
+   * Returns daily, weekly, and monthly limits alongside the configured
+   * degradation strategy, alert thresholds, and model preferences.
+   *
+   * @param agentId - The unique agent identifier.
+   * @returns The Budget configuration record for this agent.
+   */
+  getBudget(agentId: string): Promise<ApiResult<Budget>>;
+
+  /**
+   * Record the actual cost of a completed LLM call.
+   *
+   * Persists the call record to JSONL storage and fires any alert
+   * thresholds that have been crossed as a result of this spend.
+   *
+   * @param entry - Cost record with agent, model, token counts, and optional cost.
+   * @returns The persisted TokenUsage record with calculated cost_usd.
+   */
+  trackCost(entry: CostEntry): Promise<ApiResult<TokenUsage>>;
+
+  /**
+   * Predict the cost of an LLM call before it is executed.
+   *
+   * Uses the pricing tables and token estimation heuristics to return
+   * an upper-bound cost estimate with a confidence score.
+   *
+   * @param request - Prediction request with model, prompt text, and token cap.
+   * @returns WorkloadForecast with estimated tokens, cost, and confidence.
+   */
+  predictCost(request: PredictCostRequest): Promise<ApiResult<WorkloadForecast>>;
+
+  /**
+   * Update the budget limits for an agent.
+   *
+   * Supports updating daily, weekly, and monthly limits independently.
+   * Only fields provided in the request are modified; omitted fields retain
+   * their current values.
+   *
+   * @param request - Budget limit update payload.
+   * @returns The updated Budget configuration record.
+   */
+  setBudgetLimit(request: SetBudgetLimitRequest): Promise<ApiResult<Budget>>;
+
+  /**
+   * Retrieve a consolidated usage report for an agent across all periods.
+   *
+   * Returns daily, weekly, and monthly BudgetStatus snapshots plus a
+   * lifetime total spend.
+   *
+   * @param agentId - The unique agent identifier.
+   * @param options - Optional filter by period ("daily" | "weekly" | "monthly").
+   * @returns UsageReport with per-period snapshots and lifetime totals.
+   */
+  getUsageReport(
+    agentId: string,
+    options?: { period?: "daily" | "weekly" | "monthly" },
+  ): Promise<ApiResult<UsageReport>>;
+
+  /**
+   * Retrieve pricing information for a specific model.
+   *
+   * Supports fuzzy model name resolution including aliases (e.g. "haiku"
+   * resolves to "claude-haiku-4"). Returns null in the data field if the
+   * model cannot be resolved.
+   *
+   * @param model - Model identifier string (exact or alias).
+   * @returns ModelPricing with per-million token rates, tier, and context window.
+   */
+  getModelPricing(model: string): Promise<ApiResult<ModelPricing>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-energy-budget service.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentEnergyBudgetClient instance.
+ */
+export function createAgentEnergyBudgetClient(
+  config: AgentEnergyBudgetClientConfig,
+): AgentEnergyBudgetClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async getBudget(agentId: string): Promise<ApiResult<Budget>> {
+      return fetchJson<Budget>(
+        `${baseUrl}/budgets/${encodeURIComponent(agentId)}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async trackCost(entry: CostEntry): Promise<ApiResult<TokenUsage>> {
+      return fetchJson<TokenUsage>(
+        `${baseUrl}/costs`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(entry),
+        },
+        timeoutMs,
+      );
+    },
+
+    async predictCost(
+      request: PredictCostRequest,
+    ): Promise<ApiResult<WorkloadForecast>> {
+      return fetchJson<WorkloadForecast>(
+        `${baseUrl}/costs/predict`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async setBudgetLimit(
+      request: SetBudgetLimitRequest,
+    ): Promise<ApiResult<Budget>> {
+      return fetchJson<Budget>(
+        `${baseUrl}/budgets/${encodeURIComponent(request.agent_id)}/limits`,
+        {
+          method: "PATCH",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getUsageReport(
+      agentId: string,
+      options?: { period?: "daily" | "weekly" | "monthly" },
+    ): Promise<ApiResult<UsageReport>> {
+      const params = new URLSearchParams();
+      if (options?.period !== undefined) {
+        params.set("period", options.period);
+      }
+      const queryString = params.toString();
+      const url = queryString
+        ? `${baseUrl}/reports/${encodeURIComponent(agentId)}?${queryString}`
+        : `${baseUrl}/reports/${encodeURIComponent(agentId)}`;
+      return fetchJson<UsageReport>(
+        url,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async getModelPricing(model: string): Promise<ApiResult<ModelPricing>> {
+      return fetchJson<ModelPricing>(
+        `${baseUrl}/pricing/${encodeURIComponent(model)}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @aumos/agent-energy-budget
+ *
+ * TypeScript client for the AumOS agent-energy-budget service.
+ * Provides HTTP client and type definitions for token cost tracking,
+ * budget enforcement, cost prediction, and model pricing lookup.
+ */
+
+// Client and configuration
+export type { AgentEnergyBudgetClient, AgentEnergyBudgetClientConfig } from "./client.js";
+export { createAgentEnergyBudgetClient } from "./client.js";
+
+// Core types
+export type {
+  DegradationStrategy,
+  ProviderName,
+  ModelTier,
+  AlertLevel,
+  TokenUsage,
+  AlertThresholds,
+  ModelPreferences,
+  Budget,
+  BudgetStatus,
+  CostEntry,
+  ModelPricing,
+  BudgetAlert,
+  WorkloadForecast,
+  PredictCostRequest,
+  SetBudgetLimitRequest,
+  ThrottleConfig,
+  UsageReport,
+  ApiError,
+  ApiResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,354 @@
+/**
+ * TypeScript interfaces for the agent-energy-budget service.
+ *
+ * Mirrors the Pydantic models and dataclasses defined in:
+ *   agent_energy_budget.budget.config
+ *   agent_energy_budget.budget.tracker
+ *   agent_energy_budget.budget.alerts
+ *   agent_energy_budget.pricing.tables
+ *   agent_energy_budget.estimator.cost_estimator
+ *
+ * All interfaces use readonly fields to match Python's frozen dataclasses.
+ */
+
+// ---------------------------------------------------------------------------
+// Enumerations
+// ---------------------------------------------------------------------------
+
+/**
+ * Action to take when a budget limit is approached or exceeded.
+ * Maps to DegradationStrategy enum in agent_energy_budget.budget.config.
+ */
+export type DegradationStrategy =
+  | "model_downgrade"
+  | "token_reduction"
+  | "block_with_error"
+  | "cached_fallback";
+
+/**
+ * LLM provider identifier.
+ * Maps to ProviderName enum in agent_energy_budget.pricing.tables.
+ */
+export type ProviderName =
+  | "anthropic"
+  | "openai"
+  | "google"
+  | "mistral"
+  | "meta"
+  | "deepseek"
+  | "custom";
+
+/**
+ * Quality/cost tier classification for models.
+ * Maps to ModelTier enum in agent_energy_budget.pricing.tables.
+ *
+ * nano      — ultra-cheap, small context, fast
+ * efficient — good value, solid quality
+ * standard  — mainstream flagship-class models
+ * premium   — top capability, highest cost
+ */
+export type ModelTier = "nano" | "efficient" | "standard" | "premium";
+
+/**
+ * Alert severity level.
+ * Maps to AlertLevel enum in agent_energy_budget.budget.alerts.
+ */
+export type AlertLevel = "warning" | "critical" | "exhausted";
+
+// ---------------------------------------------------------------------------
+// TokenUsage
+// ---------------------------------------------------------------------------
+
+/**
+ * Token consumption record for a single LLM call.
+ * Mirrors the _CallRecord internal dataclass in agent_energy_budget.budget.tracker.
+ */
+export interface TokenUsage {
+  /** Agent that made this call. */
+  readonly agent_id: string;
+  /** Model identifier used for this call. */
+  readonly model: string;
+  /** Number of input (prompt) tokens consumed. */
+  readonly input_tokens: number;
+  /** Number of output (completion) tokens generated. */
+  readonly output_tokens: number;
+  /** Actual cost in USD for this call. */
+  readonly cost_usd: number;
+  /** ISO-8601 UTC timestamp when this call was recorded. */
+  readonly recorded_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Budget
+// ---------------------------------------------------------------------------
+
+/**
+ * Alert threshold configuration as utilisation percentages.
+ * Maps to AlertThresholds in agent_energy_budget.budget.config.
+ */
+export interface AlertThresholds {
+  /** First alert threshold (default 50%). */
+  readonly warning: number;
+  /** Second alert threshold (default 80%). */
+  readonly critical: number;
+  /** Third alert threshold (default 100%). */
+  readonly exhausted: number;
+}
+
+/**
+ * Model selection preferences for degradation and estimation.
+ * Maps to ModelPreferences in agent_energy_budget.budget.config.
+ */
+export interface ModelPreferences {
+  /** Ordered list of model IDs to try first (most preferred first). */
+  readonly preferred_models: readonly string[];
+  /** Model to use when all others are exhausted or over budget. */
+  readonly fallback_model: string;
+  /** Model IDs that must never be used. */
+  readonly blocked_models: readonly string[];
+  /** When true, restrict model selection to vision-capable models only. */
+  readonly require_vision: boolean;
+}
+
+/**
+ * Top-level budget configuration for a single agent or agent group.
+ * Maps to BudgetConfig in agent_energy_budget.budget.config.
+ */
+export interface Budget {
+  /** Unique identifier for the agent this budget belongs to. */
+  readonly agent_id: string;
+  /** Maximum USD spend per calendar day (0 = disabled). */
+  readonly daily_limit: number;
+  /** Maximum USD spend per calendar week Mon-Sun (0 = disabled). */
+  readonly weekly_limit: number;
+  /** Maximum USD spend per calendar month (0 = disabled). */
+  readonly monthly_limit: number;
+  /** Strategy to apply when a limit is breached. */
+  readonly degradation_strategy: DegradationStrategy;
+  /** Utilisation percentage levels that trigger alerts. */
+  readonly alert_thresholds: AlertThresholds;
+  /** Model selection configuration for degradation. */
+  readonly model_preferences: ModelPreferences;
+  /** ISO currency code for display purposes (default "USD"). */
+  readonly currency: string;
+  /** Arbitrary key-value metadata attached to this budget. */
+  readonly tags: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// BudgetStatus (usage snapshot)
+// ---------------------------------------------------------------------------
+
+/**
+ * Snapshot of current budget usage for a single period.
+ * Maps to BudgetStatus dataclass in agent_energy_budget.budget.tracker.
+ */
+export interface BudgetStatus {
+  /** The agent whose budget this describes. */
+  readonly agent_id: string;
+  /** Period label: "daily", "weekly", or "monthly". */
+  readonly period: "daily" | "weekly" | "monthly";
+  /** Budget cap in USD for this period. */
+  readonly limit_usd: number;
+  /** Amount spent so far this period in USD. */
+  readonly spent_usd: number;
+  /** Amount remaining (limit - spent); may be negative if overspent. */
+  readonly remaining_usd: number;
+  /** Percentage of budget consumed (0-100+). */
+  readonly utilisation_pct: number;
+  /** Number of LLM calls recorded this period. */
+  readonly call_count: number;
+  /** Average cost per call in USD. */
+  readonly avg_cost_per_call: number;
+}
+
+// ---------------------------------------------------------------------------
+// CostEntry (track cost request)
+// ---------------------------------------------------------------------------
+
+/**
+ * Request payload for recording actual LLM call costs.
+ */
+export interface CostEntry {
+  /** Agent that made the call. */
+  readonly agent_id: string;
+  /** Model identifier used. */
+  readonly model: string;
+  /** Actual input tokens consumed. */
+  readonly input_tokens: number;
+  /** Actual output tokens generated. */
+  readonly output_tokens: number;
+  /** Actual cost in USD (if null, calculated from pricing tables). */
+  readonly cost_usd?: number;
+}
+
+// ---------------------------------------------------------------------------
+// ModelPricing
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-model pricing in USD per million tokens.
+ * Maps to ModelPricing dataclass in agent_energy_budget.pricing.tables.
+ */
+export interface ModelPricing {
+  /** Canonical model identifier string. */
+  readonly model: string;
+  /** The provider that operates this model. */
+  readonly provider: ProviderName;
+  /** Quality/cost tier classification. */
+  readonly tier: ModelTier;
+  /** Cost in USD for one million input (prompt) tokens. */
+  readonly input_per_million: number;
+  /** Cost in USD for one million output (completion) tokens. */
+  readonly output_per_million: number;
+  /** Maximum context window in tokens (0 = unknown). */
+  readonly context_window: number;
+  /** Whether the model accepts image inputs. */
+  readonly supports_vision: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// BudgetAlert
+// ---------------------------------------------------------------------------
+
+/**
+ * Immutable record of a fired budget alert event.
+ * Maps to AlertEvent dataclass in agent_energy_budget.budget.alerts.
+ */
+export interface BudgetAlert {
+  /** The agent whose budget triggered the alert. */
+  readonly agent_id: string;
+  /** Alert severity level. */
+  readonly level: AlertLevel;
+  /** Current utilisation percentage at the time of the alert. */
+  readonly utilisation_pct: number;
+  /** Amount spent in USD at the time of the alert. */
+  readonly spent_usd: number;
+  /** Budget limit in USD that was approached or exceeded. */
+  readonly limit_usd: number;
+  /** Budget period label ("daily", "weekly", or "monthly"). */
+  readonly period: string;
+  /** Human-readable description of the alert condition. */
+  readonly message: string;
+  /** ISO-8601 UTC timestamp when the alert was fired. */
+  readonly fired_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// WorkloadForecast (cost prediction)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pre-execution cost estimate for an LLM call.
+ * Maps to CostEstimate dataclass in agent_energy_budget.estimator.cost_estimator.
+ */
+export interface WorkloadForecast {
+  /** Model identifier used for the estimate. */
+  readonly model: string;
+  /** Estimated number of input (prompt) tokens. */
+  readonly estimated_input_tokens: number;
+  /** Estimated number of output (completion) tokens. */
+  readonly estimated_output_tokens: number;
+  /** Estimated total cost in USD. */
+  readonly estimated_cost_usd: number;
+  /** Confidence score for the estimate in [0.0, 1.0]. */
+  readonly confidence: number;
+}
+
+// ---------------------------------------------------------------------------
+// PredictCostRequest
+// ---------------------------------------------------------------------------
+
+/**
+ * Request payload for predicting the cost of an LLM call before execution.
+ */
+export interface PredictCostRequest {
+  /** Agent identifier requesting the cost prediction. */
+  readonly agent_id: string;
+  /** Model to use for cost estimation. */
+  readonly model: string;
+  /** Prompt text to estimate input tokens from. */
+  readonly prompt_text: string;
+  /** Maximum output tokens (used as worst-case upper bound). */
+  readonly max_output_tokens?: number;
+}
+
+// ---------------------------------------------------------------------------
+// SetBudgetLimitRequest
+// ---------------------------------------------------------------------------
+
+/**
+ * Request payload for updating budget limits for an agent.
+ */
+export interface SetBudgetLimitRequest {
+  /** Agent identifier to update limits for. */
+  readonly agent_id: string;
+  /** New daily limit in USD (0 = disabled, omit to leave unchanged). */
+  readonly daily_limit?: number;
+  /** New weekly limit in USD (0 = disabled, omit to leave unchanged). */
+  readonly weekly_limit?: number;
+  /** New monthly limit in USD (0 = disabled, omit to leave unchanged). */
+  readonly monthly_limit?: number;
+  /** Degradation strategy to apply on limit breach. */
+  readonly degradation_strategy?: DegradationStrategy;
+}
+
+// ---------------------------------------------------------------------------
+// ThrottleConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Throttling configuration applied when budget limits approach exhaustion.
+ * Maps to options in agent_energy_budget.budget.config.
+ */
+export interface ThrottleConfig {
+  /** Agent identifier this throttle configuration applies to. */
+  readonly agent_id: string;
+  /** Whether throttling is currently active for this agent. */
+  readonly throttle_active: boolean;
+  /** Maximum calls per minute allowed under throttle. */
+  readonly max_calls_per_minute: number;
+  /** Maximum input tokens per call under throttle. */
+  readonly max_input_tokens_per_call: number;
+  /** Maximum output tokens per call under throttle. */
+  readonly max_output_tokens_per_call: number;
+  /** ISO-8601 UTC timestamp when throttling was last applied. */
+  readonly throttle_applied_at: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// UsageReport
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregated usage report across all periods for an agent.
+ */
+export interface UsageReport {
+  /** Agent identifier this report covers. */
+  readonly agent_id: string;
+  /** Daily usage snapshot. */
+  readonly daily: BudgetStatus;
+  /** Weekly usage snapshot. */
+  readonly weekly: BudgetStatus;
+  /** Monthly usage snapshot. */
+  readonly monthly: BudgetStatus;
+  /** Total USD spent across all recorded history. */
+  readonly lifetime_spend_usd: number;
+  /** ISO-8601 UTC timestamp when this report was generated. */
+  readonly generated_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// API result wrapper (shared pattern)
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-energy-budget API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2020", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}