toad-eye 2.4.5 → 2.6.0

package/README.md

@@ -124,6 +124,39 @@ const result = await traceLLMCall(
 
 </details>
 
+<details>
+<summary>MCP Server observability</summary>
+
+Drop-in middleware for MCP servers — one line for full tracing of every tool call, resource read, and prompt request.
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { toadEyeMiddleware } from "toad-eye/mcp";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+toadEyeMiddleware(server);
+
+// All handlers are now instrumented — spans appear in Jaeger
+server.tool("calculate", { expression: z.string() }, async ({ expression }) => {
+  return { content: [{ type: "text", text: String(eval(expression)) }] };
+});
+```
+
+Spans follow OTel GenAI semconv: `execute_tool calculate`, `retrieval file:///docs`, `prompt greeting`.
+
+Privacy by default — tool arguments and results are NOT recorded unless you opt in:
+
+```typescript
+toadEyeMiddleware(server, {
+  recordInputs: true,
+  redactKeys: ["apiKey", "token"],
+});
+```
+
+> Safe for stdio transport — OTel diagnostics are redirected to stderr.
+
+</details>
+
 ## Budget guards
 
 Prevent cost overruns at runtime. Three modes: warn, block, or auto-downgrade to a cheaper model.
@@ -385,7 +418,7 @@ import { ToadEyeAISpanProcessor, withToadEye } from "toad-eye/vercel"; // Vercel
 
 ## Architecture
 
-![toad-eye architecture](https://raw.githubusercontent.com/vola-trebla/toad-eye/main/demo/toad_eye_architecture.svg)
+![toad-eye architecture](https://raw.githubusercontent.com/vola-trebla/toad-eye/main/demo/toad_eye_architecture_v2.svg)
 
 ## What it tracks
 

package/dist/agent.js

@@ -1,6 +1,6 @@
 import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "./types/index.js";
-import { recordAgentSteps, recordAgentToolUsage } from "./core/metrics.js";
+import { recordAgentSteps, recordAgentToolUsage, recordAgentToolDuration, } from "./core/metrics.js";
 import { getConfig, shouldEmitDeprecatedAttrs } from "./core/tracer.js";
 const tracer = trace.getTracer(INSTRUMENTATION_NAME);
 const DEFAULT_MAX_STEPS = 25;
@@ -58,7 +58,11 @@ function traceAgentStep(input) {
         }),
     });
     if (input.type === "act" && input.toolName !== undefined) {
-        recordAgentToolUsage(input.toolName);
+        recordAgentToolUsage(input.toolName, input.toolStatus ?? "success");
+        if (input.toolDurationMs !== undefined) {
+            recordAgentToolDuration(input.toolName, input.toolDurationMs);
+            span.setAttribute("gen_ai.tool.duration_ms", input.toolDurationMs);
+        }
     }
     span.setStatus({ code: SpanStatusCode.OK });
     span.end();

package/dist/cli.js

@@ -207,7 +207,14 @@ async function exportTraceCommand() {
             i++;
         }
         else if (args[i] === "--jaeger-url" && args[i + 1]) {
-            jaegerUrl = args[i + 1];
+            try {
+                new URL(args[i + 1]);
+                jaegerUrl = args[i + 1];
+            }
+            catch {
+                console.error(`❌ Invalid --jaeger-url: ${args[i + 1]}`);
+                process.exit(1);
+            }
             i++;
         }
     }

package/dist/context/error.d.ts

@@ -0,0 +1,15 @@
+/** Thrown when context guard blockAt threshold is exceeded. */
+export declare class ToadContextExceededError extends Error {
+    readonly utilization: number;
+    readonly threshold: number;
+    readonly model: string;
+    readonly maxContextTokens: number;
+    readonly inputTokens: number;
+    constructor(info: {
+        utilization: number;
+        threshold: number;
+        model: string;
+        maxContextTokens: number;
+        inputTokens: number;
+    });
+}

package/dist/context/error.js

