toad-eye 2.4.4 → 2.5.0

package/README.md

@@ -385,7 +385,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/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,2 @@
+export { ToadContextExceededError } from "./error.js";
+export { checkContextGuard, resetContextGuardState } from "./guard.js";

package/dist/context/index.js

@@ -0,0 +1,2 @@
+export { ToadContextExceededError } from "./error.js";
+export { checkContextGuard, resetContextGuardState } from "./guard.js";

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,6 +80,12 @@ 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(). */
@@ -105,9 +118,15 @@ export function recordError(provider, model, attrs) {
 export function recordAgentSteps(stepCount) {
     agentStepsPerQuery.record(stepCount);
 }
-export function recordAgentToolUsage(toolName) {
+export function recordAgentToolUsage(toolName, status = "success") {
     agentToolUsage.add(1, {
         [GEN_AI_ATTRS.TOOL_NAME]: toolName,
+        "tool.status": status,
+    });
+}
+export function recordAgentToolDuration(toolName, durationMs) {
+    agentToolDuration.record(durationMs, {
+        [GEN_AI_ATTRS.TOOL_NAME]: toolName,
     });
 }
 export function recordGuardEvaluation(ruleName) {
@@ -147,3 +166,14 @@ export function recordResponseEmpty(provider, model, attrs) {
 export function recordResponseLatencyPerToken(msPerToken, provider, model, attrs) {
     responseLatencyPerToken.record(msPerToken, baseLabels(provider, model, attrs));
 }
+export function recordContextUtilization(utilization, provider, model) {
+    contextUtilization.record(utilization, {
+        [GEN_AI_ATTRS.PROVIDER]: provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: model,
+    });
+}
+export function recordContextBlocked(model) {
+    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,23 +5,59 @@
  */
 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 = {};
 /**

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;
@@ -173,6 +173,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.blockAt !== undefined && utilization >= guard.blockAt) {
+                        recordContextBlocked(effectiveInput.model);
+                        span.addEvent("gen_ai.context.limit_exceeded", {
+                            "gen_ai.toad_eye.context_utilization": utilization,
+                            "gen_ai.toad_eye.context.threshold": guard.blockAt,
+                        });
+                        console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${effectiveInput.model} — exceeds blockAt threshold ${(guard.blockAt * 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];

package/dist/core/tracer.js

@@ -7,6 +7,7 @@ import { TraceIdRatioBasedSampler, ParentBasedSampler, BatchSpanProcessor, } fro
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { initMetrics, resetMetrics } from "./metrics.js";
 import { resetCustomPricing } from "./pricing.js";
+import { resetContextGuardState } from "../context/guard.js";
 import { enableAll, disableAll } from "../instrumentations/registry.js";
 import { BudgetTracker } from "../budget/index.js";
 import { ToadEyeAISpanProcessor } from "../vercel.js";
@@ -137,4 +138,5 @@ export async function shutdown() {
     budgetTracker = null;
     resetMetrics();
     resetCustomPricing();
+    resetContextGuardState();
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { initObservability, shutdown, getConfig, getBudgetTracker, } from "./core/tracer.js";
 export { BudgetTracker, ToadBudgetExceededError } from "./budget/index.js";
+export { ToadContextExceededError } from "./context/index.js";
 export type { BudgetConfig, BudgetExceededMode, BudgetExceededInfo, DowngradeCallback, } from "./budget/index.js";
 export { AlertManager, startAlertsFromFile, parseCondition, } from "./alerts/index.js";
 export type { AlertsConfig, AlertRule, AlertChannelConfig, FiredAlert, } from "./alerts/index.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { initObservability, shutdown, getConfig, getBudgetTracker, } from "./core/tracer.js";
 export { BudgetTracker, ToadBudgetExceededError } from "./budget/index.js";
+export { ToadContextExceededError } from "./context/index.js";
 export { AlertManager, startAlertsFromFile, parseCondition, } from "./alerts/index.js";
 export { traceLLMCall } from "./core/spans.js";
 export { traceAgentStep, traceAgentQuery } from "./agent.js";

package/dist/instrumentations/anthropic.js

@@ -47,8 +47,31 @@ 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" &&
+            event.content_block?.type === "tool_use") {
+            acc.toolCalls.push({
+                name: event.content_block.name ?? "",
+                arguments: "",
+                id: event.content_block.id,
+            });
+        }
+        // Tool use: input_json_delta accumulates arguments
+        if (event.type === "content_block_delta" &&
+            event.delta?.type === "input_json_delta" &&
+            event.delta.partial_json) {
+            const last = acc.toolCalls[acc.toolCalls.length - 1];
+            if (last)
+                last.arguments += event.delta.partial_json;
         }
         if (event.type === "message_start" && event.message?.usage) {
             acc.inputTokens = event.message.usage.input_tokens ?? 0;

package/dist/instrumentations/create.js

@@ -1,8 +1,8 @@
 import { createRequire } from "node:module";
 import { trace, context, diag, SpanStatusCode, } from "@opentelemetry/api";
 import { traceLLMCall, processContent } from "../core/spans.js";
-import { calculateCost } from "../core/pricing.js";
-import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordTimeToFirstToken, recordResponseEmpty, recordResponseLatencyPerToken, recordBudgetExceeded, recordBudgetDowngraded, } from "../core/metrics.js";
+import { calculateCost, getModelPricing } from "../core/pricing.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordTimeToFirstToken, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, recordBudgetExceeded, recordBudgetDowngraded, } from "../core/metrics.js";
 import { getConfig, getBudgetTracker } from "../core/tracer.js";
 import { ToadBudgetExceededError } from "../budget/index.js";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
@@ -31,8 +31,10 @@ function loadModule(moduleName) {
 async function* wrapAsyncIterable(stream, accumulate, onFirstChunk, onComplete, onError) {
     const acc = {
         completion: "",
+        thinkingContent: "",
         inputTokens: 0,
         outputTokens: 0,
+        toolCalls: [],
     };
     let firstChunk = true;
     let completed = false;
@@ -66,6 +68,14 @@ function createStreamingHandler(
 original, patch, providerName) {
     const tracer = trace.getTracer(INSTRUMENTATION_NAME);
     return async function handleStreaming(thisArg, body, rest) {
+        // OpenAI does not send usage in streaming chunks by default.
+        // Auto-inject stream_options to get token counts in the final chunk.
+        if (providerName === "openai") {
+            const b = body;
+            if (!b["stream_options"]) {
+                b["stream_options"] = { include_usage: true };
+            }
+        }
         // Pass thisArg so extractRequest can access instance properties (e.g., Gemini model name)
         const req = patch.extractRequest(body, thisArg);
         const start = performance.now();
@@ -87,6 +97,7 @@ original, patch, providerName) {
         const span = tracer.startSpan(`chat ${effectiveModel}`);
         const ctx = trace.setSpan(context.active(), span);
         const sessionId = config?.sessionExtractor?.() ?? config?.sessionId;
+        let ttftMs = 0;
         span.setAttributes({
             [GEN_AI_ATTRS.PROVIDER]: effectiveProvider,
             [GEN_AI_ATTRS.REQUEST_MODEL]: effectiveModel,
@@ -127,11 +138,27 @@ original, patch, providerName) {
             ? resp["stream"]
             : response;
         const wrapped = context.bind(ctx, wrapAsyncIterable(streamIterable, (acc, chunk) => patch.accumulateChunk(acc, chunk), () => {
-            recordTimeToFirstToken(performance.now() - start, effectiveProvider, effectiveModel);
+            const ttft = performance.now() - start;
+            ttftMs = ttft;
+            recordTimeToFirstToken(ttft, effectiveProvider, effectiveModel);
+            // Span event for per-trace TTFT debugging in Jaeger
+            span.addEvent("gen_ai.content.first_token", {
+                "gen_ai.response.time_to_first_token_ms": ttft,
+            });
+            span.setAttribute("gen_ai.response.time_to_first_token_ms", ttft);
         }, (acc) => {
             const duration = performance.now() - start;
             const cost = calculateCost(effectiveModel, acc.inputTokens, acc.outputTokens);
             const processedCompletion = processContent(acc.completion);
+            // Anthropic extended thinking — track separately from completion
+            if (acc.thinkingContent.length > 0) {
+                span.setAttribute("gen_ai.toad_eye.thinking.content_length", acc.thinkingContent.length);
+            }
+            // Record tool calls from streaming chunks
+            if (acc.toolCalls.length > 0) {
+                span.setAttribute(GEN_AI_ATTRS.TOOL_NAME, acc.toolCalls.map((t) => t.name).join(", "));
+                span.setAttribute("gen_ai.tool.call.count", acc.toolCalls.length);
+            }
             span.setAttributes({
                 ...(processedCompletion !== undefined && {
                     [GEN_AI_ATTRS.COMPLETION]: processedCompletion,
@@ -156,6 +183,37 @@ original, patch, providerName) {
             if (acc.outputTokens > 0) {
                 recordResponseLatencyPerToken(duration / acc.outputTokens, effectiveProvider, effectiveModel);
             }
+            // Context window utilization — ratio of input tokens to model's max context
+            const pricing = getModelPricing(effectiveModel);
+            if (pricing?.maxContextTokens && acc.inputTokens > 0) {
+                const utilization = acc.inputTokens / pricing.maxContextTokens;
+                span.setAttribute(GEN_AI_ATTRS.CONTEXT_UTILIZATION, utilization);
+                recordContextUtilization(utilization, effectiveProvider, effectiveModel);
+                // Context guard — post-stream warning
+                const guard = config?.contextGuard;
+                if (guard) {
+                    if (guard.blockAt !== undefined && utilization >= guard.blockAt) {
+                        recordContextBlocked(effectiveModel);
+                        span.addEvent("gen_ai.context.limit_exceeded", {
+                            "gen_ai.toad_eye.context_utilization": utilization,
+                            "gen_ai.toad_eye.context.threshold": guard.blockAt,
+                        });
+                        console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${effectiveModel} — exceeds blockAt threshold ${(guard.blockAt * 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 ${effectiveModel} (${acc.inputTokens}/${pricing.maxContextTokens} tokens)`);
+                    }
+                }
+            }
+            // Prefill/decode latency split — TTFT = prefill, rest = decode
+            if (ttftMs > 0) {
+                const decodeMs = duration - ttftMs;
+                span.setAttribute("gen_ai.toad_eye.latency.decode_ms", decodeMs);
+                if (acc.outputTokens > 0 && decodeMs > 0) {
+                    span.setAttribute("gen_ai.toad_eye.throughput.tokens_per_second", acc.outputTokens / (decodeMs / 1000));
+                }
+            }
             // Budget recording — releases the reservation made in checkBefore
             if (budget) {
                 const exceeded = budget.recordCost(cost, effectiveModel, userId, estimatedCost);

package/dist/instrumentations/gemini.js

@@ -66,6 +66,18 @@ const generateContentStream = {
         catch {
             // text() may throw if content is blocked
         }
+        // Gemini function calls in streaming
+        const parts = c?.candidates?.[0]?.content?.parts;
+        if (parts) {
+            for (const part of parts) {
+                if (part.functionCall) {
+                    acc.toolCalls.push({
+                        name: part.functionCall.name,
+                        arguments: JSON.stringify(part.functionCall.args ?? {}),
+                    });
+                }
+            }
+        }
         if (c?.usageMetadata) {
             acc.inputTokens = c.usageMetadata.promptTokenCount ?? acc.inputTokens;
             acc.outputTokens =

package/dist/instrumentations/openai.js

@@ -47,9 +47,26 @@ const chatCompletions = {
     isStreaming: (body) => !!body?.stream,
     accumulateChunk: (acc, chunk) => {
         const c = chunk;
-        const delta = c?.choices?.[0]?.delta?.content;
-        if (delta)
-            acc.completion += delta;
+        const delta = c?.choices?.[0]?.delta;
+        if (delta?.content)
+            acc.completion += delta.content;
+        // Accumulate tool calls from streaming chunks
+        if (delta?.tool_calls) {
+            for (const tc of delta.tool_calls) {
+                const existing = acc.toolCalls[tc.index];
+                if (existing) {
+                    if (tc.function?.arguments)
+                        existing.arguments += tc.function.arguments;
+                }
+                else {
+                    acc.toolCalls[tc.index] = {
+                        name: tc.function?.name ?? "",
+                        arguments: tc.function?.arguments ?? "",
+                        id: tc.id,
+                    };
+                }
+            }
+        }
         if (c?.usage) {
             acc.inputTokens = c.usage.prompt_tokens ?? acc.inputTokens;
             acc.outputTokens = c.usage.completion_tokens ?? acc.outputTokens;

package/dist/instrumentations/types.d.ts

@@ -6,11 +6,20 @@ export interface Instrumentation {
     /** Restore original methods. */
     disable(): void;
 }
+/** Tool call accumulated from streaming chunks. */
+export interface AccumulatedToolCall {
+    name: string;
+    arguments: string;
+    id?: string | undefined;
+}
 /** Accumulated stream data — only primitives, no raw SDK objects. */
 export interface StreamAccumulator {
     completion: string;
+    /** Anthropic extended thinking content (tracked separately from completion). */
+    thinkingContent: string;
     inputTokens: number;
     outputTokens: number;
+    toolCalls: AccumulatedToolCall[];
 }
 /** Describes a single method to monkey-patch on an SDK prototype. */
 export interface PatchTarget {

package/dist/types/attributes.d.ts

@@ -47,6 +47,7 @@ export declare const GEN_AI_ATTRS: {
     readonly COMPLETION: "gen_ai.toad_eye.completion";
     readonly COST: "gen_ai.toad_eye.cost";
     readonly STATUS: "gen_ai.toad_eye.status";
+    readonly CONTEXT_UTILIZATION: "gen_ai.toad_eye.context_utilization";
     readonly SESSION_ID: "session.id";
     readonly TEAM: "toad_eye.team";
     readonly USER_ID: "toad_eye.user_id";

package/dist/types/attributes.js

@@ -53,6 +53,7 @@ export const GEN_AI_ATTRS = {
     COMPLETION: "gen_ai.toad_eye.completion",
     COST: "gen_ai.toad_eye.cost",
     STATUS: "gen_ai.toad_eye.status",
+    CONTEXT_UTILIZATION: "gen_ai.toad_eye.context_utilization",
     SESSION_ID: "session.id",
     // FinOps attribution
     TEAM: "toad_eye.team",

package/dist/types/config.d.ts

@@ -47,6 +47,13 @@ export interface ToadEyeConfig {
     readonly onBudgetExceeded?: BudgetExceededMode | undefined;
     /** Callback for 'downgrade' mode — receives original provider/model, returns replacement. */
     readonly downgradeCallback?: DowngradeCallback | undefined;
+    /** Warn or block when context window utilization exceeds thresholds. */
+    readonly contextGuard?: {
+        /** Warn when utilization exceeds this ratio (0.0–1.0). Default: none. */
+        readonly warnAt?: number | undefined;
+        /** Block (throw ToadContextExceededError) when utilization exceeds this ratio. Default: none. */
+        readonly blockAt?: number | undefined;
+    } | undefined;
     /** Static session ID — all spans will carry this value as `session.id`. */
     readonly sessionId?: string | undefined;
     /** Dynamic session ID extractor — called per traceLLMCall to resolve session ID. */

package/dist/types/metrics.d.ts

@@ -14,6 +14,7 @@ export declare const GEN_AI_METRICS: {
     readonly ERRORS: "gen_ai.client.errors";
     readonly AGENT_STEPS_PER_QUERY: "gen_ai.agent.steps_per_query";
     readonly AGENT_TOOL_USAGE: "gen_ai.agent.tool_usage";
+    readonly AGENT_TOOL_DURATION: "gen_ai.agent.tool_duration";
     readonly GUARD_EVALUATIONS: "gen_ai.toad_eye.guard.evaluations";
     readonly GUARD_WOULD_BLOCK: "gen_ai.toad_eye.guard.would_block";
     readonly SEMANTIC_DRIFT: "gen_ai.toad_eye.semantic_drift";
@@ -23,6 +24,8 @@ export declare const GEN_AI_METRICS: {
     readonly BUDGET_DOWNGRADED: "gen_ai.toad_eye.budget.downgraded";
     readonly RESPONSE_EMPTY: "gen_ai.toad_eye.response.empty";
     readonly RESPONSE_LATENCY_PER_TOKEN: "gen_ai.toad_eye.response.latency_per_token";
+    readonly CONTEXT_UTILIZATION: "gen_ai.toad_eye.context_utilization";
+    readonly CONTEXT_BLOCKED: "gen_ai.toad_eye.context.blocked";
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export declare const LLM_METRICS: {