@voltagent/core 2.6.11 → 2.6.12

package/dist/index.js

@@ -287,7 +287,7 @@ __export(index_exports, {
   context: () => import_api9.context,
   convertUsage: () => convertUsage,
   cosineSimilarity: () => cosineSimilarity,
-  createAsyncIterableStream: () => import_utils40.createAsyncIterableStream,
+  createAsyncIterableStream: () => import_utils41.createAsyncIterableStream,
   createDefaultInputSafetyGuardrails: () => createDefaultInputSafetyGuardrails,
   createDefaultPIIGuardrails: () => createDefaultPIIGuardrails,
   createDefaultSafetyGuardrails: () => createDefaultSafetyGuardrails,
@@ -12693,7 +12693,7 @@ __name(createWorkflowChain, "createWorkflowChain");
 // src/agent/agent.ts
 var import_node_util = require("util");
 var import_api16 = require("@opentelemetry/api");
-var import_utils33 = require("@voltagent/internal/utils");
+var import_utils34 = require("@voltagent/internal/utils");
 var import_ai7 = require("ai");
 var import_zod7 = require("zod");
 
@@ -26521,6 +26521,172 @@ function addModelAttributesToSpan(span, modelName, options, defaultMaxOutputToke
 }
 __name(addModelAttributesToSpan, "addModelAttributesToSpan");
 
+// src/agent/prompt-context-usage.ts
+var import_utils29 = require("@voltagent/internal/utils");
+var ESTIMATED_CHARS_PER_TOKEN = 4;
+var BINARY_PART_TYPES = /* @__PURE__ */ new Set([
+  "audio",
+  "file",
+  "image",
+  "input_audio",
+  "input_image",
+  "media"
+]);
+var LARGE_BINARY_KEYS = /* @__PURE__ */ new Set(["audio", "base64", "bytes", "data", "image"]);
+function estimatePromptContextUsage(params) {
+  let systemTokensEstimated = 0;
+  let messageTokensEstimated = 0;
+  let nonSystemMessageTokensEstimated = 0;
+  let systemMessageCount = 0;
+  for (const message of params.messages ?? []) {
+    const serializedMessage = serializePromptMessage(message);
+    if (!serializedMessage) {
+      continue;
+    }
+    const estimatedTokens = estimateTokensFromText(serializedMessage);
+    messageTokensEstimated += estimatedTokens;
+    if (message.role === "system") {
+      systemTokensEstimated += estimatedTokens;
+      systemMessageCount += 1;
+      continue;
+    }
+    nonSystemMessageTokensEstimated += estimatedTokens;
+  }
+  const serializedTools = Object.entries(params.tools ?? {}).map(
+    ([name, tool2]) => serializeToolDefinition(name, tool2)
+  );
+  const toolTokensEstimated = serializedTools.length > 0 ? estimateTokensFromText((0, import_utils29.safeStringify)(serializedTools)) : 0;
+  const totalTokensEstimated = messageTokensEstimated + toolTokensEstimated;
+  if (totalTokensEstimated === 0) {
+    return void 0;
+  }
+  return {
+    systemTokensEstimated,
+    messageTokensEstimated,
+    nonSystemMessageTokensEstimated,
+    toolTokensEstimated,
+    totalTokensEstimated,
+    systemMessageCount,
+    toolCount: serializedTools.length
+  };
+}
+__name(estimatePromptContextUsage, "estimatePromptContextUsage");
+function promptContextUsageEstimateToAttributes(estimate) {
+  return {
+    "usage.prompt_context.system_tokens_estimated": estimate.systemTokensEstimated,
+    "usage.prompt_context.message_tokens_estimated": estimate.messageTokensEstimated,
+    "usage.prompt_context.non_system_message_tokens_estimated": estimate.nonSystemMessageTokensEstimated,
+    "usage.prompt_context.tool_tokens_estimated": estimate.toolTokensEstimated,
+    "usage.prompt_context.total_tokens_estimated": estimate.totalTokensEstimated,
+    "usage.prompt_context.system_message_count": estimate.systemMessageCount,
+    "usage.prompt_context.tool_count": estimate.toolCount
+  };
+}
+__name(promptContextUsageEstimateToAttributes, "promptContextUsageEstimateToAttributes");
+function estimateTokensFromText(text) {
+  if (!text) {
+    return 0;
+  }
+  return Math.ceil(text.length / ESTIMATED_CHARS_PER_TOKEN);
+}
+__name(estimateTokensFromText, "estimateTokensFromText");
+function serializePromptMessage(message) {
+  const content = serializePromptValue(message.content).trim();
+  if (!content) {
+    return "";
+  }
+  const role = typeof message.role === "string" ? message.role.toUpperCase() : "MESSAGE";
+  return `${role}:
+${content}`;
+}
+__name(serializePromptMessage, "serializePromptMessage");
+function serializePromptValue(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializePromptValue(entry)).filter((entry) => entry.trim().length > 0).join("\n");
+  }
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+  const record = value;
+  const type = typeof record.type === "string" ? record.type : void 0;
+  if (typeof record.text === "string") {
+    return record.text;
+  }
+  if (type && BINARY_PART_TYPES.has(type)) {
+    return `[${type}]`;
+  }
+  if (type === "tool-call") {
+    const toolName = typeof record.toolName === "string" ? record.toolName : "tool";
+    const input = serializePromptValue(record.input);
+    return input ? `tool-call ${toolName}: ${input}` : `tool-call ${toolName}`;
+  }
+  if (type === "tool-result") {
+    const toolName = typeof record.toolName === "string" ? record.toolName : "tool";
+    const output = serializePromptValue(record.output);
+    return output ? `tool-result ${toolName}: ${output}` : `tool-result ${toolName}`;
+  }
+  if ("content" in record) {
+    const nestedContent = serializePromptValue(record.content);
+    if (nestedContent) {
+      return nestedContent;
+    }
+  }
+  return (0, import_utils29.safeStringify)(sanitizeRecord(record));
+}
+__name(serializePromptValue, "serializePromptValue");
+function sanitizeRecord(record) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(record)) {
+    sanitized[key] = LARGE_BINARY_KEYS.has(key) ? "[omitted]" : value;
+  }
+  return sanitized;
+}
+__name(sanitizeRecord, "sanitizeRecord");
+function serializeToolDefinition(name, tool2) {
+  if (!tool2 || typeof tool2 !== "object") {
+    return { name };
+  }
+  const candidate = tool2;
+  return {
+    name,
+    ...typeof candidate.type === "string" ? { type: candidate.type } : {},
+    ...typeof candidate.id === "string" ? { id: candidate.id } : {},
+    ...typeof candidate.description === "string" ? { description: candidate.description } : {},
+    ...candidate.inputSchema || candidate.parameters || candidate.input_schema || candidate.schema ? {
+      inputSchema: normalizeSchema(
+        candidate.inputSchema ?? candidate.parameters ?? candidate.input_schema ?? candidate.schema
+      )
+    } : {},
+    ...candidate.outputSchema || candidate.output_schema ? {
+      outputSchema: normalizeSchema(candidate.outputSchema ?? candidate.output_schema)
+    } : {},
+    ...candidate.providerOptions ? { providerOptions: candidate.providerOptions } : {},
+    ...candidate.args ? { args: sanitizeRecord(candidate.args) } : {},
+    ...candidate.needsApproval !== void 0 ? { needsApproval: candidate.needsApproval } : {}
+  };
+}
+__name(serializeToolDefinition, "serializeToolDefinition");
+function normalizeSchema(schema) {
+  if (!schema || typeof schema !== "object") {
+    return schema;
+  }
+  try {
+    if ("_def" in schema) {
+      return zodSchemaToJsonUI(schema);
+    }
+  } catch (_error) {
+    return schema;
+  }
+  return schema;
+}
+__name(normalizeSchema, "normalizeSchema");
+
 // src/agent/tool-input-coercion.ts
 var isPathSegment = /* @__PURE__ */ __name((value) => typeof value === "string" || typeof value === "number", "isPathSegment");
 var isRecord2 = /* @__PURE__ */ __name((value) => typeof value === "object" && value !== null && !Array.isArray(value), "isRecord");