@@ -0,0 +1,17 @@
+/** Thrown when context guard blockAt threshold is exceeded. */
+export class ToadContextExceededError extends Error {
+    utilization;
+    threshold;
+    model;
+    maxContextTokens;
+    inputTokens;
+    constructor(info) {
+        super(`toad-eye: context window ${(info.utilization * 100).toFixed(0)}% full (${info.inputTokens}/${info.maxContextTokens} tokens) for model ${info.model} — blocked at ${(info.threshold * 100).toFixed(0)}%`);
+        this.name = "ToadContextExceededError";
+        this.utilization = info.utilization;
+        this.threshold = info.threshold;
+        this.model = info.model;
+        this.maxContextTokens = info.maxContextTokens;
+        this.inputTokens = info.inputTokens;
+    }
+}

package/dist/context/guard.d.ts

@@ -0,0 +1,8 @@
+export declare function resetContextGuardState(): void;
+/**
+ * Check context utilization before an LLM call.
+ * - If utilization > blockAt → throw ToadContextExceededError
+ * - If utilization > warnAt → console.warn (once per model per session)
+ * - If model unknown or no guard configured → skip silently
+ */
+export declare function checkContextGuard(model: string, inputTokens: number): void;

package/dist/context/guard.js

@@ -0,0 +1,41 @@
+import { getModelPricing } from "../core/pricing.js";
+import { getConfig } from "../core/tracer.js";
+import { ToadContextExceededError } from "./error.js";
+let warnedModels = new Set();
+export function resetContextGuardState() {
+    warnedModels = new Set();
+}
+/**
+ * Check context utilization before an LLM call.
+ * - If utilization > blockAt → throw ToadContextExceededError
+ * - If utilization > warnAt → console.warn (once per model per session)
+ * - If model unknown or no guard configured → skip silently
+ */
+export function checkContextGuard(model, inputTokens) {
+    if (inputTokens <= 0)
+        return;
+    const config = getConfig();
+    const guard = config?.contextGuard;
+    if (!guard)
+        return;
+    const pricing = getModelPricing(model);
+    if (!pricing?.maxContextTokens)
+        return;
+    const utilization = inputTokens / pricing.maxContextTokens;
+    if (guard.blockAt !== undefined && utilization >= guard.blockAt) {
+        throw new ToadContextExceededError({
+            utilization,
+            threshold: guard.blockAt,
+            model,
+            maxContextTokens: pricing.maxContextTokens,
+            inputTokens,
+        });
+    }
+    if (guard.warnAt !== undefined && utilization >= guard.warnAt) {
+        const key = `${model}:${Math.floor(utilization * 10)}`;
+        if (!warnedModels.has(key)) {
+            warnedModels.add(key);
+            console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${model} (${inputTokens}/${pricing.maxContextTokens} tokens)`);
+        }
+    }
+}

package/dist/context/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/context/index.js

@@ -0,0 +1,4 @@
+export {};
+// Context module — post-call utilization monitoring only.
+// Pre-call blocking was removed (see #198) — API providers handle
+// context overflow natively, and pre-call token estimation is unreliable.

package/dist/core/metrics.d.ts

@@ -7,7 +7,8 @@ export declare function recordTokens(count: number, provider: string, model: str
 export declare function recordRequest(provider: string, model: string, attrs?: Record<string, string>): void;
 export declare function recordError(provider: string, model: string, attrs?: Record<string, string>): void;
 export declare function recordAgentSteps(stepCount: number): void;
-export declare function recordAgentToolUsage(toolName: string): void;
+export declare function recordAgentToolUsage(toolName: string, status?: "success" | "error"): void;
+export declare function recordAgentToolDuration(toolName: string, durationMs: number): void;
 export declare function recordGuardEvaluation(ruleName: string): void;
 export declare function recordGuardWouldBlock(ruleName: string): void;
 export declare function recordSemanticDrift(drift: number, provider: string, model: string): void;
@@ -17,3 +18,5 @@ export declare function recordBudgetBlocked(budgetType: string): void;
 export declare function recordBudgetDowngraded(budgetType: string): void;
 export declare function recordResponseEmpty(provider: string, model: string, attrs?: Record<string, string>): void;
 export declare function recordResponseLatencyPerToken(msPerToken: number, provider: string, model: string, attrs?: Record<string, string>): void;
+export declare function recordContextUtilization(utilization: number, provider: string, model: string): void;
+export declare function recordContextBlocked(model: string): void;

package/dist/core/metrics.js

@@ -7,6 +7,7 @@ let requestsTotal;
 let errorsTotal;
 let agentStepsPerQuery;
 let agentToolUsage;
+let agentToolDuration;
 let guardEvaluations;
 let guardWouldBlock;
 let semanticDrift;
@@ -16,6 +17,8 @@ let budgetBlocked;
 let budgetDowngraded;
 let responseEmpty;
 let responseLatencyPerToken;
+let contextUtilization;
+let contextBlocked;
 let initialized = false;
 export function initMetrics() {
     if (initialized)
@@ -42,7 +45,11 @@ export function initMetrics() {
         description: "Number of agent steps per query",
     });
     agentToolUsage = meter.createCounter(GEN_AI_METRICS.AGENT_TOOL_USAGE, {
-        description: "Agent tool invocations by tool name",
+        description: "Agent tool invocations by tool name and status",
+    });
+    agentToolDuration = meter.createHistogram(GEN_AI_METRICS.AGENT_TOOL_DURATION, {
+        description: "Agent tool execution duration in milliseconds",
+        unit: "ms",
     });
     guardEvaluations = meter.createCounter(GEN_AI_METRICS.GUARD_EVALUATIONS, {
         description: "Total guard evaluations (shadow + enforce)",
@@ -73,12 +80,22 @@ export function initMetrics() {
         description: "Generation latency normalized per output token (ms/token). Higher values indicate slower generation speed.",
         unit: "ms",
     });
+    contextUtilization = meter.createHistogram(GEN_AI_METRICS.CONTEXT_UTILIZATION, {
+        description: "Ratio of input tokens to model context window (0.0–1.0+). Values above 0.8 indicate risk of context overflow.",
+    });
+    contextBlocked = meter.createCounter(GEN_AI_METRICS.CONTEXT_BLOCKED, {
+        description: "Number of LLM calls blocked by context guard",
+    });
     initialized = true;
 }
 /** Reset metrics state so the next initMetrics() creates fresh instruments. Called from shutdown(). */
 export function resetMetrics() {
     initialized = false;
 }
+/** Returns true if metrics are safe to record. Prevents crash if called before initMetrics(). */
+function isReady() {
+    return initialized;
+}
 /** Build metric labels: provider + model + optional FinOps attributes. */
 function baseLabels(provider, model, attrs) {
     return {
@@ -88,62 +105,117 @@ function baseLabels(provider, model, attrs) {
     };
 }
 export function recordRequestDuration(ms, provider, model, attrs) {
+    if (!isReady())
+        return;
     requestDuration.record(ms, baseLabels(provider, model, attrs));
 }
 export function recordRequestCost(usd, provider, model, attrs) {
+    if (!isReady())
+        return;
     requestCost.record(usd, baseLabels(provider, model, attrs));
 }
 export function recordTokens(count, provider, model, attrs) {
+    if (!isReady())
+        return;
     tokenUsage.add(count, baseLabels(provider, model, attrs));
 }
 export function recordRequest(provider, model, attrs) {
+    if (!isReady())
+        return;
     requestsTotal.add(1, baseLabels(provider, model, attrs));
 }
 export function recordError(provider, model, attrs) {
+    if (!isReady())
+        return;
     errorsTotal.add(1, baseLabels(provider, model, attrs));
 }
 export function recordAgentSteps(stepCount) {
+    if (!isReady())
+        return;
     agentStepsPerQuery.record(stepCount);
 }
-export function recordAgentToolUsage(toolName) {
+export function recordAgentToolUsage(toolName, status = "success") {
+    if (!isReady())
+        return;
     agentToolUsage.add(1, {
         [GEN_AI_ATTRS.TOOL_NAME]: toolName,
+        "tool.status": status,
+    });
+}
+export function recordAgentToolDuration(toolName, durationMs) {
+    if (!isReady())
+        return;
+    agentToolDuration.record(durationMs, {
+        [GEN_AI_ATTRS.TOOL_NAME]: toolName,
     });
 }
 export function recordGuardEvaluation(ruleName) {
+    if (!isReady())
+        return;
     guardEvaluations.add(1, {
         [GEN_AI_ATTRS.GUARD_RULE_NAME]: ruleName,
     });
 }
 export function recordGuardWouldBlock(ruleName) {
+    if (!isReady())
+        return;
     guardWouldBlock.add(1, {
         [GEN_AI_ATTRS.GUARD_RULE_NAME]: ruleName,
     });
 }
 export function recordSemanticDrift(drift, provider, model) {
+    if (!isReady())
+        return;
     semanticDrift.record(drift, {
         [GEN_AI_ATTRS.PROVIDER]: provider,
         [GEN_AI_ATTRS.REQUEST_MODEL]: model,
     });
 }
 export function recordTimeToFirstToken(ms, provider, model) {
+    if (!isReady())
+        return;
     timeToFirstToken.record(ms, {
         [GEN_AI_ATTRS.PROVIDER]: provider,
         [GEN_AI_ATTRS.REQUEST_MODEL]: model,
     });
 }
 export function recordBudgetExceeded(budgetType) {
+    if (!isReady())
+        return;
     budgetExceeded.add(1, { budget_type: budgetType });
 }
 export function recordBudgetBlocked(budgetType) {
+    if (!isReady())
+        return;
     budgetBlocked.add(1, { budget_type: budgetType });
 }
 export function recordBudgetDowngraded(budgetType) {
+    if (!isReady())
+        return;
     budgetDowngraded.add(1, { budget_type: budgetType });
 }
 export function recordResponseEmpty(provider, model, attrs) {
+    if (!isReady())
+        return;
     responseEmpty.add(1, baseLabels(provider, model, attrs));
 }
 export function recordResponseLatencyPerToken(msPerToken, provider, model, attrs) {
+    if (!isReady())
+        return;
     responseLatencyPerToken.record(msPerToken, baseLabels(provider, model, attrs));
 }
+export function recordContextUtilization(utilization, provider, model) {
+    if (!isReady())
+        return;
+    contextUtilization.record(utilization, {
+        [GEN_AI_ATTRS.PROVIDER]: provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: model,
+    });
+}
+export function recordContextBlocked(model) {
+    if (!isReady())
+        return;
+    contextBlocked.add(1, {
+        [GEN_AI_ATTRS.REQUEST_MODEL]: model,
+    });
+}

package/dist/core/pricing.d.ts

@@ -6,6 +6,8 @@
 export interface ModelPricing {
     readonly inputPer1M: number;
     readonly outputPer1M: number;
+    /** Maximum context window size in tokens. Used to calculate context utilization ratio. */
+    readonly maxContextTokens?: number | undefined;
 }
 /**
  * Set custom pricing for models (overrides built-in prices).

package/dist/core/pricing.js

@@ -5,25 +5,62 @@
  */
 const BUILT_IN_PRICING = {
     // OpenAI
-    "gpt-4o": { inputPer1M: 2.5, outputPer1M: 10 },
-    "gpt-4o-mini": { inputPer1M: 0.15, outputPer1M: 0.6 },
-    "gpt-4-turbo": { inputPer1M: 10, outputPer1M: 30 },
-    "gpt-4.1": { inputPer1M: 2, outputPer1M: 8 },
-    "gpt-4.1-mini": { inputPer1M: 0.4, outputPer1M: 1.6 },
-    "gpt-4.1-nano": { inputPer1M: 0.1, outputPer1M: 0.4 },
-    o3: { inputPer1M: 10, outputPer1M: 40 },
-    "o3-mini": { inputPer1M: 1.1, outputPer1M: 4.4 },
-    "o4-mini": { inputPer1M: 1.1, outputPer1M: 4.4 },
+    "gpt-4o": { inputPer1M: 2.5, outputPer1M: 10, maxContextTokens: 128_000 },
+    "gpt-4o-mini": {
+        inputPer1M: 0.15,
+        outputPer1M: 0.6,
+        maxContextTokens: 128_000,
+    },
+    "gpt-4-turbo": { inputPer1M: 10, outputPer1M: 30, maxContextTokens: 128_000 },
+    "gpt-4.1": { inputPer1M: 2, outputPer1M: 8, maxContextTokens: 1_047_576 },
+    "gpt-4.1-mini": {
+        inputPer1M: 0.4,
+        outputPer1M: 1.6,
+        maxContextTokens: 1_047_576,
+    },
+    "gpt-4.1-nano": {
+        inputPer1M: 0.1,
+        outputPer1M: 0.4,
+        maxContextTokens: 1_047_576,
+    },
+    o3: { inputPer1M: 10, outputPer1M: 40, maxContextTokens: 200_000 },
+    "o3-mini": { inputPer1M: 1.1, outputPer1M: 4.4, maxContextTokens: 200_000 },
+    "o4-mini": { inputPer1M: 1.1, outputPer1M: 4.4, maxContextTokens: 200_000 },
     // Anthropic
-    "claude-opus-4-20250514": { inputPer1M: 15, outputPer1M: 75 },
-    "claude-sonnet-4-20250514": { inputPer1M: 3, outputPer1M: 15 },
-    "claude-haiku-3-5-20241022": { inputPer1M: 0.8, outputPer1M: 4 },
+    "claude-opus-4-20250514": {
+        inputPer1M: 15,
+        outputPer1M: 75,
+        maxContextTokens: 200_000,
+    },
+    "claude-sonnet-4-20250514": {
+        inputPer1M: 3,
+        outputPer1M: 15,
+        maxContextTokens: 200_000,
+    },
+    "claude-haiku-3-5-20241022": {
+        inputPer1M: 0.8,
+        outputPer1M: 4,
+        maxContextTokens: 200_000,
+    },
     // Google Gemini
-    "gemini-2.5-pro": { inputPer1M: 1.25, outputPer1M: 10 },
-    "gemini-2.5-flash": { inputPer1M: 0.15, outputPer1M: 0.6 },
-    "gemini-2.0-flash": { inputPer1M: 0.1, outputPer1M: 0.4 },
+    "gemini-2.5-pro": {
+        inputPer1M: 1.25,
+        outputPer1M: 10,
+        maxContextTokens: 1_048_576,
+    },
+    "gemini-2.5-flash": {
+        inputPer1M: 0.15,
+        outputPer1M: 0.6,
+        maxContextTokens: 1_048_576,
+    },
+    "gemini-2.0-flash": {
+        inputPer1M: 0.1,
+        outputPer1M: 0.4,
+        maxContextTokens: 1_048_576,
+    },
 };
 let customPricing = {};
+const warnedModels = new Set();
 /**
  * Set custom pricing for models (overrides built-in prices).
  * Useful for enterprise contracts or custom/fine-tuned models.
@@ -34,6 +71,7 @@ export function setCustomPricing(pricing) {
 /** Reset custom pricing to empty. Called from shutdown() to avoid stale state across re-inits. */
 export function resetCustomPricing() {
     customPricing = {};
+    warnedModels.clear();
 }
 /**
  * Get pricing for a model. Custom pricing takes precedence.
@@ -50,8 +88,15 @@ export function calculateCost(model, inputTokens, outputTokens) {
     if (inputTokens < 0 || outputTokens < 0)
         return 0;
     const pricing = getModelPricing(model);
-    if (!pricing)
+    if (!pricing) {
+        if (inputTokens + outputTokens > 0 && !warnedModels.has(model)) {
+            if (warnedModels.size >= 100)
+                warnedModels.clear();
+            warnedModels.add(model);
+            console.warn(`toad-eye: unknown pricing for "${model}" — cost reported as $0. Use setCustomPricing() to set rates.`);
+        }
         return 0;
+    }
     const cost = (inputTokens / 1_000_000) * pricing.inputPer1M +
         (outputTokens / 1_000_000) * pricing.outputPer1M;
     return Math.round(cost * 1_000_000) / 1_000_000;

package/dist/core/spans.d.ts

@@ -5,6 +5,8 @@ export interface LLMCallInput {
     readonly model: string;
     readonly prompt: string;
     readonly temperature?: number | undefined;
+    /** OTel operation name for span naming. Default: "chat". */
+    readonly operationName?: string | undefined;
     /** Per-request FinOps attributes (team, userId, feature, etc). Merged with global attributes. */
     readonly attributes?: Readonly<Record<string, string>> | undefined;
 }

package/dist/core/spans.js

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
-import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordBudgetExceeded, recordBudgetBlocked, recordBudgetDowngraded, recordResponseEmpty, recordResponseLatencyPerToken, } from "./metrics.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordBudgetExceeded, recordBudgetBlocked, recordBudgetDowngraded, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, } from "./metrics.js";
 import { getConfig, getBudgetTracker } from "./tracer.js";
-import { calculateCost } from "./pricing.js";
+import { calculateCost, getModelPricing } from "./pricing.js";
 import { ToadBudgetExceededError } from "../budget/index.js";
 const tracer = trace.getTracer(INSTRUMENTATION_NAME);
 let saltWarningEmitted = false;
@@ -46,6 +46,11 @@ export function processContent(text) {
     const config = getConfig();
     if (config?.recordContent === false)
         return undefined;
+    // Content sampling — record only a fraction of calls
+    if (config?.contentSamplingRate !== undefined) {
+        if (Math.random() >= config.contentSamplingRate)
+            return undefined;
+    }
     let processed = text;
     let totalRedacted = 0;
     // Apply default PII patterns if enabled
@@ -59,9 +64,14 @@ export function processContent(text) {
     // Apply custom patterns
     if (config?.redactPatterns?.length) {
         for (const pattern of config.redactPatterns) {
-            const [result, count] = applyRedaction(processed, pattern);
-            processed = result;
-            totalRedacted += count;
+            try {
+                const [result, count] = applyRedaction(processed, pattern);
+                processed = result;
+                totalRedacted += count;
+            }
+            catch {
+                console.warn(`toad-eye: invalid redact pattern skipped: ${pattern.source}`);
+            }
         }
     }
     // Audit mode — log a summary only, never the original content (would re-expose PII)
@@ -93,7 +103,7 @@ function setBaseAttributes(span, input) {
         [GEN_AI_ATTRS.PROVIDER]: input.provider,
         [GEN_AI_ATTRS.REQUEST_MODEL]: input.model,
         [GEN_AI_ATTRS.TEMPERATURE]: input.temperature ?? 1.0,
-        [GEN_AI_ATTRS.OPERATION]: "chat",
+        [GEN_AI_ATTRS.OPERATION]: input.operationName ?? "chat",
         ...(prompt !== undefined && { [GEN_AI_ATTRS.PROMPT]: prompt }),
         ...(sessionId !== undefined && { [GEN_AI_ATTRS.SESSION_ID]: sessionId }),
         ...attrs,
@@ -153,7 +163,8 @@ export async function traceLLMCall(input, fn) {
             recordBudgetDowngraded(override.budget);
         }
     }
-    return tracer.startActiveSpan(`chat ${effectiveInput.model}`, async (span) => {
+    const op = effectiveInput.operationName ?? "chat";
+    return tracer.startActiveSpan(`${op} ${effectiveInput.model}`, async (span) => {
         const start = performance.now();
         setBaseAttributes(span, effectiveInput);
         try {
@@ -173,6 +184,31 @@ export async function traceLLMCall(input, fn) {
             if (output.outputTokens > 0) {
                 recordResponseLatencyPerToken(duration / output.outputTokens, effectiveInput.provider, effectiveInput.model, attrs);
             }
+            // Context window utilization — ratio of input tokens to model's max context
+            const pricing = getModelPricing(effectiveInput.model);
+            if (pricing?.maxContextTokens && output.inputTokens > 0) {
+                const utilization = output.inputTokens / pricing.maxContextTokens;
+                span.setAttribute(GEN_AI_ATTRS.CONTEXT_UTILIZATION, utilization);
+                recordContextUtilization(utilization, effectiveInput.provider, effectiveInput.model);
+                // Context guard — post-call warning when approaching limit.
+                // This warns about the CURRENT call's context usage so agents
+                // can compress context before the NEXT call.
+                const guard = getConfig()?.contextGuard;
+                if (guard) {
+                    if (guard.alertAt !== undefined && utilization >= guard.alertAt) {
+                        recordContextBlocked(effectiveInput.model);
+                        span.addEvent("gen_ai.context.limit_exceeded", {
+                            "gen_ai.toad_eye.context_utilization": utilization,
+                            "gen_ai.toad_eye.context.threshold": guard.alertAt,
+                        });
+                        console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${effectiveInput.model} — exceeds alertAt threshold ${(guard.alertAt * 100).toFixed(0)}%. Compress context before next call.`);
+                    }
+                    else if (guard.warnAt !== undefined &&
+                        utilization >= guard.warnAt) {
+                        console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${effectiveInput.model} (${output.inputTokens}/${pricing.maxContextTokens} tokens)`);
+                    }
+                }
+            }
             // Budget recording AFTER the call — releases the cost reservation
             if (budget) {
                 const userId = effectiveInput.attributes?.[GEN_AI_ATTRS.USER_ID];
@@ -190,15 +226,18 @@ export async function traceLLMCall(input, fn) {
             const attrs = resolveAttributes(effectiveInput);
             setErrorAttributes(span, message);
             recordBaseMetrics(duration, effectiveInput.provider, effectiveInput.model, attrs);
-            recordError(effectiveInput.provider, effectiveInput.model, attrs);
             // Release cost reservation on any error (no cost was incurred)
             if (budget) {
                 budget.releaseReservation(estimatedCost);
             }
-            // If this was a budget block, record the metric with the correct budget type
             if (error instanceof ToadBudgetExceededError) {
+                // Budget blocks are intentional guardrails, not errors — record
+                // only the budget-specific metric to avoid inflating error rate
                 recordBudgetBlocked(error.budget);
             }
+            else {
+                recordError(effectiveInput.provider, effectiveInput.model, attrs);
+            }
             throw error;
         }
         finally {

package/dist/core/tracer.js

@@ -40,6 +40,10 @@ function validateConfig(config) {
     if (config.apiKey !== undefined && !config.apiKey.startsWith("toad_")) {
         throw new Error('toad-eye: apiKey must start with "toad_" prefix');
     }
+    if (config.onBudgetExceeded === "downgrade" &&
+        config.downgradeCallback === undefined) {
+        throw new Error('toad-eye: downgradeCallback is required when onBudgetExceeded is "downgrade"');
+    }
 }
 /** Resolve endpoint and auth headers based on config mode (self-hosted vs cloud). */
 function resolveTransport(config) {
@@ -123,7 +127,9 @@ export function initObservability(config) {
         if (patchProviders.length > 0) {
             // enableAll is async (lazy-loads provider modules on first call).
             // Fire-and-forget: patching completes before any async SDK call.
-            void enableAll(patchProviders);
+            void enableAll(patchProviders).catch((err) => {
+                console.warn(`toad-eye: auto-instrumentation failed: ${err instanceof Error ? err.message : err}`);
+            });
         }
     }
 }

package/dist/instrumentations/anthropic.js

@@ -47,8 +47,14 @@ const messagesCreate = {
     isStreaming: (body) => !!body?.stream,
     accumulateChunk: (acc, chunk) => {
         const event = chunk;
-        if (event.type === "content_block_delta" && event.delta?.text) {
-            acc.completion += event.delta.text;
+        if (event.type === "content_block_delta") {
+            if (event.delta?.type === "thinking_delta" && event.delta.thinking) {
+                // Extended thinking — track separately from completion
+                acc.thinkingContent += event.delta.thinking;
+            }
+            else if (event.delta?.text) {
+                acc.completion += event.delta.text;
+            }
         }
         // Tool use: content_block_start with type "tool_use"
         if (event.type === "content_block_start" &&