toad-eye 2.1.1 → 2.3.0

package/dist/instrumentations/create.js

@@ -1,8 +1,10 @@
 import { createRequire } from "node:module";
-import { trace, diag, SpanStatusCode } from "@opentelemetry/api";
-import { traceLLMCall } from "../core/spans.js";
+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, } 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) {
@@ -21,95 +23,189 @@ function loadModule(moduleName) {
     return sdk.default ?? sdk;
 }
 /**
- * Wrap an async iterable stream to intercept chunks.
- * Yields every chunk transparently to the caller while collecting them.
- * On stream end, calls onComplete with all accumulated chunks.
+ * Wrap an async iterable stream with an accumulator.
+ * Yields every chunk transparently. Accumulates only extracted data (no raw chunks stored).
+ * On stream end, calls onComplete with the accumulated result.
+ * onFirstChunk is called once when the first chunk arrives (for TTFT tracking).
  */
-async function* wrapAsyncIterable(stream, onChunk, onComplete, onError) {
-    const chunks = [];
+async function* wrapAsyncIterable(stream, accumulate, onFirstChunk, onComplete, onError) {
+    const acc = {
+        completion: "",
+        inputTokens: 0,
+        outputTokens: 0,
+    };
+    let firstChunk = true;
+    let completed = false;
+    let errored = false;
     try {
         for await (const chunk of stream) {
-            chunks.push(chunk);
-            onChunk(chunk);
+            if (firstChunk) {
+                onFirstChunk();
+                firstChunk = false;
+            }
+            accumulate(acc, chunk);
             yield chunk;
         }
-        onComplete(chunks);
+        completed = true;
+        onComplete(acc);
     }
     catch (err) {
+        errored = true;
         onError(err);
         throw err;
     }
+    finally {
+        // If stream was abandoned (consumer broke out), still record what we have
+        if (!completed && !errored) {
+            onComplete(acc);
+        }
+    }
 }
 function createStreamingHandler(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 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);
-        // The response should be an async iterable (Stream, MessageStream, etc.)
-        // We wrap it to intercept chunks
-        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(`gen_ai.${effectiveProvider}.${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 }),
         });
-        const wrapped = wrapAsyncIterable(response, () => { }, (chunks) => {
+        let response;
+        try {
+            response = await original.call(thisArg, body, ...rest);
+        }
+        catch (err) {
             const duration = performance.now() - start;
-            const res = patch.extractStreamResponse(chunks);
-            const cost = calculateCost(req.model, res.inputTokens, res.outputTokens);
+            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.RESPONSE_MODEL]: req.model,
-                [GEN_AI_ATTRS.INPUT_TOKENS]: res.inputTokens,
-                [GEN_AI_ATTRS.OUTPUT_TOKENS]: res.outputTokens,
+                [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 &&
+            typeof resp === "object" &&
+            "stream" in resp &&
+            resp["stream"] != null &&
+            typeof resp["stream"] === "object" &&
+            Symbol.asyncIterator in resp["stream"];
+        const streamIterable = hasStreamProp
+            ? resp["stream"]
+            : response;
+        const wrapped = context.bind(ctx, wrapAsyncIterable(streamIterable, (acc, chunk) => patch.accumulateChunk(acc, chunk), () => {
+            recordTimeToFirstToken(performance.now() - start, effectiveProvider, effectiveModel);
+        }, (acc) => {
+            const duration = performance.now() - start;
+            const cost = calculateCost(effectiveModel, acc.inputTokens, acc.outputTokens);
+            const processedCompletion = processContent(acc.completion);
+            span.setAttributes({
+                ...(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,
                 [GEN_AI_ATTRS.STATUS]: "success",
+                [GEN_AI_ATTRS.FINISH_REASONS]: ["stop"],
             });
             span.setStatus({ code: SpanStatusCode.OK });
             span.end();
-            recordRequest(providerName, req.model);
-            recordRequestDuration(duration, providerName, req.model);
-            recordRequestCost(cost, providerName, req.model);
-            recordTokens(res.inputTokens + res.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
+        return new Proxy(response, {
+            get(target, prop, receiver) {
+                if (prop === Symbol.asyncIterator) {
+                    return () => wrapped[Symbol.asyncIterator]();
+                }
+                return Reflect.get(target, prop, receiver);
+            },
         });
-        // Return an object that looks like the original stream but with our wrapper
-        // Preserve the original object shape — SDKs may have extra methods/properties
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const proxy = Object.create(response);
-        proxy[Symbol.asyncIterator] = () => wrapped[Symbol.asyncIterator]();
-        return proxy;
     };
 }
 function createPatchedMethod(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 original, patch, providerName) {
-    const streamHandler = patch.isStreaming && patch.extractStreamResponse
+    const streamHandler = patch.isStreaming && patch.accumulateChunk
         ? createStreamingHandler(original, patch, providerName)
         : null;
     return function patchedMethod(body, ...rest) {
         if (patch.shouldSkip?.(body)) {
             return original.call(this, body, ...rest);
         }
-        // Handle streaming calls
         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,
@@ -127,10 +223,6 @@ original, patch, providerName) {
         });
     };
 }
-/**
- * Factory for creating SDK instrumentations.
- * Eliminates boilerplate: SDK resolution, prototype patching, error handling, cleanup.
- */
 export function createInstrumentation(config) {
     const activePatches = [];
     return {

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,11 +17,10 @@ function extractPrompt(request) {
 const generateContent = {
     getPrototype: (sdk) => sdk?.GenerativeModel?.prototype,
     method: "generateContent",
-    extractRequest(body) {
+    extractRequest(body, thisArg) {
         return {
             prompt: extractPrompt(body),
-            // model comes from `this.model` — injected by create.ts via the patched function's `this`
-            model: "unknown",
+            model: thisArg?.model ?? "unknown",
         };
     },
     extractResponse: (response) => {
@@ -41,8 +39,42 @@ const generateContent = {
         };
     },
 };
-register(createInstrumentation({
+const generateContentStream = {
+    getPrototype: (sdk) => sdk?.GenerativeModel?.prototype,
+    method: "generateContentStream",
+    extractRequest(body, thisArg) {
+        return {
+            prompt: extractPrompt(body),
+            model: thisArg?.model ?? "unknown",
+        };
+    },
+    extractResponse: () => ({
+        completion: "",
+        inputTokens: 0,
+        outputTokens: 0,
+    }),
+    // generateContentStream always returns a stream
+    isStreaming: () => true,
+    accumulateChunk: (acc, chunk) => {
+        // Gemini stream chunks are GenerateContentResponse objects
+        const c = chunk;
+        try {
+            const text = c?.text?.();
+            if (text)
+                acc.completion += text;
+        }
+        catch {
+            // text() may throw if content is blocked
+        }
+        if (c?.usageMetadata) {
+            acc.inputTokens = c.usageMetadata.promptTokenCount ?? acc.inputTokens;
+            acc.outputTokens =
+                c.usageMetadata.candidatesTokenCount ?? acc.outputTokens;
+        }
+    },
+};
+export const geminiInstrumentation = createInstrumentation({
     name: "gemini",
     moduleName: "@google/generative-ai",
-    patches: [generateContent],
-}));
+    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))
@@ -46,23 +45,15 @@ const chatCompletions = {
         };
     },
     isStreaming: (body) => !!body?.stream,
-    extractStreamResponse: (chunks) => {
-        // OpenAI stream chunks: { choices: [{ delta: { content } }], usage?: { ... } }
-        let completion = "";
-        let inputTokens = 0;
-        let outputTokens = 0;
-        for (const chunk of chunks) {
-            const c = chunk;
-            const delta = c?.choices?.[0]?.delta?.content;
-            if (delta)
-                completion += delta;
-            // Usage is typically in the final chunk (when stream_options.include_usage is set)
-            if (c?.usage) {
-                inputTokens = c.usage.prompt_tokens ?? inputTokens;
-                outputTokens = c.usage.completion_tokens ?? outputTokens;
-            }
+    accumulateChunk: (acc, chunk) => {
+        const c = chunk;
+        const delta = c?.choices?.[0]?.delta?.content;
+        if (delta)
+            acc.completion += delta;
+        if (c?.usage) {
+            acc.inputTokens = c.usage.prompt_tokens ?? acc.inputTokens;
+            acc.outputTokens = c.usage.completion_tokens ?? acc.outputTokens;
         }
-        return { completion, inputTokens, outputTokens };
     },
 };
 const embeddings = {
@@ -87,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

@@ -6,14 +6,22 @@ export interface Instrumentation {
     /** Restore original methods. */
     disable(): void;
 }
+/** Accumulated stream data — only primitives, no raw SDK objects. */
+export interface StreamAccumulator {
+    completion: string;
+    inputTokens: number;
+    outputTokens: number;
+}
 /** Describes a single method to monkey-patch on an SDK prototype. */
 export interface PatchTarget {
     /** How to find the prototype from the loaded SDK module */
     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;
@@ -28,10 +36,6 @@ export interface PatchTarget {
     shouldSkip?: (body: unknown) => boolean;
     /** Return true if this call is a streaming request */
     isStreaming?: (body: unknown) => boolean;
-    /** Extract final stats from accumulated stream chunks. Required when isStreaming is set. */
-    extractStreamResponse?: (chunks: unknown[]) => {
-        completion: string;
-        inputTokens: number;
-        outputTokens: number;
-    };
+    /** Process one stream chunk — extract only the data we need into the accumulator. */
+    accumulateChunk?: (acc: StreamAccumulator, chunk: unknown) => void;
 }

package/dist/types/attributes.d.ts

@@ -19,6 +19,9 @@ export declare const GEN_AI_ATTRS: {
     readonly AGENT_STEP_NUMBER: "gen_ai.agent.step.number";
     readonly AGENT_TOOL_NAME: "gen_ai.agent.tool.name";
     readonly AGENT_STEP_CONTENT: "gen_ai.agent.step.content";
+    readonly AGENT_HANDOFF_TO: "gen_ai.agent.handoff.to";
+    readonly AGENT_HANDOFF_REASON: "gen_ai.agent.handoff.reason";
+    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

@@ -21,6 +21,9 @@ export const GEN_AI_ATTRS = {
     AGENT_STEP_NUMBER: "gen_ai.agent.step.number",
     AGENT_TOOL_NAME: "gen_ai.agent.tool.name",
     AGENT_STEP_CONTENT: "gen_ai.agent.step.content",
+    AGENT_HANDOFF_TO: "gen_ai.agent.handoff.to",
+    AGENT_HANDOFF_REASON: "gen_ai.agent.handoff.reason",
+    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, GuardMode, GuardResult, } from "./spans.js";

package/dist/types/metrics.d.ts

@@ -17,9 +17,12 @@ export declare const GEN_AI_METRICS: {
     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";
+    readonly TIME_TO_FIRST_TOKEN: "gen_ai.client.time_to_first_token";
     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

@@ -20,10 +20,15 @@ export const GEN_AI_METRICS = {
     GUARD_WOULD_BLOCK: "gen_ai.toad_eye.guard.would_block",
     // Drift metrics
     SEMANTIC_DRIFT: "gen_ai.toad_eye.semantic_drift",
+    // Streaming metrics
+    TIME_TO_FIRST_TOKEN: "gen_ai.client.time_to_first_token",
     // Budget 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,23 @@
 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;
+    /** 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;
 }
 /** Guard execution mode */
 export type GuardMode = "shadow" | "enforce";