agentpay-mcp 4.1.0 → 4.1.4

package/dist/tools/otel-budget.d.ts

@@ -0,0 +1,265 @@
+/**
+ * otel-budget.ts — OpenTelemetry Budget Circuit-Breaker for AWS AgentCore
+ *
+ * Reads OTel span data from AgentCore-instrumented agents, applies per-agent
+ * and per-task budget policies against accumulated spend, emits budget
+ * enforcement decisions as OTel events, and supports circuit-breaker patterns
+ * (auto-kill agent runs exceeding budget thresholds).
+ *
+ * Why this exists: AWS AgentCore Policy Controls (GA March 2026) provide
+ * observability and guardrails but NO native per-agent/per-session spend cap
+ * APIs. This module fills that gap by sitting between the OTel telemetry
+ * pipeline and agentpay-mcp's existing budget enforcement.
+ *
+ * @module otel-budget
+ * @since 4.2.0
+ */
+import { z } from 'zod';
+export interface AgentBudgetPolicy {
+    /** Unique agent or session identifier */
+    agentId: string;
+    /** Optional task-level identifier for fine-grained budgets */
+    taskId?: string;
+    /** Maximum spend in USD for this agent/task */
+    maxSpendUsd: number;
+    /** Rolling window in milliseconds (0 = lifetime budget) */
+    windowMs: number;
+    /** Action when budget exceeded: 'warn' | 'block' | 'kill' */
+    breachAction: 'warn' | 'block' | 'kill';
+    /** Optional callback URL for circuit-breaker kill signal */
+    killCallbackUrl?: string;
+}
+export interface SpendRecord {
+    agentId: string;
+    taskId?: string;
+    amountUsd: number;
+    timestamp: number;
+    spanId: string;
+    traceId: string;
+}
+export interface BudgetDecision {
+    agentId: string;
+    taskId?: string;
+    action: 'allow' | 'warn' | 'block' | 'kill';
+    accumulatedSpendUsd: number;
+    budgetLimitUsd: number;
+    remainingUsd: number;
+    utilizationPct: number;
+    reason: string;
+    timestamp: number;
+}
+export interface OTelSpanCostAttributes {
+    /** OTel span attribute: agentcore.agent.id */
+    'agentcore.agent.id'?: string;
+    /** OTel span attribute: agentcore.task.id */
+    'agentcore.task.id'?: string;
+    /** OTel span attribute: agentcore.cost.usd — cost incurred in this span */
+    'agentcore.cost.usd'?: number;
+    /** OTel span attribute: gen_ai.usage.input_tokens */
+    'gen_ai.usage.input_tokens'?: number;
+    /** OTel span attribute: gen_ai.usage.output_tokens */
+    'gen_ai.usage.output_tokens'?: number;
+    /** OTel span attribute: gen_ai.usage.cost */
+    'gen_ai.usage.cost'?: number;
+    /** Standard OTel trace/span IDs */
+    traceId?: string;
+    spanId?: string;
+}
+/** Reset all state — useful for testing */
+export declare function _resetOTelBudgetState(): void;
+/**
+ * Register a budget policy for an agent or agent+task combination.
+ */
+export declare function registerPolicy(policy: AgentBudgetPolicy): void;
+/**
+ * Process an OTel span and evaluate budget. Returns a BudgetDecision.
+ *
+ * This is the main entry point: feed it span attributes from an
+ * AgentCore-instrumented agent, and it returns an enforcement decision.
+ */
+export declare function evaluateSpan(attrs: OTelSpanCostAttributes): BudgetDecision | null;
+export declare function invokeKillCallback(policy: AgentBudgetPolicy, decision: BudgetDecision): Promise<{
+    attempted: boolean;
+    ok: boolean;
+    status?: number;
+    error?: string;
+} | null>;
+/**
+ * Convert a BudgetDecision to OTel-compatible event attributes.
+ * These can be emitted as span events for AgentCore dashboard visibility.
+ */
+export declare function decisionToOTelEvent(decision: BudgetDecision): Record<string, string | number | boolean>;
+/**
+ * Get recent decisions for an agent (for dashboard/audit).
+ */
+export declare function getDecisionHistory(agentId: string, limit?: number): BudgetDecision[];
+/**
+ * Get all registered policies (for introspection).
+ */
+export declare function listPolicies(): AgentBudgetPolicy[];
+export declare const OTelRegisterPolicySchema: z.ZodObject<{
+    agentId: z.ZodString;
+    taskId: z.ZodOptional<z.ZodString>;
+    maxSpendUsd: z.ZodNumber;
+    windowMs: z.ZodDefault<z.ZodNumber>;
+    breachAction: z.ZodDefault<z.ZodEnum<["warn", "block", "kill"]>>;
+    killCallbackUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    agentId: string;
+    maxSpendUsd: number;
+    windowMs: number;
+    breachAction: "block" | "warn" | "kill";
+    taskId?: string | undefined;
+    killCallbackUrl?: string | undefined;
+}, {
+    agentId: string;
+    maxSpendUsd: number;
+    taskId?: string | undefined;
+    windowMs?: number | undefined;
+    breachAction?: "block" | "warn" | "kill" | undefined;
+    killCallbackUrl?: string | undefined;
+}>;
+export type OTelRegisterPolicyInput = z.infer<typeof OTelRegisterPolicySchema>;
+export declare const otelRegisterPolicyTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            agentId: {
+                type: string;
+                description: string;
+            };
+            taskId: {
+                type: string;
+                description: string;
+            };
+            maxSpendUsd: {
+                type: string;
+                description: string;
+            };
+            windowMs: {
+                type: string;
+                description: string;
+            };
+            breachAction: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            killCallbackUrl: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleOTelRegisterPolicy(input: OTelRegisterPolicyInput): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare const OTelEvaluateSpendSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    taskId: z.ZodOptional<z.ZodString>;
+    costUsd: z.ZodNumber;
+    spanId: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    agentId: string;
+    costUsd: number;
+    taskId?: string | undefined;
+    spanId?: string | undefined;
+    traceId?: string | undefined;
+}, {
+    agentId: string;
+    costUsd: number;
+    taskId?: string | undefined;
+    spanId?: string | undefined;
+    traceId?: string | undefined;
+}>;
+export type OTelEvaluateSpendInput = z.infer<typeof OTelEvaluateSpendSchema>;
+export declare const otelEvaluateSpendTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            agentId: {
+                type: string;
+                description: string;
+            };
+            taskId: {
+                type: string;
+                description: string;
+            };
+            costUsd: {
+                type: string;
+                description: string;
+            };
+            spanId: {
+                type: string;
+                description: string;
+            };
+            traceId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleOTelEvaluateSpend(input: OTelEvaluateSpendInput): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare const OTelBudgetStatusSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    includeHistory: z.ZodDefault<z.ZodBoolean>;
+    historyLimit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    agentId: string;
+    includeHistory: boolean;
+    historyLimit: number;
+}, {
+    agentId: string;
+    includeHistory?: boolean | undefined;
+    historyLimit?: number | undefined;
+}>;
+export type OTelBudgetStatusInput = z.infer<typeof OTelBudgetStatusSchema>;
+export declare const otelBudgetStatusTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            agentId: {
+                type: string;
+                description: string;
+            };
+            includeHistory: {
+                type: string;
+                description: string;
+            };
+            historyLimit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleOTelBudgetStatus(input: OTelBudgetStatusInput): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+//# sourceMappingURL=otel-budget.d.ts.map