@@ -26639,7 +26805,7 @@ var coerceStringifiedJsonToolArgs = /* @__PURE__ */ __name((rawArgs, issues) =>
 var import_ts_pattern2 = require("ts-pattern");
 
 // src/agent/apply-summarization.ts
-var import_utils29 = require("@voltagent/internal/utils");
+var import_utils30 = require("@voltagent/internal/utils");
 var import_ai5 = require("ai");
 var SUMMARY_METADATA_KEY = "agent";
 var SUMMARY_STATE_CACHE_KEY = Symbol("agentSummaryState");
@@ -26752,7 +26918,7 @@ var applySummarization = /* @__PURE__ */ __name(async ({
         }
       } catch (error) {
         oc.logger.debug("[Agent] Failed to summarize conversation", {
-          error: (0, import_utils29.safeStringify)(error)
+          error: (0, import_utils30.safeStringify)(error)
         });
         if (summarySpan) {
           oc.traceContext.endChildSpan(summarySpan, "error", {
@@ -26835,7 +27001,7 @@ async function loadAgentSummaryState(agent, context8) {
       state = readSummaryStateFromMetadata(conversation?.metadata);
     } catch (error) {
       context8.logger.debug("[Agent] Failed to load summary state from memory", {
-        error: (0, import_utils29.safeStringify)(error)
+        error: (0, import_utils30.safeStringify)(error)
       });
     }
   }
@@ -26865,7 +27031,7 @@ async function updateAgentSummaryState(agent, context8, updater) {
       }
     } catch (error) {
       context8.logger.debug("[Agent] Failed to persist summary state", {
-        error: (0, import_utils29.safeStringify)(error)
+        error: (0, import_utils30.safeStringify)(error)
       });
     }
   }
@@ -26898,11 +27064,11 @@ function removeSystemMessagesWithMarker(messages, marker) {
   });
 }
 __name(removeSystemMessagesWithMarker, "removeSystemMessagesWithMarker");
-function estimateTokensFromText(text) {
+function estimateTokensFromText2(text) {
   if (!text) return 0;
   return Math.ceil(text.length / SUMMARY_CHAR_PER_TOKEN);
 }
-__name(estimateTokensFromText, "estimateTokensFromText");
+__name(estimateTokensFromText2, "estimateTokensFromText");
 function summarizePartValue(value) {
   if (typeof value === "string") {
     return truncateText2(value, SUMMARY_MAX_PART_CHARS);
@@ -26910,7 +27076,7 @@ function summarizePartValue(value) {
   if (value === null || value === void 0) {
     return "";
   }
-  return truncateText2((0, import_utils29.safeStringify)(value), SUMMARY_MAX_PART_CHARS);
+  return truncateText2((0, import_utils30.safeStringify)(value), SUMMARY_MAX_PART_CHARS);
 }
 __name(summarizePartValue, "summarizePartValue");
 function extractSummaryText(message) {
@@ -26965,7 +27131,7 @@ function estimateTokensFromMessages(messages) {
   for (const message of messages) {
     const formatted = formatMessageForSummary(message);
     if (formatted) {
-      total += estimateTokensFromText(formatted);
+      total += estimateTokensFromText2(formatted);
     }
   }
   return total;
@@ -28412,7 +28578,7 @@ var collapseRedundantStepStarts = /* @__PURE__ */ __name((parts) => {
 
 // src/agent/middleware.ts
 var import_api13 = require("@opentelemetry/api");
-var import_utils30 = require("@voltagent/internal/utils");
+var import_utils31 = require("@voltagent/internal/utils");
 function createInputMiddleware(options) {
   return {
     id: options.id,
@@ -28491,7 +28657,7 @@ function serializeMiddlewareValue(value) {
   if (typeof value === "string") {
     return value;
   }
-  return (0, import_utils30.safeStringify)(value);
+  return (0, import_utils31.safeStringify)(value);
 }
 __name(serializeMiddlewareValue, "serializeMiddlewareValue");
 async function runInputMiddlewares(input, oc, middlewares, operation, agent, retryCount) {
@@ -28515,8 +28681,8 @@ async function runInputMiddlewares(input, oc, middlewares, operation, agent, ret
           ...middleware.id ? { "middleware.id": middleware.id } : {},
           "middleware.name": middleware.name,
           ...middleware.description ? { "middleware.description": middleware.description } : {},
-          ...middleware.tags && middleware.tags.length > 0 ? { "middleware.tags": (0, import_utils30.safeStringify)(middleware.tags) } : {},
-          ...middleware.metadata ? { "middleware.metadata": (0, import_utils30.safeStringify)(middleware.metadata) } : {},
+          ...middleware.tags && middleware.tags.length > 0 ? { "middleware.tags": (0, import_utils31.safeStringify)(middleware.tags) } : {},
+          ...middleware.metadata ? { "middleware.metadata": (0, import_utils31.safeStringify)(middleware.metadata) } : {},
           "middleware.retry_count": retryCount,
           "middleware.input.original": serializeMiddlewareValue(originalInput),
           "middleware.input.current": serializeMiddlewareValue(currentInput)
@@ -28584,8 +28750,8 @@ async function runOutputMiddlewares(output, oc, middlewares, operation, agent, r
           ...middleware.id ? { "middleware.id": middleware.id } : {},
           "middleware.name": middleware.name,
           ...middleware.description ? { "middleware.description": middleware.description } : {},
-          ...middleware.tags && middleware.tags.length > 0 ? { "middleware.tags": (0, import_utils30.safeStringify)(middleware.tags) } : {},
-          ...middleware.metadata ? { "middleware.metadata": (0, import_utils30.safeStringify)(middleware.metadata) } : {},
+          ...middleware.tags && middleware.tags.length > 0 ? { "middleware.tags": (0, import_utils31.safeStringify)(middleware.tags) } : {},
+          ...middleware.metadata ? { "middleware.metadata": (0, import_utils31.safeStringify)(middleware.metadata) } : {},
           "middleware.retry_count": retryCount,
           "middleware.output.original": serializeMiddlewareValue(originalOutput),
           "middleware.output.current": serializeMiddlewareValue(currentOutput)
@@ -28593,13 +28759,13 @@ async function runOutputMiddlewares(output, oc, middlewares, operation, agent, r
       }
     );
     if (metadata?.usage !== void 0) {
-      span.setAttribute("middleware.usage", (0, import_utils30.safeStringify)(metadata.usage));
+      span.setAttribute("middleware.usage", (0, import_utils31.safeStringify)(metadata.usage));
     }
     if (metadata?.finishReason !== void 0 && metadata.finishReason !== null) {
       span.setAttribute("middleware.finish_reason", metadata.finishReason);
     }
     if (metadata?.warnings && metadata.warnings.length > 0) {
-      span.setAttribute("middleware.warnings", (0, import_utils30.safeStringify)(metadata.warnings));
+      span.setAttribute("middleware.warnings", (0, import_utils31.safeStringify)(metadata.warnings));
     }
     try {
       const abort = /* @__PURE__ */ __name((reason, options) => {
@@ -28647,7 +28813,7 @@ var import_ai6 = require("ai");
 
 // src/agent/streaming/output-guardrail-stream-runner.ts
 var import_api14 = require("@opentelemetry/api");
-var import_utils31 = require("@voltagent/internal/utils");
+var import_utils32 = require("@voltagent/internal/utils");
 var isTextDelta = /* @__PURE__ */ __name((part) => part.type === "text-delta", "isTextDelta");
 var extractChunkText = /* @__PURE__ */ __name((part) => {
   if (!isTextDelta(part)) {
@@ -28902,8 +29068,8 @@ var OutputGuardrailStreamRunner = class {
           "guardrail.name": guardrail.name,
           ...guardrail.description ? { "guardrail.description": guardrail.description } : {},
           ...guardrail.severity ? { "guardrail.severity": guardrail.severity } : {},
-          ...guardrail.tags && guardrail.tags.length > 0 ? { "guardrail.tags": (0, import_utils31.safeStringify)(guardrail.tags) } : {},
-          ...guardrail.metadata ? { "guardrail.metadata": (0, import_utils31.safeStringify)(guardrail.metadata) } : {}
+          ...guardrail.tags && guardrail.tags.length > 0 ? { "guardrail.tags": (0, import_utils32.safeStringify)(guardrail.tags) } : {},
+          ...guardrail.metadata ? { "guardrail.metadata": (0, import_utils32.safeStringify)(guardrail.metadata) } : {}
         }
       }
     );
@@ -29431,7 +29597,7 @@ __name(convertFullStreamChunkToUIMessageStream, "convertFullStreamChunkToUIMessa
 
 // src/agent/subagent/index.ts
 var import_api15 = require("@opentelemetry/api");
-var import_utils32 = require("@voltagent/internal/utils");
+var import_utils33 = require("@voltagent/internal/utils");
 var import_zod6 = require("zod");
 
 // src/agent/subagent/types.ts
@@ -29737,7 +29903,7 @@ ${guidelinesText}
         taskContent = `Task handed off from ${sourceAgent?.name || this.agentName} to ${targetAgent.name}:
 ${task}
 
-Context: ${(0, import_utils32.safeStringify)(contextObj, { indentation: 2 })}`;
+Context: ${(0, import_utils33.safeStringify)(contextObj, { indentation: 2 })}`;
       }
       const taskMessage = {
         id: crypto.randomUUID(),
@@ -29795,7 +29961,7 @@ Context: ${(0, import_utils32.safeStringify)(contextObj, { indentation: 2 })}`;
           options2
         );
         const finalObject = await response.object;
-        finalResult = (0, import_utils32.safeStringify)(finalObject);
+        finalResult = (0, import_utils33.safeStringify)(finalObject);
         finalMessages = [taskMessage, this.createAssistantMessage(finalResult)];
       } else if (this.isGenerateObjectConfig(targetAgentConfig)) {
         const options2 = { ...baseOptions, ...targetAgentConfig.options };
@@ -29804,7 +29970,7 @@ Context: ${(0, import_utils32.safeStringify)(contextObj, { indentation: 2 })}`;
           targetAgentConfig.schema,
           options2
         );
-        finalResult = (0, import_utils32.safeStringify)(response);
+        finalResult = (0, import_utils33.safeStringify)(response);
         usage = response.usage;
         finalMessages = [taskMessage, this.createAssistantMessage(finalResult)];
       } else {
@@ -30709,12 +30875,12 @@ var Agent = class {
             );
             const contextMap = Object.fromEntries(oc.context.entries());
             if (Object.keys(contextMap).length > 0) {
-              rootSpan.setAttribute("agent.context", (0, import_utils33.safeStringify)(contextMap));
+              rootSpan.setAttribute("agent.context", (0, import_utils34.safeStringify)(contextMap));
             }
-            rootSpan.setAttribute("agent.messages", (0, import_utils33.safeStringify)(messages));
-            rootSpan.setAttribute("agent.messages.ui", (0, import_utils33.safeStringify)(uiMessages));
+            rootSpan.setAttribute("agent.messages", (0, import_utils34.safeStringify)(messages));
+            rootSpan.setAttribute("agent.messages.ui", (0, import_utils34.safeStringify)(uiMessages));
             const agentState = this.getFullState();
-            rootSpan.setAttribute("agent.stateSnapshot", (0, import_utils33.safeStringify)(agentState));
+            rootSpan.setAttribute("agent.stateSnapshot", (0, import_utils34.safeStringify)(agentState));
             methodLogger.debug(
               buildAgentLogMessage(
                 this.name,
@@ -30935,7 +31101,7 @@ var Agent = class {
               operation: "generateText",
               metadata: {
                 finishReason: result.finishReason,
-                usage: usageForFinish ? JSON.parse((0, import_utils33.safeStringify)(usageForFinish)) : void 0,
+                usage: usageForFinish ? JSON.parse((0, import_utils34.safeStringify)(usageForFinish)) : void 0,
                 toolCalls: aggregatedToolCalls
               }
             });
@@ -31002,7 +31168,7 @@ var Agent = class {
                 maxMiddlewareRetries,
                 middlewareId: retryError.middlewareId ?? null,
                 reason: retryError.message ?? "middleware retry",
-                metadata: retryError.metadata !== void 0 ? (0, import_utils33.safeStringify)(retryError.metadata) : void 0
+                metadata: retryError.metadata !== void 0 ? (0, import_utils34.safeStringify)(retryError.metadata) : void 0
               });
               this.storeMiddlewareRetryFeedback(oc, retryError.message, retryError.metadata);
               middlewareRetryCount += 1;
@@ -31183,7 +31349,7 @@ var Agent = class {
                 maxMiddlewareRetries,
                 middlewareId: retryError.middlewareId ?? null,
                 reason: retryError.message ?? "middleware retry",
-                metadata: retryError.metadata !== void 0 ? (0, import_utils33.safeStringify)(retryError.metadata) : void 0
+                metadata: retryError.metadata !== void 0 ? (0, import_utils34.safeStringify)(retryError.metadata) : void 0
               });
               this.storeMiddlewareRetryFeedback(oc, retryError.message, retryError.metadata);
               middlewareRetryCount += 1;
@@ -31217,12 +31383,12 @@ var Agent = class {
           );
           const contextMap = Object.fromEntries(oc.context.entries());
           if (Object.keys(contextMap).length > 0) {
-            rootSpan2.setAttribute("agent.context", (0, import_utils33.safeStringify)(contextMap));
+            rootSpan2.setAttribute("agent.context", (0, import_utils34.safeStringify)(contextMap));
           }
-          rootSpan2.setAttribute("agent.messages", (0, import_utils33.safeStringify)(messages));
-          rootSpan2.setAttribute("agent.messages.ui", (0, import_utils33.safeStringify)(uiMessages));
+          rootSpan2.setAttribute("agent.messages", (0, import_utils34.safeStringify)(messages));
+          rootSpan2.setAttribute("agent.messages.ui", (0, import_utils34.safeStringify)(uiMessages));
           const agentState = this.getFullState();
-          rootSpan2.setAttribute("agent.stateSnapshot", (0, import_utils33.safeStringify)(agentState));
+          rootSpan2.setAttribute("agent.stateSnapshot", (0, import_utils34.safeStringify)(agentState));
         }
         methodLogger.debug(
           buildAgentLogMessage(
@@ -31504,7 +31670,7 @@ var Agent = class {
                   operation: "streamText",
                   metadata: {
                     finishReason: finalResult.finishReason,
-                    usage: usageForFinish ? JSON.parse((0, import_utils33.safeStringify)(usageForFinish)) : void 0,
+                    usage: usageForFinish ? JSON.parse((0, import_utils34.safeStringify)(usageForFinish)) : void 0,
                     toolCalls: finalResult.toolCalls
                   }
                 });
@@ -31891,12 +32057,12 @@ var Agent = class {
             );
             const contextMap = Object.fromEntries(oc.context.entries());
             if (Object.keys(contextMap).length > 0) {
-              rootSpan.setAttribute("agent.context", (0, import_utils33.safeStringify)(contextMap));
+              rootSpan.setAttribute("agent.context", (0, import_utils34.safeStringify)(contextMap));
             }
-            rootSpan.setAttribute("agent.messages", (0, import_utils33.safeStringify)(messages));
-            rootSpan.setAttribute("agent.messages.ui", (0, import_utils33.safeStringify)(uiMessages));
+            rootSpan.setAttribute("agent.messages", (0, import_utils34.safeStringify)(messages));
+            rootSpan.setAttribute("agent.messages.ui", (0, import_utils34.safeStringify)(uiMessages));
             const agentState = this.getFullState();
-            rootSpan.setAttribute("agent.stateSnapshot", (0, import_utils33.safeStringify)(agentState));
+            rootSpan.setAttribute("agent.stateSnapshot", (0, import_utils34.safeStringify)(agentState));
             methodLogger.debug(
               buildAgentLogMessage(
                 this.name,
@@ -32005,7 +32171,7 @@ var Agent = class {
                 parts: [
                   {
                     type: "text",
-                    text: (0, import_utils33.safeStringify)(finalObject)
+                    text: (0, import_utils34.safeStringify)(finalObject)
                   }
                 ]
               };
@@ -32013,7 +32179,7 @@ var Agent = class {
               const step = {
                 id: randomUUID(),
                 type: "text",
-                content: (0, import_utils33.safeStringify)(finalObject),
+                content: (0, import_utils34.safeStringify)(finalObject),
                 role: "assistant",
                 usage: usageInfo
               };
@@ -32027,7 +32193,7 @@ var Agent = class {
               operation: "generateObject",
               metadata: {
                 finishReason: result.finishReason,
-                usage: usageForFinish ? JSON.parse((0, import_utils33.safeStringify)(usageForFinish)) : void 0,
+                usage: usageForFinish ? JSON.parse((0, import_utils34.safeStringify)(usageForFinish)) : void 0,
                 schemaName
               }
             });
@@ -32086,7 +32252,7 @@ var Agent = class {
                 maxMiddlewareRetries,
                 middlewareId: retryError.middlewareId ?? null,
                 reason: retryError.message ?? "middleware retry",
-                metadata: retryError.metadata !== void 0 ? (0, import_utils33.safeStringify)(retryError.metadata) : void 0
+                metadata: retryError.metadata !== void 0 ? (0, import_utils34.safeStringify)(retryError.metadata) : void 0
               });
               this.storeMiddlewareRetryFeedback(oc, retryError.message, retryError.metadata);
               middlewareRetryCount += 1;
@@ -32156,7 +32322,7 @@ var Agent = class {
                 maxMiddlewareRetries,
                 middlewareId: retryError.middlewareId ?? null,
                 reason: retryError.message ?? "middleware retry",
-                metadata: retryError.metadata !== void 0 ? (0, import_utils33.safeStringify)(retryError.metadata) : void 0
+                metadata: retryError.metadata !== void 0 ? (0, import_utils34.safeStringify)(retryError.metadata) : void 0
               });
               this.storeMiddlewareRetryFeedback(oc, retryError.message, retryError.metadata);
               middlewareRetryCount += 1;
@@ -32187,12 +32353,12 @@ var Agent = class {
         );
         const contextMap = Object.fromEntries(oc.context.entries());
         if (Object.keys(contextMap).length > 0) {
-          rootSpan.setAttribute("agent.context", (0, import_utils33.safeStringify)(contextMap));
+          rootSpan.setAttribute("agent.context", (0, import_utils34.safeStringify)(contextMap));
         }
-        rootSpan.setAttribute("agent.messages", (0, import_utils33.safeStringify)(messages));
-        rootSpan.setAttribute("agent.messages.ui", (0, import_utils33.safeStringify)(uiMessages));
+        rootSpan.setAttribute("agent.messages", (0, import_utils34.safeStringify)(messages));
+        rootSpan.setAttribute("agent.messages.ui", (0, import_utils34.safeStringify)(uiMessages));
         const agentState = this.getFullState();
-        rootSpan.setAttribute("agent.stateSnapshot", (0, import_utils33.safeStringify)(agentState));
+        rootSpan.setAttribute("agent.stateSnapshot", (0, import_utils34.safeStringify)(agentState));
         methodLogger.debug(
           buildAgentLogMessage(
             this.name,
@@ -32355,7 +32521,7 @@ var Agent = class {
                       parts: [
                         {
                           type: "text",
-                          text: (0, import_utils33.safeStringify)(finalObject)
+                          text: (0, import_utils34.safeStringify)(finalObject)
                         }
                       ]
                     };
@@ -32363,7 +32529,7 @@ var Agent = class {
                     const step = {
                       id: randomUUID(),
                       type: "text",
-                      content: (0, import_utils33.safeStringify)(finalObject),
+                      content: (0, import_utils34.safeStringify)(finalObject),
                       role: "assistant",
                       usage: usageInfo
                     };
@@ -32410,7 +32576,7 @@ var Agent = class {
                     operation: "streamObject",
                     metadata: {
                       finishReason: finalResult.finishReason,
-                      usage: usageForFinish ? JSON.parse((0, import_utils33.safeStringify)(usageForFinish)) : void 0,
+                      usage: usageForFinish ? JSON.parse((0, import_utils34.safeStringify)(usageForFinish)) : void 0,
                       schemaName
                     }
                   });
@@ -32529,7 +32695,7 @@ var Agent = class {
     let feedback = `[Middleware Feedback] ${baseReason} Please retry with the feedback in mind.`;
     if (metadata !== void 0) {
       feedback = `${feedback}
-Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
+Metadata: ${(0, import_utils34.safeStringify)(metadata)}`;
     }
     oc.systemContext.set(MIDDLEWARE_RETRY_FEEDBACK_KEY, feedback);
   }
@@ -32629,8 +32795,8 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
             maxSteps,
             configuredToolCount,
             toolCallCount: toolCalls.length,
-            usage: usageForFinish ? JSON.parse((0, import_utils33.safeStringify)(usageForFinish)) : void 0,
-            providerMetadata: providerMetadata !== void 0 ? JSON.parse((0, import_utils33.safeStringify)(providerMetadata)) : void 0
+            usage: usageForFinish ? JSON.parse((0, import_utils34.safeStringify)(usageForFinish)) : void 0,
+            providerMetadata: providerMetadata !== void 0 ? JSON.parse((0, import_utils34.safeStringify)(providerMetadata)) : void 0
           }
         }
       );
@@ -32892,7 +33058,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
     for (const responseMessage of responseMessages) {
       const normalizedMessage = responseMessage.role === "assistant" ? { ...responseMessage, id: fallbackAssistantMessageId } : responseMessage;
       const fingerprintMessageId = normalizedMessage.role === "assistant" ? fallbackAssistantMessageId : normalizedMessage.id ?? null;
-      const fingerprint = (0, import_utils33.safeStringify)({
+      const fingerprint = (0, import_utils34.safeStringify)({
         role: normalizedMessage.role,
         id: fingerprintMessageId,
         content: normalizedMessage.content
@@ -32967,7 +33133,14 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
   }
   createLLMSpan(oc, params) {
     const { label, ...spanParams } = params;
-    const attributes = this.buildLLMSpanAttributes(spanParams);
+    const promptContextUsageEstimate = estimatePromptContextUsage({
+      messages: params.messages,
+      tools: params.tools
+    });
+    const attributes = {
+      ...this.buildLLMSpanAttributes(spanParams),
+      ...promptContextUsageEstimate ? promptContextUsageEstimateToAttributes(promptContextUsageEstimate) : {}
+    };
     const span = oc.traceContext.createChildSpan(`llm:${params.operation}`, "llm", {
       kind: import_api16.SpanKind.CLIENT,
       label,
@@ -33049,12 +33222,12 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
       attrs["llm.top_p"] = topP;
     }
     if (callOptions.stop !== void 0) {
-      attrs["llm.stop_condition"] = (0, import_utils33.safeStringify)(callOptions.stop);
+      attrs["llm.stop_condition"] = (0, import_utils34.safeStringify)(callOptions.stop);
     }
     if (params.messages && params.messages.length > 0) {
       attrs["llm.messages.count"] = params.messages.length;
       const trimmedMessages = params.messages.slice(-10);
-      attrs["llm.messages"] = (0, import_utils33.safeStringify)(
+      attrs["llm.messages"] = (0, import_utils34.safeStringify)(
         trimmedMessages.map((msg) => ({
           role: msg.role,
           content: msg.content
@@ -33069,7 +33242,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
       }
     }
     if (params.providerOptions) {
-      attrs["llm.provider_options"] = (0, import_utils33.safeStringify)(params.providerOptions);
+      attrs["llm.provider_options"] = (0, import_utils34.safeStringify)(params.providerOptions);
     }
     return attrs;
   }
@@ -33081,7 +33254,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
     if (!normalizedUsage) {
       return;
     }
-    const { promptTokens, completionTokens, totalTokens } = normalizedUsage;
+    const { promptTokens, completionTokens, totalTokens, cachedInputTokens, reasoningTokens } = normalizedUsage;
     if (promptTokens !== void 0) {
       span.setAttribute("llm.usage.prompt_tokens", promptTokens);
     }
@@ -33091,6 +33264,12 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
     if (totalTokens !== void 0) {
       span.setAttribute("llm.usage.total_tokens", totalTokens);
     }
+    if (cachedInputTokens !== void 0) {
+      span.setAttribute("llm.usage.cached_tokens", cachedInputTokens);
+    }
+    if (reasoningTokens !== void 0) {
+      span.setAttribute("llm.usage.reasoning_tokens", reasoningTokens);
+    }
   }
   recordProviderCost(span, providerMetadata) {
     const openRouterUsageCost = extractOpenRouterUsageCost(providerMetadata);
@@ -33336,7 +33515,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
         }
       } catch (error) {
         context8.logger.debug("[Memory] Failed to generate conversation title", {
-          error: (0, import_utils33.safeStringify)(error)
+          error: (0, import_utils34.safeStringify)(error)
         });
         return null;
       }
@@ -33372,7 +33551,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
           attributes: {
             "memory.operation": "read",
             "memory.semantic": isSemanticSearch,
-            input: (0, import_utils33.safeStringify)(spanInput),
+            input: (0, import_utils34.safeStringify)(spanInput),
             ...isSemanticSearch && {
               "memory.semantic.limit": semanticLimit,
               "memory.semantic.threshold": semanticThreshold,
@@ -33594,10 +33773,10 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
           rootSpan.setAttribute("prompt.version", metadata.version);
         }
         if (metadata.labels && metadata.labels.length > 0) {
-          rootSpan.setAttribute("prompt.labels", (0, import_utils33.safeStringify)(metadata.labels));
+          rootSpan.setAttribute("prompt.labels", (0, import_utils34.safeStringify)(metadata.labels));
         }
         if (metadata.tags && metadata.tags.length > 0) {
-          rootSpan.setAttribute("prompt.tags", (0, import_utils33.safeStringify)(metadata.tags));
+          rootSpan.setAttribute("prompt.tags", (0, import_utils34.safeStringify)(metadata.tags));
         }
         if (metadata.source) {
           rootSpan.setAttribute("prompt.source", metadata.source);
@@ -33609,7 +33788,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
           rootSpan.setAttribute("prompt.outdated", metadata.outdated);
         }
         if (metadata.config) {
-          rootSpan.setAttribute("prompt.config", (0, import_utils33.safeStringify)(metadata.config));
+          rootSpan.setAttribute("prompt.config", (0, import_utils34.safeStringify)(metadata.config));
         }
       }
     }
@@ -33810,7 +33989,7 @@ ${retrieverContext}`;
       label: this.retriever.tool.name || "Retriever",
       attributes: {
         "retriever.name": this.retriever.tool.name || "Retriever",
-        input: typeof input === "string" ? input : (0, import_utils33.safeStringify)(input),
+        input: typeof input === "string" ? input : (0, import_utils34.safeStringify)(input),
         ...this.getRetrieverObservabilityAttributes()
       }
     });
@@ -34057,7 +34236,7 @@ ${retrieverContext}`;
           nextModelIndex: nextCandidate ? index + 1 : void 0
         });
         logger.warn(`[Agent:${this.name}] - Failed to resolve model, falling back`, {
-          error: (0, import_utils33.safeStringify)(error),
+          error: (0, import_utils34.safeStringify)(error),
           modelIndex: index,
           operation
         });
@@ -34102,7 +34281,7 @@ ${retrieverContext}`;
               retryEligible,
               isRetryable: error?.isRetryable,
               statusCode: error?.statusCode,
-              error: (0, import_utils33.safeStringify)(error)
+              error: (0, import_utils34.safeStringify)(error)
             });
             await hooks.onRetry?.({
               agent: this,
@@ -34134,7 +34313,7 @@ ${retrieverContext}`;
               fallbackEligible,
               retryEligible,
               isLastModel,
-              error: (0, import_utils33.safeStringify)(error)
+              error: (0, import_utils34.safeStringify)(error)
             });
             throw error;
           }
@@ -34154,7 +34333,7 @@ ${retrieverContext}`;
             nextModelIndex: nextCandidate ? index + 1 : void 0
           });
           logger.warn(`[Agent:${this.name}] - Model failed, trying fallback`, {
-            error: (0, import_utils33.safeStringify)(error),
+            error: (0, import_utils34.safeStringify)(error),
             modelName,
             modelIndex: index,
             operation,
@@ -34374,9 +34553,9 @@ ${retrieverContext}`;
           "tool.name": tool2.name,
           "tool.call.id": toolCallId,
           "tool.description": tool2.description,
-          ...toolTags && toolTags.length > 0 ? { "tool.tags": (0, import_utils33.safeStringify)(toolTags) } : {},
-          "tool.parameters": (0, import_utils33.safeStringify)(tool2.parameters),
-          input: args ? (0, import_utils33.safeStringify)(args) : void 0
+          ...toolTags && toolTags.length > 0 ? { "tool.tags": (0, import_utils34.safeStringify)(toolTags) } : {},
+          "tool.parameters": (0, import_utils34.safeStringify)(tool2.parameters),
+          input: args ? (0, import_utils34.safeStringify)(args) : void 0
         },
         kind: import_api16.SpanKind.CLIENT
       });
@@ -34817,7 +34996,7 @@ ${retrieverContext}`;
             output: selections,
             attributes: {
               "tool.search.selection.count": selections.length,
-              "tool.search.selection.names": (0, import_utils33.safeStringify)(
+              "tool.search.selection.names": (0, import_utils34.safeStringify)(
                 selections.map((selection) => selection.name)
               )
             }
@@ -34825,7 +35004,7 @@ ${retrieverContext}`;
           oc.logger.debug("Tool search selections computed", {
             tool: TOOL_ROUTING_SEARCH_TOOL_NAME,
             query,
-            selections: (0, import_utils33.safeStringify)(selections)
+            selections: (0, import_utils34.safeStringify)(selections)
           });
         } catch (error) {
           oc.traceContext.endChildSpan(selectionSpan, "error", {
@@ -34971,7 +35150,7 @@ ${retrieverContext}`;
     const tools = {
       [tool2.name]: tool2
     };
-    const argsInstruction = `Use these tool arguments exactly: ${(0, import_utils33.safeStringify)(args)}`;
+    const argsInstruction = `Use these tool arguments exactly: ${(0, import_utils34.safeStringify)(args)}`;
     const result = await this.runInternalGenerateText({
       oc,
       messages: [
@@ -35316,7 +35495,7 @@ ${retrieverContext}`;
           oc.conversationSteps?.push({
             id: toolCall.toolCallId || randomUUID(),
             type: "tool_call",
-            content: (0, import_utils33.safeStringify)(toolCall.input ?? {}),
+            content: (0, import_utils34.safeStringify)(toolCall.input ?? {}),
             role: "assistant",
             name: toolCall.toolName,
             arguments: toolCall.input || {},
@@ -35348,7 +35527,7 @@ ${retrieverContext}`;
           oc.conversationSteps?.push({
             id: toolResult.toolCallId || randomUUID(),
             type: "tool_result",
-            content: (0, import_utils33.safeStringify)(toolResult.output),
+            content: (0, import_utils34.safeStringify)(toolResult.output),
             role: "assistant",
             name: toolResult.toolName,
             result: toolResult.output,
@@ -36230,7 +36409,7 @@ ${retrieverContext}`;
 };
 
 // src/planagent/plan-agent.ts
-var import_utils38 = require("@voltagent/internal/utils");
+var import_utils39 = require("@voltagent/internal/utils");
 var import_zod10 = require("zod");
 
 // src/planagent/context-keys.ts
@@ -36242,7 +36421,7 @@ var import_internal11 = require("@voltagent/internal");
 var import_zod8 = require("zod");
 
 // src/planagent/state.ts
-var import_utils35 = require("@voltagent/internal/utils");
+var import_utils36 = require("@voltagent/internal/utils");
 var PLANAGENT_METADATA_KEY = "planagent";
 var STATE_CACHE_KEY = Symbol("planagentState");
 var fallbackState = /* @__PURE__ */ new Map();
@@ -36254,13 +36433,13 @@ function readStateFromMetadata(metadata) {
   if (!metadata) return null;
   const entry = metadata[PLANAGENT_METADATA_KEY];
   if (!entry || typeof entry !== "object") return null;
-  return (0, import_utils35.deepClone)(entry);
+  return (0, import_utils36.deepClone)(entry);
 }
 __name(readStateFromMetadata, "readStateFromMetadata");
 async function loadPlanAgentState(agent, context8) {
   const cached = context8.systemContext.get(STATE_CACHE_KEY);
   if (cached) {
-    return (0, import_utils35.deepClone)(cached);
+    return (0, import_utils36.deepClone)(cached);
   }
   let state = null;
   const memory = agent.getMemory();
@@ -36270,23 +36449,23 @@ async function loadPlanAgentState(agent, context8) {
       state = readStateFromMetadata(conversation?.metadata);
     } catch (error) {
       context8.logger.debug("[PlanAgent] Failed to load state from memory", {
-        error: (0, import_utils35.safeStringify)(error)
+        error: (0, import_utils36.safeStringify)(error)
       });
     }
   }
   if (!state) {
-    state = (0, import_utils35.deepClone)(fallbackState.get(getConversationKey(context8)) || {});
+    state = (0, import_utils36.deepClone)(fallbackState.get(getConversationKey(context8)) || {});
   }
   context8.systemContext.set(STATE_CACHE_KEY, state);
-  return (0, import_utils35.deepClone)(state);
+  return (0, import_utils36.deepClone)(state);
 }
 __name(loadPlanAgentState, "loadPlanAgentState");
 async function updatePlanAgentState(agent, context8, updater) {
   const current = await loadPlanAgentState(agent, context8);
-  const nextState = updater((0, import_utils35.deepClone)(current));
+  const nextState = updater((0, import_utils36.deepClone)(current));
   const normalized = nextState || {};
   context8.systemContext.set(STATE_CACHE_KEY, normalized);
-  fallbackState.set(getConversationKey(context8), (0, import_utils35.deepClone)(normalized));
+  fallbackState.set(getConversationKey(context8), (0, import_utils36.deepClone)(normalized));
   const memory = agent.getMemory();
   if (memory && context8.conversationId) {
     try {
@@ -36294,17 +36473,17 @@ async function updatePlanAgentState(agent, context8, updater) {
       if (conversation) {
         const metadata = {
           ...conversation.metadata,
-          [PLANAGENT_METADATA_KEY]: (0, import_utils35.deepClone)(normalized)
+          [PLANAGENT_METADATA_KEY]: (0, import_utils36.deepClone)(normalized)
         };
         await memory.updateConversation(context8.conversationId, { metadata });
       }
     } catch (error) {
       context8.logger.debug("[PlanAgent] Failed to persist state", {
-        error: (0, import_utils35.safeStringify)(error)
+        error: (0, import_utils36.safeStringify)(error)
       });
     }
   }
-  return (0, import_utils35.deepClone)(normalized);
+  return (0, import_utils36.deepClone)(normalized);
 }
 __name(updatePlanAgentState, "updatePlanAgentState");
 
@@ -36714,7 +36893,7 @@ function createToolResultEvictor(options) {
 __name(createToolResultEvictor, "createToolResultEvictor");
 
 // src/planagent/planning/index.ts
-var import_utils37 = require("@voltagent/internal/utils");
+var import_utils38 = require("@voltagent/internal/utils");
 var import_zod9 = require("zod");
 
 // src/planagent/planning/backend.ts
@@ -36858,7 +37037,7 @@ function createPlanningToolkit(agent, options = {}) {
         toolSpan.setAttribute("planagent.todos.done", doneCount);
         toolSpan.setAttribute("planagent.todos.truncated", snapshot.truncated);
         toolSpan.setAttribute("planagent.todos.blocked_done", blockedCount);
-        toolSpan.setAttribute("planagent.todos", (0, import_utils37.safeStringify)(snapshot.todos));
+        toolSpan.setAttribute("planagent.todos", (0, import_utils38.safeStringify)(snapshot.todos));
       }
       return {
         todos: guardedTodos,
@@ -37434,7 +37613,7 @@ function createTaskToolkit(options) {
         parentSpan: toolSpan
       });
       if (toolSpan) {
-        const responsePreview = typeof result.result === "string" ? truncateText3(result.result, 500) : truncateText3((0, import_utils38.safeStringify)(result.result), 500);
+        const responsePreview = typeof result.result === "string" ? truncateText3(result.result, 500) : truncateText3((0, import_utils39.safeStringify)(result.result), 500);
         toolSpan.setAttribute("planagent.task.status", result.bailed ? "bailed" : "completed");
         toolSpan.setAttribute("planagent.task.response_preview", responsePreview);
       }
@@ -41167,7 +41346,7 @@ var import_node_crypto = __toESM(require("crypto"));
 var import_node_fs3 = __toESM(require("fs"));
 var import_node_os = __toESM(require("os"));
 var import_node_path3 = __toESM(require("path"));
-var import_utils39 = require("@voltagent/internal/utils");
+var import_utils40 = require("@voltagent/internal/utils");
 var getEnvPaths = /* @__PURE__ */ __name((name) => {
   const homedir = import_node_os.default.homedir();
   const tmpdir = import_node_os.default.tmpdir();
@@ -41237,7 +41416,7 @@ var writeUpdateCache = /* @__PURE__ */ __name(async (projectPath, cache) => {
   try {
     ensureCacheDir();
     const cacheFilePath = getCacheFilePath(projectPath);
-    import_node_fs3.default.writeFileSync(cacheFilePath, (0, import_utils39.safeStringify)(cache, { indentation: 2 }), "utf8");
+    import_node_fs3.default.writeFileSync(cacheFilePath, (0, import_utils40.safeStringify)(cache, { indentation: 2 }), "utf8");
   } catch (error) {
     const logger = new LoggerProxy({ component: "update-cache" });
     logger.error("Error writing update cache", { error });
@@ -42292,7 +42471,7 @@ var VoltAgent = class {
 };
 
 // src/index.ts
-var import_utils40 = require("@voltagent/internal/utils");
+var import_utils41 = require("@voltagent/internal/utils");
 var import_ai9 = require("ai");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {