toad-eye 2.0.0 → 2.1.1

package/dist/instrumentations/create.js

@@ -1,8 +1,132 @@
 import { createRequire } from "node:module";
-import { diag } from "@opentelemetry/api";
-import { traceLLMCall } from "../spans.js";
-import { calculateCost } from "../pricing.js";
+import { trace, diag, SpanStatusCode } from "@opentelemetry/api";
+import { traceLLMCall } from "../core/spans.js";
+import { calculateCost } from "../core/pricing.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, } from "../core/metrics.js";
+import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
 const require = createRequire(import.meta.url);
+function isModuleInstalled(moduleName) {
+    try {
+        require.resolve(moduleName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function loadModule(moduleName) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const sdk = require(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.
+ */
+async function* wrapAsyncIterable(stream, onChunk, onComplete, onError) {
+    const chunks = [];
+    try {
+        for await (const chunk of stream) {
+            chunks.push(chunk);
+            onChunk(chunk);
+            yield chunk;
+        }
+        onComplete(chunks);
+    }
+    catch (err) {
+        onError(err);
+        throw err;
+    }
+}
+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);
+        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}`);
+        span.setAttributes({
+            [GEN_AI_ATTRS.PROVIDER]: providerName,
+            [GEN_AI_ATTRS.REQUEST_MODEL]: req.model,
+            [GEN_AI_ATTRS.TEMPERATURE]: req.temperature ?? 1.0,
+            [GEN_AI_ATTRS.OPERATION]: "chat",
+        });
+        const wrapped = wrapAsyncIterable(response, () => { }, (chunks) => {
+            const duration = performance.now() - start;
+            const res = patch.extractStreamResponse(chunks);
+            const cost = calculateCost(req.model, res.inputTokens, res.outputTokens);
+            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.COST]: cost,
+                [GEN_AI_ATTRS.STATUS]: "success",
+            });
+            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);
+        }, (err) => {
+            const duration = performance.now() - start;
+            const message = err instanceof Error ? err.message : String(err);
+            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);
+        });
+        // 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
+        ? 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);
+        return traceLLMCall({
+            provider: providerName,
+            model: req.model,
+            prompt: req.prompt,
+            temperature: req.temperature,
+        }, async () => {
+            const response = await original.call(this, body, ...rest);
+            const res = patch.extractResponse(response, req.model);
+            return {
+                completion: res.completion,
+                inputTokens: res.inputTokens,
+                outputTokens: res.outputTokens,
+                cost: calculateCost(req.model, res.inputTokens, res.outputTokens),
+            };
+        });
+    };
+}
 /**
  * Factory for creating SDK instrumentations.
  * Eliminates boilerplate: SDK resolution, prototype patching, error handling, cleanup.
@@ -12,42 +136,16 @@ export function createInstrumentation(config) {
     return {
         name: config.name,
         enable() {
-            try {
-                require.resolve(config.moduleName);
-            }
-            catch {
+            if (!isModuleInstalled(config.moduleName))
                 return false;
-            }
             try {
-                // eslint-disable-next-line @typescript-eslint/no-require-imports
-                const sdk = require(config.moduleName);
-                const mod = sdk.default ?? sdk;
+                const mod = loadModule(config.moduleName);
                 for (const patch of config.patches) {
                     const proto = patch.getPrototype(mod);
                     if (!proto?.[patch.method])
                         continue;
                     const original = proto[patch.method];
-                    proto[patch.method] = function patchedMethod(body, ...rest) {
-                        if (patch.shouldSkip?.(body)) {
-                            return original.call(this, body, ...rest);
-                        }
-                        const req = patch.extractRequest(body);
-                        return traceLLMCall({
-                            provider: config.name,
-                            model: req.model,
-                            prompt: req.prompt,
-                            temperature: req.temperature,
-                        }, async () => {
-                            const response = await original.call(this, body, ...rest);
-                            const res = patch.extractResponse(response, req.model);
-                            return {
-                                completion: res.completion,
-                                inputTokens: res.inputTokens,
-                                outputTokens: res.outputTokens,
-                                cost: calculateCost(req.model, res.inputTokens, res.outputTokens),
-                            };
-                        });
-                    };
+                    proto[patch.method] = createPatchedMethod(original, patch, config.name);
                     activePatches.push({ proto, method: patch.method, original });
                 }
                 return activePatches.length > 0;

package/dist/instrumentations/openai.js

@@ -4,14 +4,31 @@ function extractMessages(messages) {
     if (!Array.isArray(messages))
         return "";
     return messages
-        .map((m) => typeof m.content === "string" ? m.content : "")
+        .map((m) => {
+        if (typeof m.content === "string")
+            return m.content;
+        if (Array.isArray(m.content)) {
+            return m.content
+                .map((part) => {
+                if (part.type === "text")
+                    return part.text ?? "";
+                if (part.type === "image_url")
+                    return "[image]";
+                if (part.type === "input_audio")
+                    return "[audio]";
+                return "";
+            })
+                .filter(Boolean)
+                .join("");
+        }
+        return "";
+    })
         .filter(Boolean)
         .join("\n");
 }
 const chatCompletions = {
     getPrototype: (sdk) => (sdk?.Chat?.Completions ?? sdk?.Completions)?.prototype,
     method: "create",
-    shouldSkip: (body) => !!body?.stream,
     extractRequest: (body) => {
         const b = body;
         return {
@@ -28,6 +45,25 @@ const chatCompletions = {
             outputTokens: r?.usage?.completion_tokens ?? 0,
         };
     },
+    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;
+            }
+        }
+        return { completion, inputTokens, outputTokens };
+    },
 };
 const embeddings = {
     getPrototype: (sdk) => sdk?.Embeddings?.prototype,

package/dist/instrumentations/types.d.ts

@@ -24,6 +24,14 @@ export interface PatchTarget {
         inputTokens: number;
         outputTokens: number;
     };
-    /** Return true if this call should skip patching (e.g. streaming) */
+    /** Return true if this call should skip patching entirely */
     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;
+    };
 }

package/dist/types/attributes.d.ts

@@ -15,11 +15,23 @@ 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_STEP_TYPE: "gen_ai.agent.step.type";
+    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 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";
+    readonly GUARD_RULE_NAME: "gen_ai.toad_eye.guard.rule_name";
     readonly PROMPT: "gen_ai.toad_eye.prompt";
     readonly COMPLETION: "gen_ai.toad_eye.completion";
     readonly COST: "gen_ai.toad_eye.cost";
     readonly STATUS: "gen_ai.toad_eye.status";
     readonly SESSION_ID: "session.id";
+    readonly TEAM: "toad_eye.team";
+    readonly USER_ID: "toad_eye.user_id";
+    readonly FEATURE: "toad_eye.feature";
+    readonly ENVIRONMENT: "toad_eye.environment";
 };
 /** @deprecated Use GEN_AI_ATTRS instead. Kept for backward compatibility. */
 export declare const LLM_ATTRS: {

package/dist/types/attributes.js

@@ -16,12 +16,27 @@ export const GEN_AI_ATTRS = {
     OPERATION: "gen_ai.operation.name",
     FINISH_REASONS: "gen_ai.response.finish_reasons",
     ERROR: "error.type",
+    // Agent step attributes
+    AGENT_STEP_TYPE: "gen_ai.agent.step.type",
+    AGENT_STEP_NUMBER: "gen_ai.agent.step.number",
+    AGENT_TOOL_NAME: "gen_ai.agent.tool.name",
+    AGENT_STEP_CONTENT: "gen_ai.agent.step.content",
+    // Guard (shadow mode) attributes
+    GUARD_MODE: "gen_ai.toad_eye.guard.mode",
+    GUARD_PASSED: "gen_ai.toad_eye.guard.passed",
+    GUARD_FAILURE_REASON: "gen_ai.toad_eye.guard.failure_reason",
+    GUARD_RULE_NAME: "gen_ai.toad_eye.guard.rule_name",
     // toad-eye extensions
     PROMPT: "gen_ai.toad_eye.prompt",
     COMPLETION: "gen_ai.toad_eye.completion",
     COST: "gen_ai.toad_eye.cost",
     STATUS: "gen_ai.toad_eye.status",
     SESSION_ID: "session.id",
+    // FinOps attribution
+    TEAM: "toad_eye.team",
+    USER_ID: "toad_eye.user_id",
+    FEATURE: "toad_eye.feature",
+    ENVIRONMENT: "toad_eye.environment",
 };
 /** @deprecated Use GEN_AI_ATTRS instead. Kept for backward compatibility. */
 export const LLM_ATTRS = {

package/dist/types/config.d.ts

@@ -1,4 +1,5 @@
 import type { LLMProvider } from "./providers.js";
+import type { BudgetConfig, BudgetExceededMode, DowngradeCallback } from "../budget/types.js";
 /**
  * Configuration for initObservability().
  * This is what the user passes when connecting toad-eye to their service.
@@ -6,13 +7,26 @@ import type { LLMProvider } from "./providers.js";
 export interface ToadEyeConfig {
     readonly serviceName: string;
     readonly endpoint?: string | undefined;
+    /** API key for toad-eye cloud. When set, transport switches to HTTPS cloud endpoint automatically. */
+    readonly apiKey?: string | undefined;
+    /** Custom cloud endpoint override. Defaults to https://cloud.toad-eye.dev. */
+    readonly cloudEndpoint?: string | undefined;
+    readonly attributes?: Readonly<Record<string, string>> | undefined;
     /** Set to false to disable recording prompt/completion text in spans. */
     readonly recordContent?: boolean | undefined;
     /** Record SHA-256 hash of content instead of plain text. Allows prompt comparison without reading. */
     readonly hashContent?: boolean | undefined;
+    /** Salt for hashContent — prepended before hashing to prevent rainbow table attacks on short strings. */
+    readonly salt?: string | undefined;
     /** Regex patterns to redact from prompt/completion text before recording. */
     readonly redactPatterns?: readonly RegExp[] | undefined;
     readonly instrument?: readonly LLMProvider[] | 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). */
+    readonly onBudgetExceeded?: BudgetExceededMode | undefined;
+    /** Callback for 'downgrade' mode — receives original provider/model, returns replacement. */
+    readonly downgradeCallback?: DowngradeCallback | 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/index.d.ts

@@ -14,4 +14,4 @@ export type { ToadEyeConfig } 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 } from "./spans.js";
+export type { SpanStatus, LLMSpanAttributes, AgentStepType, AgentStepInput, GuardMode, GuardResult, } from "./spans.js";

package/dist/types/metrics.d.ts

@@ -12,6 +12,14 @@ export declare const GEN_AI_METRICS: {
     readonly REQUEST_COST: "gen_ai.client.request.cost";
     readonly REQUESTS: "gen_ai.client.requests";
     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 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 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";
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export declare const LLM_METRICS: {

package/dist/types/metrics.js

@@ -12,6 +12,18 @@ export const GEN_AI_METRICS = {
     REQUEST_COST: "gen_ai.client.request.cost",
     REQUESTS: "gen_ai.client.requests",
     ERRORS: "gen_ai.client.errors",
+    // Agent metrics
+    AGENT_STEPS_PER_QUERY: "gen_ai.agent.steps_per_query",
+    AGENT_TOOL_USAGE: "gen_ai.agent.tool_usage",
+    // Guard metrics
+    GUARD_EVALUATIONS: "gen_ai.toad_eye.guard.evaluations",
+    GUARD_WOULD_BLOCK: "gen_ai.toad_eye.guard.would_block",
+    // Drift metrics
+    SEMANTIC_DRIFT: "gen_ai.toad_eye.semantic_drift",
+    // 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",
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export const LLM_METRICS = {

package/dist/types/spans.d.ts

@@ -1,6 +1,27 @@
 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";
+/** 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;
+}
+/** Guard execution mode */
+export type GuardMode = "shadow" | "enforce";
+/**
+ * Result of a toad-guard validation — the contract between toad-guard and toad-eye.
+ * toad-guard produces this, toad-eye consumes it via recordGuardResult().
+ */
+export interface GuardResult {
+    readonly mode: GuardMode;
+    readonly passed: boolean;
+    readonly ruleName: string;
+    readonly failureReason?: string | undefined;
+}
 /**
  * Attributes attached to every LLM span (trace).
  * These become searchable fields in Jaeger and filterable dimensions in Grafana.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "toad-eye",
-  "version": "2.0.0",
-  "description": "Auto-instrumentation, cost tracking, and observability for LLM services",
+  "version": "2.1.1",
+  "description": "Auto-instrumentation, cost tracking, budget guards, and observability for LLM services",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,6 +15,8 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -36,7 +38,10 @@
     "gemini",
     "cost-tracking",
     "auto-instrumentation",
-    "gen-ai"
+    "gen-ai",
+    "budget-guards",
+    "finops",
+    "streaming"
   ],
   "license": "ISC",
   "dependencies": {
@@ -47,10 +52,28 @@
     "@opentelemetry/sdk-metrics": "^2.6.0",
     "@opentelemetry/sdk-node": "^0.213.0",
     "@opentelemetry/semantic-conventions": "^1.40.0",
-    "nodemailer": "^6.9.0",
+    "nodemailer": "^8.0.3",
     "yaml": "^2.7.0"
   },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.30.0",
+    "@google/generative-ai": ">=0.20.0",
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@google/generative-ai": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@types/nodemailer": "^7.0.11"
+    "@types/nodemailer": "^7.0.11",
+    "playwright": "^1.58.2",
+    "vitest": "^4.1.0"
   }
 }