toad-eye 2.2.0 → 2.4.0

package/dist/drift/monitor.js

@@ -39,13 +39,13 @@ export function createDriftMonitor(config) {
     return {
         check: performCheck,
         checkInBackground(response, providerName, model) {
-            const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error("Drift check timeout (5s)")), 5000));
-            void Promise.race([
-                performCheck(response, providerName, model),
-                timeout,
-            ]).catch((err) => {
+            let timer;
+            const timeout = new Promise((_, reject) => (timer = setTimeout(() => reject(new Error("Drift check timeout (5s)")), 5000)));
+            void Promise.race([performCheck(response, providerName, model), timeout])
+                .catch((err) => {
                 console.warn(`[toad-eye] Drift check failed (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
-            });
+            })
+                .finally(() => clearTimeout(timer));
         },
     };
 }

package/dist/index.d.ts

@@ -13,5 +13,10 @@ export type { ExportTraceOptions } from "./export.js";
 export { calculateCost, setCustomPricing, getModelPricing, } from "./core/pricing.js";
 export type { ModelPricing } from "./core/pricing.js";
 export type { LLMCallInput, LLMCallOutput } from "./core/spans.js";
-export type { ToadEyeConfig, LLMSpanAttributes, LLMProvider, SpanStatus, MetricName, AgentStepType, AgentStepInput, GuardMode, GuardResult, } from "./types/index.js";
-export { GEN_AI_METRICS, GEN_AI_ATTRS, LLM_METRICS, LLM_ATTRS, } from "./types/index.js";
+export type { ToadEyeConfig, LLMSpanAttributes, LLMProvider, SpanStatus, MetricName, AgentStepType, AgentStepInput, AgentQueryOptions, GuardMode, GuardResult, InstrumentTarget, SamplingConfig, } from "./types/index.js";
+export { GEN_AI_METRICS, GEN_AI_ATTRS } from "./types/index.js";
+/** @deprecated Use GEN_AI_METRICS instead */
+export { LLM_METRICS } from "./types/index.js";
+/** @deprecated Use GEN_AI_ATTRS instead */
+export { LLM_ATTRS } from "./types/index.js";
+export { ToadEyeAISpanProcessor, withToadEye } from "./vercel.js";

package/dist/index.js

@@ -7,4 +7,9 @@ export { recordGuardResult } from "./guard.js";
 export { createDriftMonitor, createOpenAIEmbeddingProvider, cosineSimilarity, cosineDrift, saveBaseline, loadBaseline, } from "./drift/index.js";
 export { exportTrace, fetchTrace, traceToEvalYaml } from "./export.js";
 export { calculateCost, setCustomPricing, getModelPricing, } from "./core/pricing.js";
-export { GEN_AI_METRICS, GEN_AI_ATTRS, LLM_METRICS, LLM_ATTRS, } from "./types/index.js";
+export { GEN_AI_METRICS, GEN_AI_ATTRS } from "./types/index.js";
+/** @deprecated Use GEN_AI_METRICS instead */
+export { LLM_METRICS } from "./types/index.js";
+/** @deprecated Use GEN_AI_ATTRS instead */
+export { LLM_ATTRS } from "./types/index.js";
+export { ToadEyeAISpanProcessor, withToadEye } from "./vercel.js";

package/dist/instrumentations/anthropic.d.ts

@@ -1 +1 @@
-export {};
+export declare const anthropicInstrumentation: import("./types.js").Instrumentation;

package/dist/instrumentations/anthropic.js

@@ -1,4 +1,3 @@
-import { register } from "./registry.js";
 import { createInstrumentation } from "./create.js";
 function extractMessages(messages) {
     if (!Array.isArray(messages))
@@ -59,8 +58,8 @@ const messagesCreate = {
         }
     },
 };
-register(createInstrumentation({
+export const anthropicInstrumentation = createInstrumentation({
     name: "anthropic",
     moduleName: "@anthropic-ai/sdk",
     patches: [messagesCreate],
-}));
+});

package/dist/instrumentations/create.js

@@ -1,8 +1,10 @@
 import { createRequire } from "node:module";
 import { trace, context, diag, SpanStatusCode, } from "@opentelemetry/api";
-import { traceLLMCall } from "../core/spans.js";
+import { traceLLMCall, processContent } from "../core/spans.js";
 import { calculateCost } from "../core/pricing.js";
-import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordTimeToFirstToken, } from "../core/metrics.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordTimeToFirstToken, recordResponseEmpty, recordResponseLatencyPerToken, 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";
 const require = createRequire(import.meta.url);
 function isModuleInstalled(moduleName) {
@@ -64,17 +66,55 @@ function createStreamingHandler(
 original, patch, providerName) {
     const tracer = trace.getTracer(INSTRUMENTATION_NAME);
     return async function handleStreaming(thisArg, body, rest) {
-        const req = patch.extractRequest(body);
+        // Pass thisArg so extractRequest can access instance properties (e.g., Gemini model name)
+        const req = patch.extractRequest(body, thisArg);
         const start = performance.now();
-        const response = await original.call(thisArg, body, ...rest);
-        const span = tracer.startSpan(`gen_ai.${providerName}.${req.model}`);
+        // Budget check BEFORE the LLM call — mirrors traceLLMCall behavior
+        const budget = getBudgetTracker();
+        const config = getConfig();
+        const userId = config?.attributes?.[GEN_AI_ATTRS.USER_ID];
+        const estimatedCost = budget ? calculateCost(req.model, 500, 200) : 0;
+        let effectiveProvider = providerName;
+        let effectiveModel = req.model;
+        if (budget) {
+            const override = budget.checkBefore(providerName, req.model, userId, estimatedCost);
+            if (override) {
+                effectiveProvider = override.provider;
+                effectiveModel = override.model;
+                recordBudgetDowngraded(override.budget);
+            }
+        }
+        const span = tracer.startSpan(`chat ${effectiveModel}`);
         const ctx = trace.setSpan(context.active(), span);
+        const sessionId = config?.sessionExtractor?.() ?? config?.sessionId;
         span.setAttributes({
-            [GEN_AI_ATTRS.PROVIDER]: providerName,
-            [GEN_AI_ATTRS.REQUEST_MODEL]: req.model,
+            [GEN_AI_ATTRS.PROVIDER]: effectiveProvider,
+            [GEN_AI_ATTRS.REQUEST_MODEL]: effectiveModel,
             [GEN_AI_ATTRS.TEMPERATURE]: req.temperature ?? 1.0,
             [GEN_AI_ATTRS.OPERATION]: "chat",
+            ...(sessionId !== undefined && { [GEN_AI_ATTRS.SESSION_ID]: sessionId }),
         });
+        let response;
+        try {
+            response = await original.call(thisArg, body, ...rest);
+        }
+        catch (err) {
+            const duration = performance.now() - start;
+            const message = err instanceof Error ? err.message : String(err);
+            // Release budget reservation — no cost was incurred
+            if (budget)
+                budget.releaseReservation(estimatedCost);
+            span.setAttributes({
+                [GEN_AI_ATTRS.STATUS]: "error",
+                [GEN_AI_ATTRS.ERROR]: message,
+            });
+            span.setStatus({ code: SpanStatusCode.ERROR, message });
+            span.end();
+            recordRequest(effectiveProvider, effectiveModel);
+            recordRequestDuration(duration, effectiveProvider, effectiveModel);
+            recordError(effectiveProvider, effectiveModel);
+            throw err;
+        }
         // Some SDKs (Gemini) return { stream: AsyncIterable } instead of a direct AsyncIterable
         const resp = response;
         const hasStreamProp = resp != null &&
@@ -87,13 +127,16 @@ original, patch, providerName) {
             ? resp["stream"]
             : response;
         const wrapped = context.bind(ctx, wrapAsyncIterable(streamIterable, (acc, chunk) => patch.accumulateChunk(acc, chunk), () => {
-            const ttft = performance.now() - start;
-            recordTimeToFirstToken(ttft, providerName, req.model);
+            recordTimeToFirstToken(performance.now() - start, effectiveProvider, effectiveModel);
         }, (acc) => {
             const duration = performance.now() - start;
-            const cost = calculateCost(req.model, acc.inputTokens, acc.outputTokens);
+            const cost = calculateCost(effectiveModel, acc.inputTokens, acc.outputTokens);
+            const processedCompletion = processContent(acc.completion);
             span.setAttributes({
-                [GEN_AI_ATTRS.RESPONSE_MODEL]: req.model,
+                ...(processedCompletion !== undefined && {
+                    [GEN_AI_ATTRS.COMPLETION]: processedCompletion,
+                }),
+                [GEN_AI_ATTRS.RESPONSE_MODEL]: effectiveModel,
                 [GEN_AI_ATTRS.INPUT_TOKENS]: acc.inputTokens,
                 [GEN_AI_ATTRS.OUTPUT_TOKENS]: acc.outputTokens,
                 [GEN_AI_ATTRS.COST]: cost,
@@ -102,22 +145,40 @@ original, patch, providerName) {
             });
             span.setStatus({ code: SpanStatusCode.OK });
             span.end();
-            recordRequest(providerName, req.model);
-            recordRequestDuration(duration, providerName, req.model);
-            recordRequestCost(cost, providerName, req.model);
-            recordTokens(acc.inputTokens + acc.outputTokens, providerName, req.model);
+            recordRequest(effectiveProvider, effectiveModel);
+            recordRequestDuration(duration, effectiveProvider, effectiveModel);
+            recordRequestCost(cost, effectiveProvider, effectiveModel);
+            recordTokens(acc.inputTokens + acc.outputTokens, effectiveProvider, effectiveModel);
+            // Quality metrics
+            if (acc.completion.trim() === "") {
+                recordResponseEmpty(effectiveProvider, effectiveModel);
+            }
+            if (acc.outputTokens > 0) {
+                recordResponseLatencyPerToken(duration / acc.outputTokens, effectiveProvider, effectiveModel);
+            }
+            // Budget recording — releases the reservation made in checkBefore
+            if (budget) {
+                const exceeded = budget.recordCost(cost, effectiveModel, userId, estimatedCost);
+                if (exceeded) {
+                    recordBudgetExceeded(exceeded.budget);
+                    console.warn(`toad-eye: ${exceeded.budget} budget exceeded — limit $${exceeded.limit}, current $${exceeded.current.toFixed(2)}`);
+                }
+            }
         }, (err) => {
             const duration = performance.now() - start;
             const message = err instanceof Error ? err.message : String(err);
+            // Release budget reservation on stream error
+            if (budget)
+                budget.releaseReservation(estimatedCost);
             span.setAttributes({
                 [GEN_AI_ATTRS.STATUS]: "error",
                 [GEN_AI_ATTRS.ERROR]: message,
             });
             span.setStatus({ code: SpanStatusCode.ERROR, message });
             span.end();
-            recordRequest(providerName, req.model);
-            recordRequestDuration(duration, providerName, req.model);
-            recordError(providerName, req.model);
+            recordRequest(effectiveProvider, effectiveModel);
+            recordRequestDuration(duration, effectiveProvider, effectiveModel);
+            recordError(effectiveProvider, effectiveModel);
         }));
         // Proxy preserves the original object shape (getters, private fields, methods)
         // while intercepting only the async iterator for instrumentation
@@ -144,7 +205,7 @@ original, patch, providerName) {
         if (streamHandler && patch.isStreaming?.(body)) {
             return streamHandler(this, body, rest);
         }
-        const req = patch.extractRequest(body);
+        const req = patch.extractRequest(body, this);
         return traceLLMCall({
             provider: providerName,
             model: req.model,

package/dist/instrumentations/gemini.d.ts

@@ -1 +1 @@
-export {};
+export declare const geminiInstrumentation: import("./types.js").Instrumentation;

package/dist/instrumentations/gemini.js

@@ -1,4 +1,3 @@
-import { register } from "./registry.js";
 import { createInstrumentation } from "./create.js";
 function extractPrompt(request) {
     if (typeof request === "string")
@@ -18,10 +17,10 @@ function extractPrompt(request) {
 const generateContent = {
     getPrototype: (sdk) => sdk?.GenerativeModel?.prototype,
     method: "generateContent",
-    extractRequest(body) {
+    extractRequest(body, thisArg) {
         return {
             prompt: extractPrompt(body),
-            model: "unknown",
+            model: thisArg?.model ?? "unknown",
         };
     },
     extractResponse: (response) => {
@@ -43,10 +42,10 @@ const generateContent = {
 const generateContentStream = {
     getPrototype: (sdk) => sdk?.GenerativeModel?.prototype,
     method: "generateContentStream",
-    extractRequest(body) {
+    extractRequest(body, thisArg) {
         return {
             prompt: extractPrompt(body),
-            model: "unknown",
+            model: thisArg?.model ?? "unknown",
         };
     },
     extractResponse: () => ({
@@ -74,8 +73,8 @@ const generateContentStream = {
         }
     },
 };
-register(createInstrumentation({
+export const geminiInstrumentation = createInstrumentation({
     name: "gemini",
     moduleName: "@google/generative-ai",
     patches: [generateContent, generateContentStream],
-}));
+});

package/dist/instrumentations/openai.d.ts

@@ -1 +1 @@
-export {};
+export declare const openaiInstrumentation: import("./types.js").Instrumentation;

package/dist/instrumentations/openai.js

@@ -1,4 +1,3 @@
-import { register } from "./registry.js";
 import { createInstrumentation } from "./create.js";
 function extractMessages(messages) {
     if (!Array.isArray(messages))
@@ -79,8 +78,8 @@ const embeddings = {
         };
     },
 };
-register(createInstrumentation({
+export const openaiInstrumentation = createInstrumentation({
     name: "openai",
     moduleName: "openai",
     patches: [chatCompletions, embeddings],
-}));
+});

package/dist/instrumentations/registry.d.ts

@@ -1,5 +1,7 @@
 import type { LLMProvider } from "../types/index.js";
 import type { Instrumentation } from "./types.js";
 export declare function register(inst: Instrumentation): void;
-export declare function enableAll(providers: readonly LLMProvider[]): void;
+/** Skip lazy registration (used in tests that register mocks manually). */
+export declare function skipAutoRegister(): void;
+export declare function enableAll(providers: readonly LLMProvider[]): Promise<void>;
 export declare function disableAll(): void;

package/dist/instrumentations/registry.js

@@ -1,25 +1,48 @@
-import { diag } from "@opentelemetry/api";
 const instrumentations = new Map();
 const active = new Set();
 export function register(inst) {
     instrumentations.set(inst.name, inst);
 }
-export function enableAll(providers) {
+/**
+ * Lazy registration — loads provider modules and registers instrumentations
+ * only when enableAll() is first called. This avoids pulling in create.ts,
+ * metrics.ts, and node:module on every `import` of toad-eye.
+ */
+let registered = false;
+/** Skip lazy registration (used in tests that register mocks manually). */
+export function skipAutoRegister() {
+    registered = true;
+}
+async function ensureRegistered() {
+    if (registered)
+        return;
+    registered = true;
+    const [openai, anthropic, gemini] = await Promise.all([
+        import("./openai.js"),
+        import("./anthropic.js"),
+        import("./gemini.js"),
+    ]);
+    register(openai.openaiInstrumentation);
+    register(anthropic.anthropicInstrumentation);
+    register(gemini.geminiInstrumentation);
+}
+export async function enableAll(providers) {
+    await ensureRegistered();
+    const validProviders = Array.from(instrumentations.keys()).join(", ");
     for (const name of providers) {
         if (active.has(name))
             continue;
         const inst = instrumentations.get(name);
         if (!inst) {
-            diag.warn(`toad-eye: unknown provider "${name}", skipping`);
+            console.warn(`toad-eye: unknown provider "${name}" — valid providers: ${validProviders}`);
             continue;
         }
         const patched = inst.enable();
         if (patched) {
             active.add(name);
-            diag.debug(`toad-eye: auto-instrumented ${name}`);
         }
         else {
-            diag.debug(`toad-eye: ${name} SDK not found, skipping`);
+            console.warn(`toad-eye: "${name}" SDK not found — install it to enable auto-instrumentation: npm install ${name === "gemini" ? "@google/generative-ai" : name}`);
         }
     }
 }

package/dist/instrumentations/types.d.ts

@@ -18,8 +18,10 @@ export interface PatchTarget {
     getPrototype: (sdk: any) => any | undefined;
     /** Method name on the prototype to patch */
     method: string;
-    /** Extract LLMCallInput fields from the request arguments */
-    extractRequest: (body: unknown) => {
+    /** Extract LLMCallInput fields from the request arguments.
+     *  thisArg is the SDK object instance — use it when the model name is not in the request body
+     *  (e.g., Gemini's GenerativeModel stores it as this.model). */
+    extractRequest: (body: unknown, thisArg?: unknown) => {
         prompt: string;
         model: string;
         temperature?: number;

package/dist/types/attributes.d.ts

@@ -15,10 +15,30 @@ export declare const GEN_AI_ATTRS: {
     readonly OPERATION: "gen_ai.operation.name";
     readonly FINISH_REASONS: "gen_ai.response.finish_reasons";
     readonly ERROR: "error.type";
+    readonly AGENT_NAME: "gen_ai.agent.name";
+    readonly AGENT_ID: "gen_ai.agent.id";
+    readonly TOOL_NAME: "gen_ai.tool.name";
+    readonly TOOL_TYPE: "gen_ai.tool.type";
+    readonly TOAD_AGENT_STEP_TYPE: "gen_ai.toad_eye.agent.step.type";
+    readonly TOAD_AGENT_STEP_NUMBER: "gen_ai.toad_eye.agent.step.number";
+    readonly TOAD_AGENT_STEP_CONTENT: "gen_ai.toad_eye.agent.step.content";
+    readonly TOAD_AGENT_HANDOFF_TO: "gen_ai.toad_eye.agent.handoff.to";
+    readonly TOAD_AGENT_HANDOFF_REASON: "gen_ai.toad_eye.agent.handoff.reason";
+    readonly TOAD_AGENT_LOOP_COUNT: "gen_ai.toad_eye.agent.loop_count";
+    /** @deprecated Use TOAD_AGENT_STEP_TYPE instead. Will be removed in v3.0. */
     readonly AGENT_STEP_TYPE: "gen_ai.agent.step.type";
+    /** @deprecated Use TOAD_AGENT_STEP_NUMBER instead. Will be removed in v3.0. */
     readonly AGENT_STEP_NUMBER: "gen_ai.agent.step.number";
+    /** @deprecated Use TOOL_NAME instead. Will be removed in v3.0. */
     readonly AGENT_TOOL_NAME: "gen_ai.agent.tool.name";
+    /** @deprecated Use TOAD_AGENT_STEP_CONTENT instead. Will be removed in v3.0. */
     readonly AGENT_STEP_CONTENT: "gen_ai.agent.step.content";
+    /** @deprecated Use TOAD_AGENT_HANDOFF_TO instead. Will be removed in v3.0. */
+    readonly AGENT_HANDOFF_TO: "gen_ai.agent.handoff.to";
+    /** @deprecated Use TOAD_AGENT_HANDOFF_REASON instead. Will be removed in v3.0. */
+    readonly AGENT_HANDOFF_REASON: "gen_ai.agent.handoff.reason";
+    /** @deprecated Use TOAD_AGENT_LOOP_COUNT instead. Will be removed in v3.0. */
+    readonly AGENT_LOOP_COUNT: "gen_ai.agent.loop_count";
     readonly GUARD_MODE: "gen_ai.toad_eye.guard.mode";
     readonly GUARD_PASSED: "gen_ai.toad_eye.guard.passed";
     readonly GUARD_FAILURE_REASON: "gen_ai.toad_eye.guard.failure_reason";

package/dist/types/attributes.js

@@ -16,11 +16,33 @@ export const GEN_AI_ATTRS = {
     OPERATION: "gen_ai.operation.name",
     FINISH_REASONS: "gen_ai.response.finish_reasons",
     ERROR: "error.type",
-    // Agent step attributes
+    // OTel GenAI agent attributes
+    AGENT_NAME: "gen_ai.agent.name",
+    AGENT_ID: "gen_ai.agent.id",
+    TOOL_NAME: "gen_ai.tool.name",
+    TOOL_TYPE: "gen_ai.tool.type",
+    // toad-eye ReAct extensions (gen_ai.toad_eye.agent.* — correct namespace)
+    TOAD_AGENT_STEP_TYPE: "gen_ai.toad_eye.agent.step.type",
+    TOAD_AGENT_STEP_NUMBER: "gen_ai.toad_eye.agent.step.number",
+    TOAD_AGENT_STEP_CONTENT: "gen_ai.toad_eye.agent.step.content",
+    TOAD_AGENT_HANDOFF_TO: "gen_ai.toad_eye.agent.handoff.to",
+    TOAD_AGENT_HANDOFF_REASON: "gen_ai.toad_eye.agent.handoff.reason",
+    TOAD_AGENT_LOOP_COUNT: "gen_ai.toad_eye.agent.loop_count",
+    // Agent step attributes — @deprecated aliases (will be removed in v3.0)
+    /** @deprecated Use TOAD_AGENT_STEP_TYPE instead. Will be removed in v3.0. */
     AGENT_STEP_TYPE: "gen_ai.agent.step.type",
+    /** @deprecated Use TOAD_AGENT_STEP_NUMBER instead. Will be removed in v3.0. */
     AGENT_STEP_NUMBER: "gen_ai.agent.step.number",
+    /** @deprecated Use TOOL_NAME instead. Will be removed in v3.0. */
     AGENT_TOOL_NAME: "gen_ai.agent.tool.name",
+    /** @deprecated Use TOAD_AGENT_STEP_CONTENT instead. Will be removed in v3.0. */
     AGENT_STEP_CONTENT: "gen_ai.agent.step.content",
+    /** @deprecated Use TOAD_AGENT_HANDOFF_TO instead. Will be removed in v3.0. */
+    AGENT_HANDOFF_TO: "gen_ai.agent.handoff.to",
+    /** @deprecated Use TOAD_AGENT_HANDOFF_REASON instead. Will be removed in v3.0. */
+    AGENT_HANDOFF_REASON: "gen_ai.agent.handoff.reason",
+    /** @deprecated Use TOAD_AGENT_LOOP_COUNT instead. Will be removed in v3.0. */
+    AGENT_LOOP_COUNT: "gen_ai.agent.loop_count",
     // Guard (shadow mode) attributes
     GUARD_MODE: "gen_ai.toad_eye.guard.mode",
     GUARD_PASSED: "gen_ai.toad_eye.guard.passed",

package/dist/types/config.d.ts

@@ -1,5 +1,19 @@
-import type { LLMProvider } from "./providers.js";
+import type { InstrumentTarget } from "./providers.js";
 import type { BudgetConfig, BudgetExceededMode, DowngradeCallback } from "../budget/types.js";
+/** Sampling configuration. Tail sampling runs in OTel Collector, SDK sends all spans. */
+export interface SamplingConfig {
+    /** SDK-side sampling rate (0.0–1.0). Default: 1.0 (send everything to Collector). */
+    readonly sdkRate?: number | undefined;
+    /** Collector-side tail sampling settings (used when generating otel-collector.yml). */
+    readonly collector?: {
+        /** Keep 100% of error traces. Default: true */
+        readonly keepErrors?: boolean | undefined;
+        /** Keep 100% of traces slower than this (ms). Default: 2000 */
+        readonly highLatencyMs?: number | undefined;
+        /** Sample this % of healthy traffic (0–100). Default: 10 */
+        readonly healthyRate?: number | undefined;
+    } | undefined;
+}
 /**
  * Configuration for initObservability().
  * This is what the user passes when connecting toad-eye to their service.
@@ -20,7 +34,13 @@ export interface ToadEyeConfig {
     readonly salt?: string | undefined;
     /** Regex patterns to redact from prompt/completion text before recording. */
     readonly redactPatterns?: readonly RegExp[] | undefined;
-    readonly instrument?: readonly LLMProvider[] | undefined;
+    /** Enable built-in redaction patterns for common PII: email, SSN, credit card, phone. */
+    readonly redactDefaults?: boolean | undefined;
+    /** Log what was masked to console (for debugging redaction config). No data is sent externally. */
+    readonly auditMasking?: boolean | undefined;
+    /** Configure trace sampling. Tail sampling happens in OTel Collector, not SDK. */
+    readonly sampling?: SamplingConfig | undefined;
+    readonly instrument?: readonly InstrumentTarget[] | undefined;
     /** Budget limits — daily, per-user, per-model spend caps in USD. */
     readonly budgets?: BudgetConfig | undefined;
     /** What to do when budget is exceeded: 'warn' (log), 'block' (throw), 'downgrade' (callback). */

package/dist/types/index.d.ts

@@ -9,9 +9,9 @@
  * - spans.ts      — span-related types (LLMSpanAttributes, SpanStatus)
  */
 export declare const INSTRUMENTATION_NAME = "toad-eye";
-export type { LLMProvider } from "./providers.js";
-export type { ToadEyeConfig } from "./config.js";
+export type { LLMProvider, InstrumentTarget } from "./providers.js";
+export type { ToadEyeConfig, SamplingConfig } from "./config.js";
 export { GEN_AI_ATTRS, LLM_ATTRS } from "./attributes.js";
 export { GEN_AI_METRICS, LLM_METRICS } from "./metrics.js";
 export type { MetricName } from "./metrics.js";
-export type { SpanStatus, LLMSpanAttributes, AgentStepType, AgentStepInput, GuardMode, GuardResult, } from "./spans.js";
+export type { SpanStatus, LLMSpanAttributes, AgentStepType, AgentStepInput, AgentQueryOptions, AgentQueryInput, GuardMode, GuardResult, } from "./spans.js";

package/dist/types/metrics.d.ts

@@ -21,6 +21,8 @@ export declare const GEN_AI_METRICS: {
     readonly BUDGET_EXCEEDED: "gen_ai.toad_eye.budget.exceeded";
     readonly BUDGET_BLOCKED: "gen_ai.toad_eye.budget.blocked";
     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";
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export declare const LLM_METRICS: {

package/dist/types/metrics.js

@@ -26,6 +26,9 @@ export const GEN_AI_METRICS = {
     BUDGET_EXCEEDED: "gen_ai.toad_eye.budget.exceeded",
     BUDGET_BLOCKED: "gen_ai.toad_eye.budget.blocked",
     BUDGET_DOWNGRADED: "gen_ai.toad_eye.budget.downgraded",
+    // Response quality proxy metrics
+    RESPONSE_EMPTY: "gen_ai.toad_eye.response.empty",
+    RESPONSE_LATENCY_PER_TOKEN: "gen_ai.toad_eye.response.latency_per_token",
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export const LLM_METRICS = {

package/dist/types/providers.d.ts

@@ -2,4 +2,9 @@
  * LLM providers supported by toad-eye.
  * Values follow OTel GenAI semconv `gen_ai.provider.name`.
  */
-export type LLMProvider = "anthropic" | "gemini" | "openai";
+export type LLMProvider = "anthropic" | "gemini" | "openai" | (string & {});
+/**
+ * All instrumentable targets — includes LLM providers + framework SDKs.
+ * 'ai' = Vercel AI SDK (uses SpanProcessor, not monkey-patching).
+ */
+export type InstrumentTarget = LLMProvider | "ai";

package/dist/types/spans.d.ts

@@ -1,14 +1,33 @@
 import type { LLMProvider } from "./providers.js";
 /** Span status values used in trace attributes. */
 export type SpanStatus = "success" | "error";
-/** ReAct agent step types: think → act → observe → answer */
-export type AgentStepType = "think" | "act" | "observe" | "answer";
+/** ReAct agent step types: think → act → observe → answer → handoff */
+export type AgentStepType = "think" | "act" | "observe" | "answer" | "handoff";
 /** Input for traceAgentStep — describes a single agent step */
 export interface AgentStepInput {
     readonly type: AgentStepType;
     readonly stepNumber: number;
     readonly content?: string | undefined;
     readonly toolName?: string | undefined;
+    /** Tool type per OTel GenAI spec: function, extension, retrieval, builtin */
+    readonly toolType?: "function" | "extension" | "retrieval" | "builtin" | undefined;
+    /** Target agent name for handoff steps */
+    readonly toAgent?: string | undefined;
+    /** Reason for handoff */
+    readonly handoffReason?: string | undefined;
+}
+/** Options for traceAgentQuery */
+export interface AgentQueryOptions {
+    /** Max steps before recording a warning. Default: 25 */
+    readonly maxSteps?: number | undefined;
+}
+/** Input for traceAgentQuery — object form with agent metadata */
+export interface AgentQueryInput {
+    readonly query: string;
+    /** Agent name — maps to gen_ai.agent.name and span name invoke_agent {agentName} */
+    readonly agentName?: string | undefined;
+    /** Agent identifier — maps to gen_ai.agent.id */
+    readonly agentId?: string | undefined;
 }
 /** Guard execution mode */
 export type GuardMode = "shadow" | "enforce";

package/dist/vercel.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Vercel AI SDK integration — enriches AI SDK OTel spans with toad-eye
+ * cost tracking and metrics. No monkey-patching needed.
+ *
+ * The Vercel AI SDK already emits OTel spans when `experimental_telemetry`
+ * is enabled. This module adds a SpanProcessor that intercepts those spans
+ * and calculates cost from token usage.
+ *
+ * Usage:
+ * ```ts
+ * import { initObservability } from 'toad-eye';
+ * import { withToadEye } from 'toad-eye/vercel';
+ *
+ * initObservability({ serviceName: 'my-app' });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Hello',
+ *   experimental_telemetry: withToadEye(),
+ * });
+ * ```
+ */
+import type { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+/**
+ * OTel SpanProcessor that enriches Vercel AI SDK spans with toad-eye
+ * cost attributes and records metrics.
+ */
+export declare class ToadEyeAISpanProcessor implements SpanProcessor {
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    onStart(): void;
+    onEnd(span: ReadableSpan): void;
+}
+/**
+ * Helper for `experimental_telemetry` option — enables telemetry with
+ * optional toad-eye metadata.
+ *
+ * ```ts
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Hello',
+ *   experimental_telemetry: withToadEye({ functionId: 'my-feature' }),
+ * });
+ * ```
+ */
+export declare function withToadEye(options?: {
+    functionId?: string;
+    metadata?: Record<string, string>;
+}): {
+    functionId?: string;
+    metadata?: Record<string, string>;
+    isEnabled: true;
+};