deepagents 1.8.0 → 1.8.1

package/dist/index.d.cts

@@ -1125,17 +1125,47 @@ declare function createSummarizationMiddleware(options: SummarizationMiddlewareO
 }, z$1.core.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]>;
 //#endregion
 //#region src/backends/store.d.ts
+/**
+ * Options for StoreBackend constructor.
+ */
+interface StoreBackendOptions {
+  /**
+   * Custom namespace for store operations.
+   *
+   * Determines where files are stored in the LangGraph store, enabling
+   * user-scoped, org-scoped, or any custom isolation pattern.
+   *
+   * If not provided, falls back to legacy behavior using assistantId from StateAndStore.
+   *
+   * @example
+   * ```typescript
+   * // User-scoped storage
+   * new StoreBackend(stateAndStore, {
+   *   namespace: ["memories", orgId, userId, "filesystem"],
+   * });
+   *
+   * // Org-scoped storage
+   * new StoreBackend(stateAndStore, {
+   *   namespace: ["memories", orgId, "filesystem"],
+   * });
+   * ```
+   */
+  namespace?: string[];
+}
 /**
  * Backend that stores files in LangGraph's BaseStore (persistent).
  *
  * Uses LangGraph's Store for persistent, cross-conversation storage.
  * Files are organized via namespaces and persist across all threads.
  *
- * The namespace can include an optional assistant_id for multi-agent isolation.
+ * The namespace can be customized via a factory function for flexible
+ * isolation patterns (user-scoped, org-scoped, etc.), or falls back
+ * to legacy assistant_id-based isolation.
  */
 declare class StoreBackend implements BackendProtocol {
   private stateAndStore;
-  constructor(stateAndStore: StateAndStore);
+  private _namespace;
+  constructor(stateAndStore: StateAndStore, options?: StoreBackendOptions);
   /**
    * Get the store instance.
    *
@@ -1146,9 +1176,11 @@ declare class StoreBackend implements BackendProtocol {
   /**
    * Get the namespace for store operations.
    *
-   * If an assistant_id is available in stateAndStore, return
-   * [assistant_id, "filesystem"] to provide per-assistant isolation.
-   * Otherwise return ["filesystem"].
+   * If a custom namespace was provided, returns it directly.
+   *
+   * Otherwise, falls back to legacy behavior:
+   * - If assistantId is set: [assistantId, "filesystem"]
+   * - Otherwise: ["filesystem"]
    */
   protected getNamespace(): string[];
   /**
@@ -1713,6 +1745,9 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
    *
    * Uses downloadFiles() to read, performs string replacement in TypeScript,
    * then uploadFiles() to write back. No runtime needed on the sandbox host.
+   *
+   * Memory-conscious: releases intermediate references early so the GC can
+   * reclaim buffers before the next large allocation is made.
    */
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
 }
@@ -2394,5 +2429,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1125,17 +1125,47 @@ declare function createSummarizationMiddleware(options: SummarizationMiddlewareO
 }, z$1.core.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]>;
 //#endregion
 //#region src/backends/store.d.ts
