@voltagent/core 2.1.1 → 2.1.2

package/dist/index.d.mts

@@ -3635,6 +3635,13 @@ interface ObservabilityConfig {
     logger?: Logger;
     resourceAttributes?: Record<string, any>;
     spanFilters?: SpanFilterConfig;
+    /**
+     * Controls whether flushOnFinish() runs automatically.
+     * - "auto": flush only in serverless (default)
+     * - "always": always flush
+     * - "never": never flush
+     */
+    flushOnFinishStrategy?: "auto" | "always" | "never";
     voltOpsSync?: {
         sampling?: ObservabilitySamplingConfig;
         maxQueueSize?: number;
@@ -3875,6 +3882,7 @@ declare class VoltAgentObservability$1 {
     private logger;
     private spanFilterOptions?;
     private instrumentationScopeName;
+    private flushLock;
     constructor(config?: ObservabilityConfig);
     /**
      * Set up span processors
@@ -3914,6 +3922,8 @@ declare class VoltAgentObservability$1 {
      * is incorrectly detected or if we are in a short-lived process.
      */
     flushOnFinish(): Promise<void>;
+    private shouldFlushOnFinish;
+    private withFlushLock;
     getProvider(): NodeTracerProvider;
     getContext(): typeof context;
     getTraceAPI(): typeof trace;
@@ -3940,6 +3950,7 @@ declare class ServerlessVoltAgentObservability {
     private spanFilterOptions?;
     private instrumentationScopeName;
     private spanStack;
+    private flushLock;
     constructor(config?: ObservabilityConfig);
     private setupProcessors;
     private applySpanFilter;
@@ -3975,6 +3986,7 @@ declare class ServerlessVoltAgentObservability {
      * This is the preferred method to call at the end of a request.
      */
     flushOnFinish(): Promise<void>;
+    private withFlushLock;
     getProvider(): BasicTracerProvider;
     getContext(): typeof context;
     getTraceAPI(): typeof trace;

package/dist/index.d.ts

@@ -3635,6 +3635,13 @@ interface ObservabilityConfig {
     logger?: Logger;
     resourceAttributes?: Record<string, any>;
     spanFilters?: SpanFilterConfig;
+    /**
+     * Controls whether flushOnFinish() runs automatically.
+     * - "auto": flush only in serverless (default)
+     * - "always": always flush
+     * - "never": never flush
+     */
+    flushOnFinishStrategy?: "auto" | "always" | "never";
     voltOpsSync?: {
         sampling?: ObservabilitySamplingConfig;
         maxQueueSize?: number;
@@ -3875,6 +3882,7 @@ declare class VoltAgentObservability$1 {
     private logger;
     private spanFilterOptions?;
     private instrumentationScopeName;
+    private flushLock;
     constructor(config?: ObservabilityConfig);
     /**
      * Set up span processors
@@ -3914,6 +3922,8 @@ declare class VoltAgentObservability$1 {
      * is incorrectly detected or if we are in a short-lived process.
      */
     flushOnFinish(): Promise<void>;
+    private shouldFlushOnFinish;
+    private withFlushLock;
     getProvider(): NodeTracerProvider;
     getContext(): typeof context;
     getTraceAPI(): typeof trace;
@@ -3940,6 +3950,7 @@ declare class ServerlessVoltAgentObservability {
     private spanFilterOptions?;
     private instrumentationScopeName;
     private spanStack;
+    private flushLock;
     constructor(config?: ObservabilityConfig);
     private setupProcessors;
     private applySpanFilter;
@@ -3975,6 +3986,7 @@ declare class ServerlessVoltAgentObservability {
      * This is the preferred method to call at the end of a request.
      */
     flushOnFinish(): Promise<void>;
+    private withFlushLock;
     getProvider(): BasicTracerProvider;
     getContext(): typeof context;
     getTraceAPI(): typeof trace;

package/dist/index.js

@@ -5757,6 +5757,7 @@ var VoltAgentObservability = class {
   logger;
   spanFilterOptions;
   instrumentationScopeName;
+  flushLock = Promise.resolve();
   constructor(config = {}) {
     this.config = config;
     this.logger = getGlobalLogger();
@@ -6008,7 +6009,35 @@ var VoltAgentObservability = class {
    * is incorrectly detected or if we are in a short-lived process.
    */
   async flushOnFinish() {
-    await this.forceFlush();
+    if (!this.shouldFlushOnFinish()) {
+      return;
+    }
+    await this.withFlushLock(async () => {
+      await this.forceFlush();
+    });
+  }
+  shouldFlushOnFinish() {
+    const strategy = this.config.flushOnFinishStrategy ?? "auto";
+    if (strategy === "never") {
+      return false;
+    }
+    if (strategy === "always") {
+      return true;
+    }
+    return false;
+  }
+  async withFlushLock(fn) {
+    const previous = this.flushLock;
+    let release;
+    this.flushLock = new Promise((resolve2) => {
+      release = resolve2;
+    });
+    await previous;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
   }
   getProvider() {
     return this.provider;
@@ -6058,6 +6087,7 @@ var ServerlessVoltAgentObservability = class {
   spanFilterOptions;
   instrumentationScopeName;
   spanStack = [];
+  flushLock = Promise.resolve();
   constructor(config = {}) {
     this.config = { ...config };
     this.instrumentationScopeName = config.instrumentationScopeName || "@voltagent/core";
@@ -6315,11 +6345,18 @@ var ServerlessVoltAgentObservability = class {
    * This is the preferred method to call at the end of a request.
    */
   async flushOnFinish() {
+    const strategy = this.config.flushOnFinishStrategy ?? "auto";
+    if (strategy === "never") {
+      return;
+    }
     const waitUntil = globalThis.___voltagent_wait_until;
-    if (waitUntil) {
+    const scheduleFlush = /* @__PURE__ */ __name(() => this.withFlushLock(async () => {
+      await this.forceFlush();
+    }), "scheduleFlush");
+    if (strategy !== "always" && waitUntil) {
       try {
         waitUntil(
-          this.forceFlush().catch((err) => {
+          scheduleFlush().catch((err) => {
             console.warn("[voltagent] Background flush failed", err);
           })
         );
@@ -6328,7 +6365,20 @@ var ServerlessVoltAgentObservability = class {
         console.warn("[voltagent] waitUntil failed, falling back to blocking flush", error);
       }
     }
-    await this.forceFlush();
+    await scheduleFlush();
+  }
+  async withFlushLock(fn) {
+    const previous = this.flushLock;
+    let release;
+    this.flushLock = new Promise((resolve2) => {
+      release = resolve2;
+    });
+    await previous;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
   }
   getProvider() {
     return this.provider;
@@ -8065,7 +8115,7 @@ function createWorkflow({
             await hooks?.onStepEnd?.(stateManager.state);
             traceContext.recordCancellation(reason);
             traceContext.end("cancelled");
-            await observability.flushOnFinish();
+            await safeFlushOnFinish(observability);
             workflowRegistry.activeExecutions.delete(executionId);
             try {
               await effectiveMemory.updateWorkflowState(executionId, {
@@ -8186,7 +8236,7 @@ function createWorkflow({
               checkpoint
             );
             traceContext.end("suspended");
-            await observability.flushOnFinish();
+            await safeFlushOnFinish(observability);
             runLogger.debug(
               `Workflow suspended | user=${options?.userId || "anonymous"} conv=${options?.conversationId || "none"} step=${index}`,
               {
@@ -8315,7 +8365,7 @@ function createWorkflow({
               suspensionMetadata?.checkpoint
             );
             traceContext.end("suspended");
-            await observability.flushOnFinish();
+            await safeFlushOnFinish(observability);
             try {
               await saveSuspensionState(
                 suspensionMetadata,
@@ -8527,7 +8577,7 @@ function createWorkflow({
         traceContext.setOutput(finalState.result);
         traceContext.setUsage(stateManager.state.usage);
         traceContext.end("completed");
-        await observability.flushOnFinish();
+        await safeFlushOnFinish(observability);
         try {
           await effectiveMemory.updateWorkflowState(executionContext.executionId, {
             status: "completed",
@@ -8578,7 +8628,7 @@ function createWorkflow({
           stateManager.cancel(cancellationReason);
           traceContext.recordCancellation(cancellationReason);
           traceContext.end("cancelled");
-          await observability.flushOnFinish();
+          await safeFlushOnFinish(observability);
           workflowRegistry.activeExecutions.delete(executionId);
           emitAndCollectEvent({
             type: "workflow-cancelled",
@@ -8627,7 +8677,7 @@ function createWorkflow({
             stateManager.state.suspension?.checkpoint
           );
           traceContext.end("suspended");
-          await observability.flushOnFinish();
+          await safeFlushOnFinish(observability);
           if (stateManager.state.status === "suspended") {
             await runTerminalHooks("suspended", { includeEnd: false });
           }
@@ -8647,7 +8697,7 @@ function createWorkflow({
           );
         }
         traceContext.end("error", error);
-        await observability.flushOnFinish();
+        await safeFlushOnFinish(observability);
         runLogger.debug(
           `Workflow failed | user=${options?.userId || "anonymous"} conv=${options?.conversationId || "none"} error=${error instanceof Error ? error.message : String(error)}`,
           {
@@ -8980,6 +9030,13 @@ async function executeWithSignalCheck(fn, signal, checkInterval = 100) {
   return Promise.race([fn(), abortPromise]);
 }
 __name(executeWithSignalCheck, "executeWithSignalCheck");
+async function safeFlushOnFinish(observability) {
+  try {
+    await observability.flushOnFinish();
+  } catch {
+  }
+}
+__name(safeFlushOnFinish, "safeFlushOnFinish");
 function serializeWorkflowStep(step, index) {
   const baseStep = {
     id: step.id,