@voltagent/core 2.6.6 → 2.6.7

package/dist/index.d.mts

@@ -8404,6 +8404,11 @@ interface CommonRuntimeMemoryBehaviorOptions {
     contextLimit?: number;
     semanticMemory?: CommonSemanticMemoryOptions;
     conversationPersistence?: AgentConversationPersistenceOptions;
+    /**
+     * When true, memory is read-only for the current call.
+     * Existing memory context can be loaded, but no writes are persisted.
+     */
+    readOnly?: boolean;
 }
 interface CommonRuntimeMemoryEnvelope {
     conversationId?: string;
@@ -8418,6 +8423,7 @@ interface CommonResolvedRuntimeMemoryOptions {
     contextLimit?: number;
     semanticMemory?: CommonSemanticMemoryOptions;
     conversationPersistence?: AgentConversationPersistenceOptions;
+    readOnly?: boolean;
 }
 /**
  * Agent status information
@@ -9039,7 +9045,9 @@ declare class MemoryManager {
      * Ensures context is always loaded, optimizes non-critical operations in background
      * PRESERVED FROM ORIGINAL
      */
-    prepareConversationContext(context: OperationContext, input: string | UIMessage[], userId?: string, conversationIdParam?: string, contextLimit?: number): Promise<{
+    prepareConversationContext(context: OperationContext, input: string | UIMessage[], userId?: string, conversationIdParam?: string, contextLimit?: number, options?: {
+        persistInput?: boolean;
+    }): Promise<{
         messages: UIMessage<{
             createdAt: Date;
         }>[];
@@ -9376,6 +9384,8 @@ declare class Agent {
     private resetOperationAttemptState;
     private getConversationBuffer;
     private getMemoryPersistQueue;
+    private isReadOnlyMemoryForContext;
+    private shouldPersistMemoryForContext;
     private ensureStreamingResponseMessageId;
     private getOrCreateStepResponseMessageId;
     private getStepResponseMessageFingerprints;

package/dist/index.d.ts

@@ -8404,6 +8404,11 @@ interface CommonRuntimeMemoryBehaviorOptions {
     contextLimit?: number;
     semanticMemory?: CommonSemanticMemoryOptions;
     conversationPersistence?: AgentConversationPersistenceOptions;
+    /**
+     * When true, memory is read-only for the current call.
+     * Existing memory context can be loaded, but no writes are persisted.
+     */
+    readOnly?: boolean;
 }
 interface CommonRuntimeMemoryEnvelope {
     conversationId?: string;
@@ -8418,6 +8423,7 @@ interface CommonResolvedRuntimeMemoryOptions {
     contextLimit?: number;
     semanticMemory?: CommonSemanticMemoryOptions;
     conversationPersistence?: AgentConversationPersistenceOptions;
+    readOnly?: boolean;
 }
 /**
  * Agent status information
@@ -9039,7 +9045,9 @@ declare class MemoryManager {
      * Ensures context is always loaded, optimizes non-critical operations in background
      * PRESERVED FROM ORIGINAL
      */
-    prepareConversationContext(context: OperationContext, input: string | UIMessage[], userId?: string, conversationIdParam?: string, contextLimit?: number): Promise<{
+    prepareConversationContext(context: OperationContext, input: string | UIMessage[], userId?: string, conversationIdParam?: string, contextLimit?: number, options?: {
+        persistInput?: boolean;
+    }): Promise<{
         messages: UIMessage<{
             createdAt: Date;
         }>[];
@@ -9376,6 +9384,8 @@ declare class Agent {
     private resetOperationAttemptState;
     private getConversationBuffer;
     private getMemoryPersistQueue;
+    private isReadOnlyMemoryForContext;
+    private shouldPersistMemoryForContext;
     private ensureStreamingResponseMessageId;
     private getOrCreateStepResponseMessageId;
     private getStepResponseMessageFingerprints;

package/dist/index.js

@@ -13068,7 +13068,7 @@ var MemoryManager = class {
    * Ensures context is always loaded, optimizes non-critical operations in background
    * PRESERVED FROM ORIGINAL
    */
-  async prepareConversationContext(context8, input, userId, conversationIdParam, contextLimit = 10) {
+  async prepareConversationContext(context8, input, userId, conversationIdParam, contextLimit = 10, options) {
     const conversationId = conversationIdParam || randomUUID();
     if (contextLimit === 0) {
       return { messages: [], conversationId };
@@ -13098,7 +13098,9 @@ var MemoryManager = class {
         error
       });
     }
-    this.handleSequentialBackgroundOperations(context8, input, userId, conversationId);
+    if (options?.persistInput !== false) {
+      this.handleSequentialBackgroundOperations(context8, input, userId, conversationId);
+    }
     return { messages, conversationId };
   }
   /**
@@ -21481,24 +21483,18 @@ var truncateByBytes = /* @__PURE__ */ __name((value, maxBytes) => {
   const truncated = buf.subarray(0, targetBytes).toString("utf-8");
   return `${truncated}${TRUNCATION_SUFFIX}`;
 }, "truncateByBytes");
-var formatStreamOutput = /* @__PURE__ */ __name((label, info) => {
-  const lines = [];
+var formatStreamSummary = /* @__PURE__ */ __name((label, info) => {
   if (info.evicted && info.path) {
-    const note = info.truncated ? " (truncated)" : "";
-    lines.push(`${label}: saved to ${info.path} (${info.bytes} bytes${note})`);
-    if (info.error) {
-      lines.push(`${label} eviction error: ${info.error}`);
-    }
-    return lines;
+    const note = info.truncated ? ", truncated" : "";
+    const errorNote = info.error ? `, eviction error: ${info.error}` : "";
+    return `${label}: saved to ${info.path} (${info.bytes} bytes${note}${errorNote})`;
   }
   if (info.content) {
-    lines.push(`${label}:`);
-    lines.push(info.content);
-    return lines;
+    const note = info.truncated ? ", truncated" : "";
+    return `${label}: captured inline (${info.bytes} bytes${note})`;
   }
-  lines.push(`${label}: (empty)`);
-  return lines;
-}, "formatStreamOutput");
+  return `${label}: (empty)`;
+}, "formatStreamSummary");
 var createWorkspaceSandboxToolkit = /* @__PURE__ */ __name((context8, options = {}) => {
   const pathContext = resolvePathContext(context8);
   const systemPrompt = options.systemPrompt === void 0 ? buildSystemPrompt(pathContext) : options.systemPrompt;
@@ -21631,8 +21627,8 @@ var createWorkspaceSandboxToolkit = /* @__PURE__ */ __name((context8, options =
           const stderrInfo = await evictStream("stderr", result.stderr, result.stderrTruncated);
           const lines = [];
           lines.push(...formatSandboxHeader(result));
-          lines.push(...formatStreamOutput("STDOUT", stdoutInfo));
-          lines.push(...formatStreamOutput("STDERR", stderrInfo));
+          lines.push(formatStreamSummary("STDOUT", stdoutInfo));
+          lines.push(formatStreamSummary("STDERR", stderrInfo));
           const summary = lines.join("\n");
           const streamErrors = [stdoutInfo.error, stderrInfo.error].filter(
             (value) => Boolean(value)
@@ -30041,6 +30037,14 @@ var firstNonBlank = /* @__PURE__ */ __name((...values) => {
   }
   return void 0;
 }, "firstNonBlank");
+var firstDefined = /* @__PURE__ */ __name((...values) => {
+  for (const value of values) {
+    if (value !== null && value !== void 0) {
+      return value;
+    }
+  }
+  return void 0;
+}, "firstDefined");
 var isAssistantContentPart = /* @__PURE__ */ __name((value) => {
   if (!isRecord4(value)) {
     return false;
@@ -30445,6 +30449,7 @@ var Agent = class {
     const feedbackOptions = this.resolveFeedbackOptions(options);
     const feedbackClient = feedbackOptions ? this.getFeedbackClient() : void 0;
     const shouldDeferPersist = Boolean(feedbackOptions && feedbackClient);
+    const shouldPersistMemory = this.shouldPersistMemoryForContext(oc);
     let feedbackMetadata = null;
     const rootSpan = oc.traceContext.getRootSpan();
     return await oc.traceContext.withSpan(rootSpan, async () => {
@@ -30640,7 +30645,7 @@ var Agent = class {
               }
             );
             void this.recordStepResults(result.steps, oc);
-            if (!shouldDeferPersist) {
+            if (!shouldDeferPersist && shouldPersistMemory) {
               await persistQueue.flush(buffer, oc);
             }
             const finalText = await runOutputGuardrails({
@@ -30722,7 +30727,7 @@ var Agent = class {
                 }
               }
             }
-            if (shouldDeferPersist) {
+            if (shouldDeferPersist && shouldPersistMemory) {
               await persistQueue.flush(buffer, oc);
             }
             const feedbackValue = (() => {
@@ -30848,6 +30853,7 @@ var Agent = class {
     const feedbackOptions = this.resolveFeedbackOptions(options);
     const feedbackClient = feedbackOptions ? this.getFeedbackClient() : void 0;
     const shouldDeferPersist = Boolean(feedbackOptions && feedbackClient);
+    const shouldPersistMemory = this.shouldPersistMemoryForContext(oc);
     const feedbackDeferred = feedbackOptions ? createDeferred() : null;
     let feedbackMetadataValue = null;
     let feedbackValue = null;
@@ -30887,7 +30893,7 @@ var Agent = class {
             { requirePending: true }
           );
         }
-        if (shouldDeferPersist) {
+        if (shouldDeferPersist && shouldPersistMemory) {
           void persistQueue.flush(buffer, oc).catch((error) => {
             oc.logger?.debug?.("Failed to persist feedback metadata", { error });
           });
@@ -31162,7 +31168,7 @@ var Agent = class {
                   usage: providerUsage,
                   finishReason: finalResult.finishReason
                 });
-                if (!shouldDeferPersist) {
+                if (!shouldDeferPersist && shouldPersistMemory) {
                   await persistQueue.flush(buffer, oc);
                 }
                 this.setTraceContextUsage(oc.traceContext, usageForFinish);
@@ -31276,7 +31282,7 @@ var Agent = class {
                 }
                 if (feedbackResolved && feedbackMetadataValue) {
                   scheduleFeedbackPersist(feedbackMetadataValue);
-                } else if (shouldDeferPersist) {
+                } else if (shouldDeferPersist && shouldPersistMemory) {
                   void persistQueue.flush(buffer, oc).catch((error) => {
                     oc.logger?.debug?.("Failed to persist deferred messages", { error });
                   });
@@ -31749,7 +31755,7 @@ var Agent = class {
                 warnings: result.warnings ?? null
               }
             });
-            if (oc.userId && oc.conversationId) {
+            if (this.shouldPersistMemoryForContext(oc) && oc.userId && oc.conversationId) {
               const message = {
                 id: randomUUID(),
                 role: "assistant",
@@ -32095,7 +32101,7 @@ var Agent = class {
                     });
                     resolveGuardrailObject?.(finalObject);
                   }
-                  if (oc.userId && oc.conversationId) {
+                  if (this.shouldPersistMemoryForContext(oc) && oc.userId && oc.conversationId) {
                     const message = {
                       id: randomUUID(),
                       role: "assistant",
@@ -32388,7 +32394,12 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
       ),
       contextLimit: contextResolvedMemory?.contextLimit ?? memoryOptions?.contextLimit ?? options?.contextLimit ?? parentResolvedMemory?.contextLimit,
       semanticMemory: contextResolvedMemory?.semanticMemory ?? memoryOptions?.semanticMemory ?? options?.semanticMemory ?? parentResolvedMemory?.semanticMemory,
-      conversationPersistence: contextResolvedMemory?.conversationPersistence ?? memoryOptions?.conversationPersistence ?? options?.conversationPersistence ?? parentResolvedMemory?.conversationPersistence
+      conversationPersistence: contextResolvedMemory?.conversationPersistence ?? memoryOptions?.conversationPersistence ?? options?.conversationPersistence ?? parentResolvedMemory?.conversationPersistence,
+      readOnly: firstDefined(
+        contextResolvedMemory?.readOnly,
+        memoryOptions?.readOnly,
+        parentResolvedMemory?.readOnly
+      )
     };
   }
   getConversationPersistenceOptionsForContext(oc) {
@@ -32546,6 +32557,12 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
     }
     return queue;
   }
+  isReadOnlyMemoryForContext(oc) {
+    return oc.resolvedMemory?.readOnly === true;
+  }
+  shouldPersistMemoryForContext(oc) {
+    return !this.isReadOnlyMemoryForContext(oc);
+  }
   async ensureStreamingResponseMessageId(oc, buffer) {
     const messageId = this.getOrCreateStepResponseMessageId(oc);
     const placeholder = {
@@ -32598,6 +32615,9 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
     return normalized.length > 0 ? normalized : void 0;
   }
   async flushPendingMessagesOnError(oc) {
+    if (!this.shouldPersistMemoryForContext(oc)) {
+      return;
+    }
     const buffer = this.getConversationBuffer(oc);
     const queue = this.getMemoryPersistQueue(oc);
     if (!buffer || !queue) {
@@ -33006,6 +33026,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
     const messages = [];
     const resolvedMemory = this.resolveMemoryRuntimeOptions(options, oc);
     const canIUseMemory = Boolean(resolvedMemory.userId);
+    const shouldPersistMemory = resolvedMemory.readOnly !== true;
     const memoryContextMessages = [];
     if (canIUseMemory) {
       const useSemanticSearch = resolvedMemory.semanticMemory?.enabled ?? this.hasSemanticSearchSupport();
@@ -33061,7 +33082,8 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
               inputForMemory,
               oc.userId,
               oc.conversationId,
-              resolvedMemory.contextLimit
+              resolvedMemory.contextLimit,
+              { persistInput: shouldPersistMemory }
             );
             oc.conversationId = result.conversationId;
             if (oc.resolvedMemory) {
@@ -33084,7 +33106,7 @@ Metadata: ${(0, import_utils33.safeStringify)(metadata)}`;
             }
           }
           memoryContextMessages.push(...memoryResult);
-          if (isSemanticSearch && oc.userId && oc.conversationId) {
+          if (isSemanticSearch && shouldPersistMemory && oc.userId && oc.conversationId) {
             try {
               const inputForMemory = typeof resolvedInput === "string" ? resolvedInput : Array.isArray(resolvedInput) && resolvedInput[0]?.parts ? resolvedInput : convertModelMessagesToUIMessages(resolvedInput);
               this.memoryManager.queueSaveInput(oc, inputForMemory, oc.userId, oc.conversationId);
@@ -34770,7 +34792,8 @@ ${retrieverContext}`;
    */
   createStepHandler(oc, options) {
     const buffer = this.getConversationBuffer(oc);
-    const persistQueue = this.getMemoryPersistQueue(oc);
+    const shouldPersistMemory = this.shouldPersistMemoryForContext(oc);
+    const persistQueue = shouldPersistMemory ? this.getMemoryPersistQueue(oc) : null;
     const conversationPersistence = this.getConversationPersistenceOptionsForContext(oc);
     return async (event) => {
       const { shouldFlushForToolCompletion, bailedResult } = this.processStepContent(oc, event);
@@ -34788,7 +34811,7 @@ ${retrieverContext}`;
           awaitPersistence: shouldFlushStepPersistence
         });
       }
-      if (conversationPersistence.mode === "step" && (hasResponseMessages || shouldFlushStepPersistence)) {
+      if (shouldPersistMemory && persistQueue && conversationPersistence.mode === "step" && (hasResponseMessages || shouldFlushStepPersistence)) {
         try {
           if (shouldFlushStepPersistence) {
             await persistQueue.flush(buffer, oc);
@@ -35025,7 +35048,7 @@ ${retrieverContext}`;
       }
       recordTimestamp = (/* @__PURE__ */ new Date()).toISOString();
     });
-    if (stepRecords.length > 0 && oc.userId && oc.conversationId) {
+    if (this.shouldPersistMemoryForContext(oc) && stepRecords.length > 0 && oc.userId && oc.conversationId) {
       const persistStepsPromise = this.memoryManager.saveConversationSteps(oc, stepRecords, oc.userId, oc.conversationId).catch((error) => {
         oc.logger.debug("Failed to persist conversation steps", {
           error,
@@ -35730,7 +35753,8 @@ ${retrieverContext}`;
         const memoryBehaviorOverrides = resolvedMemory ? {
           ...resolvedMemory.contextLimit !== void 0 ? { contextLimit: resolvedMemory.contextLimit } : {},
           ...resolvedMemory.semanticMemory !== void 0 ? { semanticMemory: resolvedMemory.semanticMemory } : {},
-          ...resolvedMemory.conversationPersistence !== void 0 ? { conversationPersistence: resolvedMemory.conversationPersistence } : {}
+          ...resolvedMemory.conversationPersistence !== void 0 ? { conversationPersistence: resolvedMemory.conversationPersistence } : {},
+          ...resolvedMemory.readOnly !== void 0 ? { readOnly: resolvedMemory.readOnly } : {}
         } : void 0;
         const memory = resolvedMemory || options2?.conversationId || options2?.userId ? {
           conversationId: resolvedMemory?.conversationId ?? options2?.conversationId,
@@ -35780,6 +35804,7 @@ ${retrieverContext}`;
       return [];
     }
     const resolvedMemory = this.resolveMemoryRuntimeOptions(options, operationContext);
+    const isReadOnly = resolvedMemory.readOnly === true;
     const memoryManager = this.memoryManager;
     const memory = memoryManager.getMemory();
     if (!memory) {
@@ -35800,60 +35825,62 @@ ${retrieverContext}`;
         }, "execute")
       })
     );
-    const schema = memory.getWorkingMemorySchema();
-    const template = memory.getWorkingMemoryTemplate();
-    const baseParams = schema ? { content: schema } : { content: import_zod7.z.string().describe("The content to store in working memory") };
-    const modeParam = {
-      mode: import_zod7.z.enum(["replace", "append"]).default("append").describe(
-        "How to update: 'append' (default - safely merge with existing) or 'replace' (complete overwrite - DELETES other fields!)"
-      )
-    };
-    tools.push(
-      createTool({
-        name: "update_working_memory",
-        description: template ? `Update working memory. Default mode is 'append' which safely merges new data. Only use 'replace' if you want to COMPLETELY OVERWRITE all data. Current data is in <current_context>. Template: ${template}` : `Update working memory with important context. Default mode is 'append' which safely merges new data. Only use 'replace' if you want to COMPLETELY OVERWRITE all data. Current data is in <current_context>.`,
-        parameters: import_zod7.z.object({ ...baseParams, ...modeParam }),
-        execute: /* @__PURE__ */ __name(async ({ content, mode }, oc) => {
-          await memory.updateWorkingMemory({
-            conversationId: resolvedMemory.conversationId,
-            userId: resolvedMemory.userId,
-            content,
-            options: {
-              mode
+    if (!isReadOnly) {
+      const schema = memory.getWorkingMemorySchema();
+      const template = memory.getWorkingMemoryTemplate();
+      const baseParams = schema ? { content: schema } : { content: import_zod7.z.string().describe("The content to store in working memory") };
+      const modeParam = {
+        mode: import_zod7.z.enum(["replace", "append"]).default("append").describe(
+          "How to update: 'append' (default - safely merge with existing) or 'replace' (complete overwrite - DELETES other fields!)"
+        )
+      };
+      tools.push(
+        createTool({
+          name: "update_working_memory",
+          description: template ? `Update working memory. Default mode is 'append' which safely merges new data. Only use 'replace' if you want to COMPLETELY OVERWRITE all data. Current data is in <current_context>. Template: ${template}` : `Update working memory with important context. Default mode is 'append' which safely merges new data. Only use 'replace' if you want to COMPLETELY OVERWRITE all data. Current data is in <current_context>.`,
+          parameters: import_zod7.z.object({ ...baseParams, ...modeParam }),
+          execute: /* @__PURE__ */ __name(async ({ content, mode }, oc) => {
+            await memory.updateWorkingMemory({
+              conversationId: resolvedMemory.conversationId,
+              userId: resolvedMemory.userId,
+              content,
+              options: {
+                mode
+              }
+            });
+            if (oc?.traceContext) {
+              const finalContent = await memory.getWorkingMemory({
+                conversationId: resolvedMemory.conversationId,
+                userId: resolvedMemory.userId
+              });
+              const rootSpan = oc.traceContext.getRootSpan();
+              rootSpan.setAttribute("agent.workingMemory.finalContent", finalContent || "");
+              rootSpan.setAttribute("agent.workingMemory.lastUpdateTime", (/* @__PURE__ */ new Date()).toISOString());
             }
-          });
-          if (oc?.traceContext) {
-            const finalContent = await memory.getWorkingMemory({
+            return `Working memory ${mode === "replace" ? "replaced" : "updated (appended)"} successfully.`;
+          }, "execute")
+        })
+      );
+      tools.push(
+        createTool({
+          name: "clear_working_memory",
+          description: "Clear the working memory content",
+          parameters: import_zod7.z.object({}),
+          execute: /* @__PURE__ */ __name(async (_, oc) => {
+            await memory.clearWorkingMemory({
               conversationId: resolvedMemory.conversationId,
               userId: resolvedMemory.userId
             });
-            const rootSpan = oc.traceContext.getRootSpan();
-            rootSpan.setAttribute("agent.workingMemory.finalContent", finalContent || "");
-            rootSpan.setAttribute("agent.workingMemory.lastUpdateTime", (/* @__PURE__ */ new Date()).toISOString());
-          }
-          return `Working memory ${mode === "replace" ? "replaced" : "updated (appended)"} successfully.`;
-        }, "execute")
-      })
-    );
-    tools.push(
-      createTool({
-        name: "clear_working_memory",
-        description: "Clear the working memory content",
-        parameters: import_zod7.z.object({}),
-        execute: /* @__PURE__ */ __name(async (_, oc) => {
-          await memory.clearWorkingMemory({
-            conversationId: resolvedMemory.conversationId,
-            userId: resolvedMemory.userId
-          });
-          if (oc?.traceContext) {
-            const rootSpan = oc.traceContext.getRootSpan();
-            rootSpan.setAttribute("agent.workingMemory.finalContent", "");
-            rootSpan.setAttribute("agent.workingMemory.lastUpdateTime", (/* @__PURE__ */ new Date()).toISOString());
-          }
-          return "Working memory cleared.";
-        }, "execute")
-      })
-    );
+            if (oc?.traceContext) {
+              const rootSpan = oc.traceContext.getRootSpan();
+              rootSpan.setAttribute("agent.workingMemory.finalContent", "");
+              rootSpan.setAttribute("agent.workingMemory.lastUpdateTime", (/* @__PURE__ */ new Date()).toISOString());
+            }
+            return "Working memory cleared.";
+          }, "execute")
+        })
+      );
+    }
     return tools;
   }
 };