+/**
+ * Options for StoreBackend constructor.
+ */
+interface StoreBackendOptions {
+  /**
+   * Custom namespace for store operations.
+   *
+   * Determines where files are stored in the LangGraph store, enabling
+   * user-scoped, org-scoped, or any custom isolation pattern.
+   *
+   * If not provided, falls back to legacy behavior using assistantId from StateAndStore.
+   *
+   * @example
+   * ```typescript
+   * // User-scoped storage
+   * new StoreBackend(stateAndStore, {
+   *   namespace: ["memories", orgId, userId, "filesystem"],
+   * });
+   *
+   * // Org-scoped storage
+   * new StoreBackend(stateAndStore, {
+   *   namespace: ["memories", orgId, "filesystem"],
+   * });
+   * ```
+   */
+  namespace?: string[];
+}
 /**
  * Backend that stores files in LangGraph's BaseStore (persistent).
  *
  * Uses LangGraph's Store for persistent, cross-conversation storage.
  * Files are organized via namespaces and persist across all threads.
  *
- * The namespace can include an optional assistant_id for multi-agent isolation.
+ * The namespace can be customized via a factory function for flexible
+ * isolation patterns (user-scoped, org-scoped, etc.), or falls back
+ * to legacy assistant_id-based isolation.
  */
 declare class StoreBackend implements BackendProtocol {
   private stateAndStore;
-  constructor(stateAndStore: StateAndStore);
+  private _namespace;
+  constructor(stateAndStore: StateAndStore, options?: StoreBackendOptions);
   /**
    * Get the store instance.
    *
@@ -1146,9 +1176,11 @@ declare class StoreBackend implements BackendProtocol {
   /**
    * Get the namespace for store operations.
    *
-   * If an assistant_id is available in stateAndStore, return
-   * [assistant_id, "filesystem"] to provide per-assistant isolation.
-   * Otherwise return ["filesystem"].
+   * If a custom namespace was provided, returns it directly.
+   *
+   * Otherwise, falls back to legacy behavior:
+   * - If assistantId is set: [assistantId, "filesystem"]
+   * - Otherwise: ["filesystem"]
    */
   protected getNamespace(): string[];
   /**
@@ -1713,6 +1745,9 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
    *
    * Uses downloadFiles() to read, performs string replacement in TypeScript,
    * then uploadFiles() to write back. No runtime needed on the sandbox host.
+   *
+   * Memory-conscious: releases intermediate references early so the GC can
+   * reclaim buffers before the next large allocation is made.
    */
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
 }
@@ -2394,5 +2429,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1049,7 +1049,13 @@ function createFilesystemMiddleware(options = {}) {
 						message: new ToolMessage({
 							content: TOO_LARGE_TOOL_MSG.replace("{tool_call_id}", msg.tool_call_id).replace("{file_path}", evictPath).replace("{content_sample}", contentSample),
 							tool_call_id: msg.tool_call_id,
-							name: msg.name
+							name: msg.name,
+							id: msg.id,
+							artifact: msg.artifact,
+							status: msg.status,
+							metadata: msg.metadata,
+							additional_kwargs: msg.additional_kwargs,
+							response_metadata: msg.response_metadata
 						}),
 						filesUpdate: writeResult.filesUpdate
 					};