package/dist/tools/otel-budget.d.ts.map

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

package/dist/tools/otel-budget.js

@@ -0,0 +1,399 @@
+"use strict";
+/**
+ * otel-budget.ts — OpenTelemetry Budget Circuit-Breaker for AWS AgentCore
+ *
+ * Reads OTel span data from AgentCore-instrumented agents, applies per-agent
+ * and per-task budget policies against accumulated spend, emits budget
+ * enforcement decisions as OTel events, and supports circuit-breaker patterns
+ * (auto-kill agent runs exceeding budget thresholds).
+ *
+ * Why this exists: AWS AgentCore Policy Controls (GA March 2026) provide
+ * observability and guardrails but NO native per-agent/per-session spend cap
+ * APIs. This module fills that gap by sitting between the OTel telemetry
+ * pipeline and agentpay-mcp's existing budget enforcement.
+ *
+ * @module otel-budget
+ * @since 4.2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.otelBudgetStatusTool = exports.OTelBudgetStatusSchema = exports.otelEvaluateSpendTool = exports.OTelEvaluateSpendSchema = exports.otelRegisterPolicyTool = exports.OTelRegisterPolicySchema = void 0;
+exports._resetOTelBudgetState = _resetOTelBudgetState;
+exports.registerPolicy = registerPolicy;
+exports.evaluateSpan = evaluateSpan;
+exports.invokeKillCallback = invokeKillCallback;
+exports.decisionToOTelEvent = decisionToOTelEvent;
+exports.getDecisionHistory = getDecisionHistory;
+exports.listPolicies = listPolicies;
+exports.handleOTelRegisterPolicy = handleOTelRegisterPolicy;
+exports.handleOTelEvaluateSpend = handleOTelEvaluateSpend;
+exports.handleOTelBudgetStatus = handleOTelBudgetStatus;
+const zod_1 = require("zod");
+const format_js_1 = require("../utils/format.js");
+// ─── In-memory stores ──────────────────────────────────────────────────────
+const _policies = new Map();
+const _spendLedger = [];
+const _decisions = [];
+/** Build a policy key from agentId + optional taskId */
+function policyKey(agentId, taskId) {
+    return taskId ? `${agentId}::${taskId}` : agentId;
+}
+/** Reset all state — useful for testing */
+function _resetOTelBudgetState() {
+    _policies.clear();
+    _spendLedger.length = 0;
+    _decisions.length = 0;
+}
+// ─── Core Logic ────────────────────────────────────────────────────────────
+/**
+ * Register a budget policy for an agent or agent+task combination.
+ */
+function registerPolicy(policy) {
+    const key = policyKey(policy.agentId, policy.taskId);
+    _policies.set(key, policy);
+}
+function getApplicablePolicy(agentId, taskId) {
+    const taskPolicy = taskId ? _policies.get(policyKey(agentId, taskId)) : undefined;
+    const agentPolicy = _policies.get(policyKey(agentId));
+    return taskPolicy ?? agentPolicy;
+}
+/**
+ * Get accumulated spend for an agent within the policy's rolling window.
+ */
+function getAccumulatedSpend(agentId, taskId, windowMs) {
+    const now = Date.now();
+    const cutoff = windowMs && windowMs > 0 ? now - windowMs : 0;
+    return _spendLedger
+        .filter((r) => r.agentId === agentId &&
+        (taskId === undefined || r.taskId === taskId) &&
+        r.timestamp >= cutoff)
+        .reduce((sum, r) => sum + r.amountUsd, 0);
+}
+/**
+ * Process an OTel span and evaluate budget. Returns a BudgetDecision.
+ *
+ * This is the main entry point: feed it span attributes from an
+ * AgentCore-instrumented agent, and it returns an enforcement decision.
+ */
+function evaluateSpan(attrs) {
+    const agentId = attrs['agentcore.agent.id'];
+    if (!agentId)
+        return null;
+    const taskId = attrs['agentcore.task.id'];
+    const costUsd = attrs['agentcore.cost.usd'] ?? attrs['gen_ai.usage.cost'] ?? 0;
+    if (costUsd <= 0)
+        return null;
+    // Record spend
+    const record = {
+        agentId,
+        taskId,
+        amountUsd: costUsd,
+        timestamp: Date.now(),
+        spanId: attrs.spanId ?? 'unknown',
+        traceId: attrs.traceId ?? 'unknown',
+    };
+    _spendLedger.push(record);
+    // Find applicable policy (task-specific first, then agent-level)
+    const policy = getApplicablePolicy(agentId, taskId);
+    if (!policy) {
+        // No policy = allow (but we still recorded the spend)
+        return {
+            agentId,
+            taskId,
+            action: 'allow',
+            accumulatedSpendUsd: getAccumulatedSpend(agentId, taskId),
+            budgetLimitUsd: Infinity,
+            remainingUsd: Infinity,
+            utilizationPct: 0,
+            reason: 'No budget policy registered for this agent',
+            timestamp: Date.now(),
+        };
+    }
+    const spendScopeTaskId = policy.taskId === undefined ? undefined : taskId;
+    const accumulated = getAccumulatedSpend(agentId, spendScopeTaskId, policy.windowMs);
+    const remaining = Math.max(0, policy.maxSpendUsd - accumulated);
+    const utilization = (accumulated / policy.maxSpendUsd) * 100;
+    let action = 'allow';
+    let reason = 'Within budget';
+    if (accumulated > policy.maxSpendUsd) {
+        action = policy.breachAction;
+        reason = `Budget exceeded: $${accumulated.toFixed(4)} / $${policy.maxSpendUsd.toFixed(4)} (${utilization.toFixed(1)}%)`;
+    }
+    else if (utilization >= 90) {
+        action = 'warn';
+        reason = `Approaching budget limit: $${accumulated.toFixed(4)} / $${policy.maxSpendUsd.toFixed(4)} (${utilization.toFixed(1)}%)`;
+    }
+    const decision = {
+        agentId,
+        taskId,
+        action,
+        accumulatedSpendUsd: accumulated,
+        budgetLimitUsd: policy.maxSpendUsd,
+        remainingUsd: remaining,
+        utilizationPct: utilization,
+        reason,
+        timestamp: Date.now(),
+    };
+    _decisions.push(decision);
+    return decision;
+}
+async function invokeKillCallback(policy, decision) {
+    if (decision.action !== 'kill' || !policy.killCallbackUrl) {
+        return null;
+    }
+    try {
+        const response = await fetch(policy.killCallbackUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                event: 'agentpay.budget.kill',
+                decision,
+                policy: {
+                    agentId: policy.agentId,
+                    taskId: policy.taskId,
+                    maxSpendUsd: policy.maxSpendUsd,
+                    windowMs: policy.windowMs,
+                    breachAction: policy.breachAction,
+                },
+            }),
+        });
+        return {
+            attempted: true,
+            ok: response.ok,
+            status: response.status,
+            ...(response.ok ? {} : { error: `Kill callback returned HTTP ${response.status}` }),
+        };
+    }
+    catch (error) {
+        return {
+            attempted: true,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Convert a BudgetDecision to OTel-compatible event attributes.
+ * These can be emitted as span events for AgentCore dashboard visibility.
+ */
+function decisionToOTelEvent(decision) {
+    return {
+        'event.name': 'agentpay.budget.decision',
+        'agentpay.agent_id': decision.agentId,
+        'agentpay.task_id': decision.taskId ?? '',
+        'agentpay.action': decision.action,
+        'agentpay.accumulated_spend_usd': decision.accumulatedSpendUsd,
+        'agentpay.budget_limit_usd': decision.budgetLimitUsd,
+        'agentpay.remaining_usd': decision.remainingUsd,
+        'agentpay.utilization_pct': decision.utilizationPct,
+        'agentpay.reason': decision.reason,
+        'agentpay.circuit_breaker_tripped': decision.action === 'kill',
+    };
+}
+/**
+ * Get recent decisions for an agent (for dashboard/audit).
+ */
+function getDecisionHistory(agentId, limit = 50) {
+    return _decisions
+        .filter((d) => d.agentId === agentId)
+        .slice(-limit);
+}
+/**
+ * Get all registered policies (for introspection).
+ */
+function listPolicies() {
+    return Array.from(_policies.values());
+}
+// ─── MCP Tool Definitions ──────────────────────────────────────────────────
+exports.OTelRegisterPolicySchema = zod_1.z.object({
+    agentId: zod_1.z.string().describe('Agent or session identifier from AgentCore'),
+    taskId: zod_1.z.string().optional().describe('Optional task-level identifier'),
+    maxSpendUsd: zod_1.z.number().positive().describe('Maximum spend in USD'),
+    windowMs: zod_1.z
+        .number()
+        .min(0)
+        .default(0)
+        .describe('Rolling window in ms (0 = lifetime budget)'),
+    breachAction: zod_1.z
+        .enum(['warn', 'block', 'kill'])
+        .default('block')
+        .describe('Action on budget breach: warn, block, or kill (circuit-breaker)'),
+    killCallbackUrl: zod_1.z
+        .string()
+        .optional()
+        .describe('Webhook URL to invoke when circuit-breaker trips (kill action)'),
+});
+exports.otelRegisterPolicyTool = {
+    name: 'otel_register_budget_policy',
+    description: 'Register a budget policy for an AWS AgentCore agent or task. ' +
+        'When OTel spans report costs exceeding this budget, agentpay-mcp will ' +
+        'enforce the configured action (warn/block/kill circuit-breaker). ' +
+        'This fills the gap left by AgentCore Policy Controls which provide ' +
+        'observability but no native per-agent spend caps.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: { type: 'string', description: 'Agent/session ID from AgentCore' },
+            taskId: { type: 'string', description: 'Optional task-level ID' },
+            maxSpendUsd: { type: 'number', description: 'Max spend in USD' },
+            windowMs: { type: 'number', description: 'Rolling window in ms (0 = lifetime)' },
+            breachAction: {
+                type: 'string',
+                enum: ['warn', 'block', 'kill'],
+                description: 'Action on breach',
+            },
+            killCallbackUrl: { type: 'string', description: 'Circuit-breaker webhook URL' },
+        },
+        required: ['agentId', 'maxSpendUsd'],
+    },
+};
+async function handleOTelRegisterPolicy(input) {
+    try {
+        const policy = {
+            agentId: input.agentId,
+            taskId: input.taskId,
+            maxSpendUsd: input.maxSpendUsd,
+            windowMs: input.windowMs ?? 0,
+            breachAction: input.breachAction ?? 'block',
+            killCallbackUrl: input.killCallbackUrl,
+        };
+        registerPolicy(policy);
+        return {
+            content: [
+                (0, format_js_1.textContent)(JSON.stringify({
+                    success: true,
+                    policy: {
+                        key: policyKey(policy.agentId, policy.taskId),
+                        ...policy,
+                    },
+                })),
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'otel_register_budget_policy'))],
+            isError: true,
+        };
+    }
+}
+// ─── otel_evaluate_spend ───────────────────────────────────────────────────
+exports.OTelEvaluateSpendSchema = zod_1.z.object({
+    agentId: zod_1.z.string().describe('Agent ID from OTel span attribute agentcore.agent.id'),
+    taskId: zod_1.z.string().optional().describe('Task ID from OTel span attribute agentcore.task.id'),
+    costUsd: zod_1.z.number().describe('Cost in USD from this span'),
+    spanId: zod_1.z.string().optional().describe('OTel span ID'),
+    traceId: zod_1.z.string().optional().describe('OTel trace ID'),
+});
+exports.otelEvaluateSpendTool = {
+    name: 'otel_evaluate_spend',
+    description: 'Evaluate a spend event from an OTel span against registered budget policies. ' +
+        'Returns a budget decision (allow/warn/block/kill) with utilization details. ' +
+        'The decision is also formatted as OTel event attributes for re-emission ' +
+        'into the AgentCore telemetry pipeline.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: { type: 'string', description: 'Agent ID from OTel span' },
+            taskId: { type: 'string', description: 'Task ID from OTel span' },
+            costUsd: { type: 'number', description: 'Span cost in USD' },
+            spanId: { type: 'string', description: 'OTel span ID' },
+            traceId: { type: 'string', description: 'OTel trace ID' },
+        },
+        required: ['agentId', 'costUsd'],
+    },
+};
+async function handleOTelEvaluateSpend(input) {
+    try {
+        const policy = getApplicablePolicy(input.agentId, input.taskId);
+        const decision = evaluateSpan({
+            'agentcore.agent.id': input.agentId,
+            'agentcore.task.id': input.taskId,
+            'agentcore.cost.usd': input.costUsd,
+            spanId: input.spanId,
+            traceId: input.traceId,
+        });
+        if (!decision) {
+            return {
+                content: [
+                    (0, format_js_1.textContent)(JSON.stringify({ action: 'skip', reason: 'No cost or agent ID in span' })),
+                ],
+            };
+        }
+        const otelEvent = decisionToOTelEvent(decision);
+        const killCallback = policy
+            ? await invokeKillCallback(policy, decision)
+            : null;
+        return {
+            content: [
+                (0, format_js_1.textContent)(JSON.stringify({
+                    decision,
+                    otelEvent,
+                    killCallback,
+                })),
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'otel_evaluate_spend'))],
+            isError: true,
+        };
+    }
+}
+// ─── otel_budget_status ────────────────────────────────────────────────────
+exports.OTelBudgetStatusSchema = zod_1.z.object({
+    agentId: zod_1.z.string().describe('Agent ID to check budget status for'),
+    includeHistory: zod_1.z
+        .boolean()
+        .default(false)
+        .describe('Include recent decision history'),
+    historyLimit: zod_1.z.number().default(20).describe('Max history entries to return'),
+});
+exports.otelBudgetStatusTool = {
+    name: 'otel_budget_status',
+    description: 'Get the current budget status for an AgentCore agent, including ' +
+        'accumulated spend, remaining budget, utilization percentage, and ' +
+        'optional decision history. Useful for dashboards and audit trails.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: { type: 'string', description: 'Agent ID' },
+            includeHistory: { type: 'boolean', description: 'Include decision history' },
+            historyLimit: { type: 'number', description: 'Max history entries' },
+        },
+        required: ['agentId'],
+    },
+};
+async function handleOTelBudgetStatus(input) {
+    try {
+        const agentPolicies = Array.from(_policies.values()).filter((p) => p.agentId === input.agentId);
+        const statuses = agentPolicies.map((policy) => {
+            const accumulated = getAccumulatedSpend(policy.agentId, policy.taskId, policy.windowMs);
+            return {
+                policyKey: policyKey(policy.agentId, policy.taskId),
+                policy,
+                accumulatedSpendUsd: accumulated,
+                remainingUsd: Math.max(0, policy.maxSpendUsd - accumulated),
+                utilizationPct: (accumulated / policy.maxSpendUsd) * 100,
+            };
+        });
+        const result = {
+            agentId: input.agentId,
+            policies: statuses,
+            totalAccumulatedUsd: getAccumulatedSpend(input.agentId),
+        };
+        if (input.includeHistory) {
+            result.recentDecisions = getDecisionHistory(input.agentId, input.historyLimit ?? 20);
+        }
+        return { content: [(0, format_js_1.textContent)(JSON.stringify(result))] };
+    }
+    catch (error) {
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'otel_budget_status'))],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=otel-budget.js.map