@@ -1327,16 +1333,28 @@ function filterStateForSubagent(state) {
 	return filtered;
 }
 /**
+* Invalid tool message block types
+*/
+const INVALID_TOOL_MESSAGE_BLOCK_TYPES = [
+	"tool_use",
+	"thinking",
+	"redacted_thinking"
+];
+/**
 * Create Command with filtered state update from subagent result
 */
 function returnCommandWithStateUpdate(result, toolCallId) {
 	const stateUpdate = filterStateForSubagent(result);
 	const messages = result.messages;
-	const lastMessage = messages?.[messages.length - 1];
+	let content = (messages?.[messages.length - 1])?.content || "Task completed";
+	if (Array.isArray(content)) {
+		content = content.filter((block) => !INVALID_TOOL_MESSAGE_BLOCK_TYPES.includes(block.type));
+		if (content.length === 0) content = "Task completed";
+	}
 	return new Command({ update: {
 		...stateUpdate,
 		messages: [new ToolMessage({
-			content: lastMessage?.content || "Task completed",
+			content,
 			tool_call_id: toolCallId,
 			name: "task"
 		})]
@@ -2658,31 +2676,44 @@ function createSummarizationMiddleware(options) {
 		return messages.filter((msg) => !isSummaryMessage(msg));
 	}
 	/**
-	* Offload messages to backend.
+	* Offload messages to backend by appending to the history file.
+	*
+	* Uses uploadFiles() directly with raw byte concatenation instead of
+	* edit() to avoid downloading the file twice and performing a full
+	* string search-and-replace. This keeps peak memory at ~2x file size
+	* (existing bytes + combined bytes) instead of ~6x with the old
+	* download → edit(oldContent, newContent) approach.
 	*/
 	async function offloadToBackend(resolvedBackend, messages, state) {
-		const path = getHistoryPath(state);
+		const filePath = getHistoryPath(state);
 		const filteredMessages = filterSummaryMessages(messages);
 		const newSection = `## Summarized at ${(/* @__PURE__ */ new Date()).toISOString()}\n\n${getBufferString(filteredMessages)}\n\n`;
-		let existingContent = "";
-		try {
-			if (resolvedBackend.downloadFiles) {
-				const responses = await resolvedBackend.downloadFiles([path]);
-				if (responses.length > 0 && responses[0].content && !responses[0].error) existingContent = new TextDecoder().decode(responses[0].content);
-			}
-		} catch {}
-		const combinedContent = existingContent + newSection;
+		const sectionBytes = new TextEncoder().encode(newSection);
 		try {
+			let existingBytes = null;
+			if (resolvedBackend.downloadFiles) try {
+				const responses = await resolvedBackend.downloadFiles([filePath]);
+				if (responses.length > 0 && responses[0].content && !responses[0].error) existingBytes = responses[0].content;
+			} catch {}
 			let result;
-			if (existingContent) result = await resolvedBackend.edit(path, existingContent, combinedContent);
-			else result = await resolvedBackend.write(path, combinedContent);
+			if (existingBytes && resolvedBackend.uploadFiles) {
+				const combined = new Uint8Array(existingBytes.byteLength + sectionBytes.byteLength);
+				combined.set(existingBytes, 0);
+				combined.set(sectionBytes, existingBytes.byteLength);
+				const uploadResults = await resolvedBackend.uploadFiles([[filePath, combined]]);
+				result = uploadResults[0].error ? { error: uploadResults[0].error } : { path: filePath };
+			} else if (!existingBytes) result = await resolvedBackend.write(filePath, newSection);
+			else {
+				const existingContent = new TextDecoder().decode(existingBytes);
+				result = await resolvedBackend.edit(filePath, existingContent, existingContent + newSection);
+			}
 			if (result.error) {
-				console.warn(`Failed to offload conversation history to ${path}: ${result.error}`);
+				console.warn(`Failed to offload conversation history to ${filePath}: ${result.error}`);
 				return null;
 			}
-			return path;
+			return filePath;
 		} catch (e) {
-			console.warn(`Exception offloading conversation history to ${path}:`, e);
+			console.warn(`Exception offloading conversation history to ${filePath}:`, e);
 			return null;
 		}
 	}
@@ -2872,18 +2903,43 @@ ${summary}
 
 //#endregion
 //#region src/backends/store.ts
+const NAMESPACE_COMPONENT_RE = /^[A-Za-z0-9\-_.@+:~]+$/;
+/**
+* Validate a namespace array.
+*
+* Each component must be a non-empty string containing only safe characters:
+* alphanumeric (a-z, A-Z, 0-9), hyphen (-), underscore (_), dot (.),
+* at sign (@), plus (+), colon (:), and tilde (~).
+*
+* Characters like *, ?, [, ], {, } etc. are rejected to prevent
+* wildcard or glob injection in store lookups.
+*/
+function validateNamespace(namespace) {
+	if (namespace.length === 0) throw new Error("Namespace array must not be empty.");
+	for (let i = 0; i < namespace.length; i++) {
+		const component = namespace[i];
+		if (typeof component !== "string") throw new TypeError(`Namespace component at index ${i} must be a string, got ${typeof component}.`);
+		if (!component) throw new Error(`Namespace component at index ${i} must not be empty.`);
+		if (!NAMESPACE_COMPONENT_RE.test(component)) throw new Error(`Namespace component at index ${i} contains disallowed characters: "${component}". Only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes are allowed.`);
+	}
+	return namespace;
+}
 /**
 * Backend that stores files in LangGraph's BaseStore (persistent).
 *
 * Uses LangGraph's Store for persistent, cross-conversation storage.
 * Files are organized via namespaces and persist across all threads.
 *
-* The namespace can include an optional assistant_id for multi-agent isolation.
+* The namespace can be customized via a factory function for flexible
+* isolation patterns (user-scoped, org-scoped, etc.), or falls back
+* to legacy assistant_id-based isolation.
 */
 var StoreBackend = class {
 	stateAndStore;
-	constructor(stateAndStore) {
+	_namespace;
+	constructor(stateAndStore, options) {
 		this.stateAndStore = stateAndStore;
+		if (options?.namespace) this._namespace = validateNamespace(options.namespace);
 	}
 	/**
 	* Get the store instance.
@@ -2899,15 +2955,17 @@ var StoreBackend = class {
 	/**
 	* Get the namespace for store operations.
 	*
-	* If an assistant_id is available in stateAndStore, return
-	* [assistant_id, "filesystem"] to provide per-assistant isolation.
-	* Otherwise return ["filesystem"].
+	* If a custom namespace was provided, returns it directly.
+	*
+	* Otherwise, falls back to legacy behavior:
+	* - If assistantId is set: [assistantId, "filesystem"]
+	* - Otherwise: ["filesystem"]
 	*/
 	getNamespace() {
-		const namespace = "filesystem";
+		if (this._namespace) return this._namespace;
 		const assistantId = this.stateAndStore.assistantId;
-		if (assistantId) return [assistantId, namespace];
-		return [namespace];
+		if (assistantId) return [assistantId, "filesystem"];
+		return ["filesystem"];
 	}
 	/**
 	* Convert a store Item to FileData format.
@@ -4567,17 +4625,85 @@ var BaseSandbox = class {
 	*
 	* Uses downloadFiles() to read, performs string replacement in TypeScript,
 	* then uploadFiles() to write back. No runtime needed on the sandbox host.
+	*
+	* Memory-conscious: releases intermediate references early so the GC can
+	* reclaim buffers before the next large allocation is made.
 	*/
 	async edit(filePath, oldString, newString, replaceAll = false) {
 		const results = await this.downloadFiles([filePath]);
 		if (results[0].error || !results[0].content) return { error: `Error: File '${filePath}' not found` };
 		const text = new TextDecoder().decode(results[0].content);
-		const count = text.split(oldString).length - 1;
-		if (count === 0) return { error: `String not found in file '${filePath}'` };
-		if (count > 1 && !replaceAll) return { error: `Multiple occurrences found in '${filePath}'. Use replaceAll=true to replace all.` };
-		const newText = replaceAll ? text.split(oldString).join(newString) : text.replace(oldString, newString);
-		const encoder = new TextEncoder();
-		const uploadResults = await this.uploadFiles([[filePath, encoder.encode(newText)]]);
+		results[0].content = null;
+		/**
+		* are we editing an empty file?
+		*/
+		if (oldString.length === 0) {
+			/**
+			* if the file is not empty, we cannot edit it with an empty oldString
+			*/
+			if (text.length !== 0) return { error: "oldString must not be empty unless the file is empty" };
+			/**
+			* if the newString is empty, we can just return the file as is
+			*/
+			if (newString.length === 0) return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences: 0
+			};
+			/**
+			* if the newString is not empty, we can edit the file
+			*/
+			const encoded = new TextEncoder().encode(newString);
+			const uploadResults = await this.uploadFiles([[filePath, encoded]]);
+			/**
+			* if the upload fails, we return an error
+			*/
+			if (uploadResults[0].error) return { error: `Failed to write edited file '${filePath}': ${uploadResults[0].error}` };
+			return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences: 1
+			};
+		}
+		const firstIdx = text.indexOf(oldString);
+		if (firstIdx === -1) return { error: `String not found in file '${filePath}'` };
+		if (oldString === newString) return {
+			path: filePath,
+			filesUpdate: null,
+			occurrences: 1
+		};
+		let newText;
+		let count;
+		if (replaceAll) {
+			newText = text.replaceAll(oldString, newString);
+			/**
+			* Derive count from the length delta to avoid a separate O(n) counting pass
+			*/
+			const lenDiff = oldString.length - newString.length;
+			if (lenDiff !== 0) count = (text.length - newText.length) / lenDiff;
+			else {
+				/**
+				* Lengths are equal — count via indexOf (we already found the first)
+				*/
+				count = 1;
+				let pos = firstIdx + oldString.length;
+				while (pos <= text.length) {
+					const idx = text.indexOf(oldString, pos);
+					if (idx === -1) break;
+					count++;
+					pos = idx + oldString.length;
+				}
+			}
+		} else {
+			if (text.indexOf(oldString, firstIdx + oldString.length) !== -1) return { error: `Multiple occurrences found in '${filePath}'. Use replaceAll=true to replace all.` };
+			count = 1;
+			/**
+			* Build result from the known index — avoids a redundant search by .replace()
+			*/
+			newText = text.slice(0, firstIdx) + newString + text.slice(firstIdx + oldString.length);
+		}
+		const encoded = new TextEncoder().encode(newText);
+		const uploadResults = await this.uploadFiles([[filePath, encoded]]);
 		if (uploadResults[0].error) return { error: `Failed to write edited file '${filePath}': ${uploadResults[0].error}` };
 		return {
 			path: filePath,