@langchain/sandbox-standard-tests 0.0.3

package/dist/sandbox-C22TOwhI.cjs

@@ -0,0 +1,1169 @@
+
+//#region src/tests/lifecycle.ts
+/**
+* Register sandbox lifecycle tests (create, isRunning, close, two-step init).
+*
+* These tests use both the shared sandbox (for id/isRunning checks) and
+* temporary sandboxes (for close and two-step initialization).
+*/
+function registerLifecycleTests(getShared, config, timeout) {
+	const { describe, it, expect, beforeAll, afterAll } = config.runner;
+	const describeSkipIf = describe.skipIf ?? ((condition) => condition ? describe.skip ?? (() => {}) : describe);
+	const itSkipIf = it.skipIf ?? ((condition) => condition ? () => {} : it);
+	describe("sandbox lifecycle", () => {
+		it("should create sandbox and have a valid id", () => {
+			const shared = getShared();
+			expect(shared).toBeDefined();
+			expect(shared.id).toBeDefined();
+			expect(typeof shared.id).toBe("string");
+			expect(shared.id.length).toBeGreaterThan(0);
+		}, timeout);
+		it("should have isRunning as true after creation", () => {
+			expect(getShared().isRunning).toBe(true);
+		}, timeout);
+		describeSkipIf(!(typeof config.closeSandbox === "function"))("close", () => {
+			let tmp;
+			beforeAll(async () => {
+				tmp = await withRetry(() => config.createSandbox());
+			}, timeout);
+			afterAll(async () => {
+				try {
+					await config.closeSandbox?.(tmp);
+				} catch {}
+			}, timeout);
+			it("should close sandbox successfully", async () => {
+				expect(tmp.isRunning).toBe(true);
+				await config.closeSandbox?.(tmp);
+				expect(tmp.isRunning).toBe(false);
+			}, timeout);
+		});
+		describe("two-step initialization", () => {
+			let tmp;
+			afterAll(async () => {
+				try {
+					if (tmp) await config.closeSandbox?.(tmp);
+				} catch {}
+			}, timeout);
+			itSkipIf(!config.createUninitializedSandbox)("should work with two-step initialization", async () => {
+				tmp = config.createUninitializedSandbox();
+				expect(tmp.isRunning).toBe(false);
+				await withRetry(() => tmp.initialize());
+				expect(tmp.isRunning).toBe(true);
+				expect(tmp.id).toBeDefined();
+			}, timeout);
+		});
+	});
+}
+
+//#endregion
+//#region src/tests/command-execution.ts
+/**
+* Register command execution tests (echo, exit codes, multiline, stderr, env vars).
+*/
+function registerCommandExecutionTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("command execution", () => {
+		it("should run a simple echo command", async () => {
+			const result = await getShared().execute("echo \"hello\"");
+			expect(result.exitCode).toBe(0);
+			expect(result.output.trim()).toBe("hello");
+			expect(result.truncated).toBe(false);
+		}, timeout);
+		it("should capture non-zero exit code", async () => {
+			expect((await getShared().execute("exit 42")).exitCode).toBe(42);
+		}, timeout);
+		it("should capture multiline output", async () => {
+			const result = await getShared().execute("echo \"line1\" && echo \"line2\" && echo \"line3\"");
+			expect(result.exitCode).toBe(0);
+			expect(result.output).toContain("line1");
+			expect(result.output).toContain("line2");
+			expect(result.output).toContain("line3");
+		}, timeout);
+		it("should capture stderr output", async () => {
+			expect((await getShared().execute("echo \"error message\" >&2")).output).toContain("error message");
+		}, timeout);
+		it("should handle command with environment variables", async () => {
+			const result = await getShared().execute("export MY_VAR=\"test_value\" && echo $MY_VAR");
+			expect(result.exitCode).toBe(0);
+			expect(result.output.trim()).toBe("test_value");
+		}, timeout);
+		it("should handle non-existent command", async () => {
+			expect((await getShared().execute("nonexistent_command_12345")).exitCode).not.toBe(0);
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/file-operations.ts
+/**
+* Register basic file operation tests (upload, download, read, write, edit, multiple files).
+*/
+function registerFileOperationTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("file operations", () => {
+		it("should upload files to sandbox", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("test-upload.txt");
+			const content = new TextEncoder().encode("Hello from test file!");
+			const results = await shared.uploadFiles([[filePath, content]]);
+			expect(results.length).toBe(1);
+			expect(results[0].path).toBe(filePath);
+			expect(results[0].error).toBeNull();
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe("Hello from test file!");
+		}, timeout);
+		it("should download files from sandbox", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("test-download.txt");
+			const encoder = new TextEncoder();
+			await shared.uploadFiles([[filePath, encoder.encode("Download test content")]]);
+			const results = await shared.downloadFiles([filePath]);
+			expect(results.length).toBe(1);
+			expect(results[0].error).toBeNull();
+			expect(results[0].content).not.toBeNull();
+			expect(new TextDecoder().decode(results[0].content).trim()).toBe("Download test content");
+		}, timeout);
+		it("should handle file not found on download", async () => {
+			const filePath = config.resolvePath("nonexistent-file-12345.txt");
+			const results = await getShared().downloadFiles([filePath]);
+			expect(results.length).toBe(1);
+			expect(results[0].content).toBeNull();
+			expect(results[0].error).toBe("file_not_found");
+		}, timeout);
+		it("should use inherited read method from BaseSandbox", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("read-test.txt");
+			const encoder = new TextEncoder();
+			await shared.uploadFiles([[filePath, encoder.encode("Read test content")]]);
+			expect(await shared.read(filePath)).toContain("Read test content");
+		}, timeout);
+		it("should use inherited write method from BaseSandbox", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("write-test.txt");
+			await shared.write(filePath, "Written via BaseSandbox");
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe("Written via BaseSandbox");
+		}, timeout);
+		it("should use inherited edit method from BaseSandbox", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("edit-test.txt");
+			await shared.write(filePath, "Hello World");
+			await shared.edit(filePath, "Hello World", "Hello Edited World");
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe("Hello Edited World");
+		}, timeout);
+		it("should upload multiple files at once", async () => {
+			const shared = getShared();
+			const path1 = config.resolvePath("multi1.txt");
+			const path2 = config.resolvePath("multi2.txt");
+			const path3 = config.resolvePath("multi3.txt");
+			const encoder = new TextEncoder();
+			const results = await shared.uploadFiles([
+				[path1, encoder.encode("Content 1")],
+				[path2, encoder.encode("Content 2")],
+				[path3, encoder.encode("Content 3")]
+			]);
+			expect(results.length).toBe(3);
+			expect(results.every((r) => r.error === null)).toBe(true);
+			const checkResult = await shared.execute(`cat ${path1} ${path2} ${path3}`);
+			expect(checkResult.output).toContain("Content 1");
+			expect(checkResult.output).toContain("Content 2");
+			expect(checkResult.output).toContain("Content 3");
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/write.ts
+/**
+* Register detailed write() tests (new file, parent dirs, existing file,
+* special chars, empty, spaces, unicode, slashes, long content, newlines).
+*/
+function registerWriteTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("write", () => {
+		it("should write a new file with basic content", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-new.txt");
+			const content = "Hello, sandbox!\nLine 2\nLine 3";
+			const result = await shared.write(filePath, content);
+			expect(result.error).toBeUndefined();
+			expect(result.path).toBe(filePath);
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe(content);
+		}, timeout);
+		it("should create parent directories automatically", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-parents/deep/nested/dir/file.txt");
+			const content = "Nested file content";
+			expect((await shared.write(filePath, content)).error).toBeUndefined();
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe(content);
+		}, timeout);
+		it("should fail when writing to an existing file", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-existing.txt");
+			await shared.write(filePath, "First content");
+			const result = await shared.write(filePath, "Second content");
+			expect(result.error).toBeDefined();
+			expect(result.error.toLowerCase()).toContain("already exists");
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe("First content");
+		}, timeout);
+		it("should handle special characters and escape sequences", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-special.txt");
+			const content = "Special chars: $VAR, `command`, $(subshell)\nTab	here\nBackslash: \\";
+			expect((await shared.write(filePath, content)).error).toBeUndefined();
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe(content);
+		}, timeout);
+		it("should write an empty file", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-empty.txt");
+			expect((await shared.write(filePath, "")).error).toBeUndefined();
+			expect((await shared.execute(`[ -f ${filePath} ] && echo 'exists' || echo 'missing'`)).output).toContain("exists");
+		}, timeout);
+		it("should write a file with spaces in the path", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-spaces/dir with spaces/file name.txt");
+			const content = "Content in file with spaces";
+			expect((await shared.write(filePath, content)).error).toBeUndefined();
+			expect((await shared.execute(`cat '${filePath}'`)).output.trim()).toBe(content);
+		}, timeout);
+		it("should write unicode content", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-unicode.txt");
+			const content = "Hello 👋 世界 مرحبا Привет 🌍\nLine with émojis 🎉";
+			expect((await shared.write(filePath, content)).error).toBeUndefined();
+			expect((await shared.execute(`cat ${filePath}`)).output.trim()).toBe(content);
+		}, timeout);
+		it("should handle consecutive slashes in path", async () => {
+			const shared = getShared();
+			const basePath = config.resolvePath("wt-slashes");
+			const filePath = `${basePath}//subdir///file.txt`;
+			const content = "Content";
+			expect((await shared.write(filePath, content)).error).toBeUndefined();
+			expect((await shared.execute(`cat ${basePath}/subdir/file.txt`)).output.trim()).toBe(content);
+		}, timeout);
+		it("should write very long content (1000 lines)", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-long.txt");
+			const content = Array.from({ length: 1e3 }, (_, i) => `Line ${i} with some content here`).join("\n");
+			expect((await shared.write(filePath, content)).error).toBeUndefined();
+			expect((await shared.execute(`wc -l < ${filePath}`)).output.trim()).toMatch(/^(999|1000)$/);
+		}, timeout);
+		it("should write content with only newlines", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("wt-newlines.txt");
+			expect((await shared.write(filePath, "\n\n\n\n\n")).error).toBeUndefined();
+			expect((await shared.execute(`wc -l < ${filePath}`)).output.trim()).toBe("5");
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/read.ts
+/**
+* Register detailed read() tests (basic, nonexistent, empty, offset, limit,
+* offset+limit, unicode, long lines, zero limit, offset beyond, chunked).
+*/
+function registerReadTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("read", () => {
+		it("should read a file with line numbers", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-basic.txt");
+			await shared.write(filePath, "Line 1\nLine 2\nLine 3");
+			const result = await shared.read(filePath);
+			expect(result).not.toContain("Error:");
+			expect(result).toContain("Line 1");
+			expect(result).toContain("Line 2");
+			expect(result).toContain("Line 3");
+		}, timeout);
+		it("should return error for nonexistent file", async () => {
+			const filePath = config.resolvePath("rd-nonexistent-xyz.txt");
+			const result = await getShared().read(filePath);
+			expect(result).toContain("Error:");
+			expect(result.toLowerCase()).toContain("not found");
+		}, timeout);
+		it("should handle reading an empty file", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-empty.txt");
+			await shared.write(filePath, "");
+			expect((await shared.read(filePath)).toLowerCase()).not.toContain("error:");
+		}, timeout);
+		it("should read with offset parameter", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-offset.txt");
+			const content = Array.from({ length: 10 }, (_, i) => `Row_${i + 1}_content`).join("\n");
+			await shared.write(filePath, content);
+			const result = await shared.read(filePath, 5);
+			expect(result).toContain("Row_6_content");
+			expect(result).not.toContain("Row_1_content");
+		}, timeout);
+		it("should read with limit parameter", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-limit.txt");
+			const content = Array.from({ length: 100 }, (_, i) => `Row_${i + 1}_content`).join("\n");
+			await shared.write(filePath, content);
+			const result = await shared.read(filePath, 0, 5);
+			expect(result).toContain("Row_1_content");
+			expect(result).toContain("Row_5_content");
+			expect(result).not.toContain("Row_6_content");
+		}, timeout);
+		it("should read with both offset and limit", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-offset-limit.txt");
+			const content = Array.from({ length: 20 }, (_, i) => `Row_${i + 1}_content`).join("\n");
+			await shared.write(filePath, content);
+			const result = await shared.read(filePath, 10, 5);
+			expect(result).toContain("Row_11_content");
+			expect(result).toContain("Row_15_content");
+			expect(result).not.toContain("Row_10_content");
+			expect(result).not.toContain("Row_16_content");
+		}, timeout);
+		it("should read unicode content", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-unicode.txt");
+			await shared.write(filePath, "Hello 👋 世界\nПривет мир\nمرحبا العالم");
+			const result = await shared.read(filePath);
+			expect(result).not.toContain("Error:");
+			expect(result).toContain("👋");
+			expect(result).toContain("世界");
+			expect(result).toContain("Привет");
+		}, timeout);
+		it("should handle files with very long lines", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-long-lines.txt");
+			const content = `Short line\n${"x".repeat(3e3)}\nAnother short line`;
+			await shared.write(filePath, content);
+			const result = await shared.read(filePath);
+			expect(result).not.toContain("Error:");
+			expect(result).toContain("Short line");
+		}, timeout);
+		it("should return nothing with limit=0", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-zero-limit.txt");
+			await shared.write(filePath, "Line 1\nLine 2\nLine 3");
+			expect(await shared.read(filePath, 0, 0)).not.toContain("Line 1");
+		}, timeout);
+		it("should handle offset beyond file length", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-offset-beyond.txt");
+			await shared.write(filePath, "Line 1\nLine 2\nLine 3");
+			const result = await shared.read(filePath, 100, 10);
+			expect(result).not.toContain("Line 1");
+			expect(result).not.toContain("Line 2");
+			expect(result).not.toContain("Line 3");
+		}, timeout);
+		it("should handle offset exactly at file length", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-offset-exact.txt");
+			const content = Array.from({ length: 5 }, (_, i) => `Line ${i + 1}`).join("\n");
+			await shared.write(filePath, content);
+			const result = await shared.read(filePath, 5, 10);
+			expect(result).not.toContain("Line 1");
+			expect(result).not.toContain("Line 5");
+		}, timeout);
+		it("should read a large file in chunks", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("rd-chunked.txt");
+			const content = Array.from({ length: 1e3 }, (_, i) => `Line_${String(i).padStart(4, "0")}_content`).join("\n");
+			await shared.write(filePath, content);
+			const chunk1 = await shared.read(filePath, 0, 100);
+			expect(chunk1).toContain("Line_0000_content");
+			expect(chunk1).toContain("Line_0099_content");
+			expect(chunk1).not.toContain("Line_0100_content");
+			const chunk2 = await shared.read(filePath, 500, 100);
+			expect(chunk2).toContain("Line_0500_content");
+			expect(chunk2).toContain("Line_0599_content");
+			expect(chunk2).not.toContain("Line_0499_content");
+			const chunk3 = await shared.read(filePath, 900, 100);
+			expect(chunk3).toContain("Line_0900_content");
+			expect(chunk3).toContain("Line_0999_content");
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/edit.ts
+/**
+* Register detailed edit() tests (single/multi occurrence, replaceAll,
+* not found, special chars, multiline, delete, identical, unicode,
+* whitespace, long strings, line endings, partial match).
+*/
+function registerEditTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("edit", () => {
+		it("should edit a single occurrence", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-single.txt");
+			await shared.write(filePath, "Hello world\nGoodbye world\nHello again");
+			const result = await shared.edit(filePath, "Goodbye", "Farewell");
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			const content = await shared.read(filePath);
+			expect(content).toContain("Farewell world");
+			expect(content).not.toContain("Goodbye");
+		}, timeout);
+		it("should fail with multiple occurrences without replaceAll", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-multi-fail.txt");
+			await shared.write(filePath, "apple\nbanana\napple\norange\napple");
+			const result = await shared.edit(filePath, "apple", "pear", false);
+			expect(result.error).toBeDefined();
+			expect(result.error.toLowerCase()).toContain("multiple");
+			const content = await shared.read(filePath);
+			expect(content).toContain("apple");
+			expect(content).not.toContain("pear");
+		}, timeout);
+		it("should replace all occurrences with replaceAll=true", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-replace-all.txt");
+			await shared.write(filePath, "apple\nbanana\napple\norange\napple");
+			const result = await shared.edit(filePath, "apple", "pear", true);
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(3);
+			const execResult = await shared.execute(`cat ${filePath}`);
+			expect(execResult.output).not.toContain("apple");
+			expect(execResult.output.split("pear").length - 1).toBe(3);
+		}, timeout);
+		it("should return error when string is not found", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-not-found.txt");
+			await shared.write(filePath, "Hello world");
+			const result = await shared.edit(filePath, "nonexistent", "replacement");
+			expect(result.error).toBeDefined();
+			expect(result.error.toLowerCase()).toContain("not found");
+		}, timeout);
+		it("should return error for nonexistent file", async () => {
+			const filePath = config.resolvePath("ed-nonexistent-xyz.txt");
+			const result = await getShared().edit(filePath, "old", "new");
+			expect(result.error).toBeDefined();
+			expect(result.error.toLowerCase()).toContain("not found");
+		}, timeout);
+		it("should handle special characters and regex metacharacters", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-special.txt");
+			await shared.write(filePath, "Price: $100.00\nPattern: [a-z]*\nPath: /usr/bin");
+			expect((await shared.edit(filePath, "$100.00", "$200.00")).error).toBeUndefined();
+			expect((await shared.edit(filePath, "[a-z]*", "[0-9]+")).error).toBeUndefined();
+			const content = await shared.read(filePath);
+			expect(content).toContain("$200.00");
+			expect(content).toContain("[0-9]+");
+		}, timeout);
+		it("should handle multiline string replacement", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-multiline.txt");
+			await shared.write(filePath, "Line 1\nLine 2\nLine 3");
+			const result = await shared.edit(filePath, "Line 1\nLine 2", "Combined");
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			const content = await shared.read(filePath);
+			expect(content).toContain("Combined");
+			expect(content).toContain("Line 3");
+			expect(content).not.toContain("Line 1");
+		}, timeout);
+		it("should delete content by replacing with empty string", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-delete.txt");
+			await shared.write(filePath, "Keep this\nDelete this part\nKeep this too");
+			const result = await shared.edit(filePath, "Delete this part\n", "");
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			const content = await shared.read(filePath);
+			expect(content).toContain("Keep this");
+			expect(content).toContain("Keep this too");
+			expect(content).not.toContain("Delete this part");
+		}, timeout);
+		it("should handle identical old and new strings", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-identical.txt");
+			await shared.write(filePath, "Same text");
+			const result = await shared.edit(filePath, "Same text", "Same text");
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			expect(await shared.read(filePath)).toContain("Same text");
+		}, timeout);
+		it("should handle unicode content", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-unicode.txt");
+			await shared.write(filePath, "Hello 👋 world\n世界 is beautiful");
+			const result = await shared.edit(filePath, "👋", "🌍");
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			const content = await shared.read(filePath);
+			expect(content).toContain("🌍");
+			expect(content).not.toContain("👋");
+		}, timeout);
+		it("should handle whitespace-only strings", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-whitespace.txt");
+			await shared.write(filePath, "Line1    Line2");
+			const result = await shared.edit(filePath, "    ", " ");
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			expect(await shared.read(filePath)).toContain("Line1 Line2");
+		}, timeout);
+		it("should handle very long old and new strings", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-long.txt");
+			const oldString = "x".repeat(1e3);
+			const newString = "y".repeat(1e3);
+			await shared.write(filePath, `Start\n${oldString}\nEnd`);
+			const result = await shared.edit(filePath, oldString, newString);
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			const content = await shared.read(filePath);
+			expect(content).toContain("y".repeat(100));
+			expect(content).not.toContain("x".repeat(100));
+		}, timeout);
+		it("should preserve line endings correctly", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-line-endings.txt");
+			await shared.write(filePath, "Line 1\nLine 2\nLine 3\n");
+			expect((await shared.edit(filePath, "Line 2", "Modified Line 2")).error).toBeUndefined();
+			const content = await shared.read(filePath);
+			expect(content).toContain("Line 1");
+			expect(content).toContain("Modified Line 2");
+			expect(content).toContain("Line 3");
+		}, timeout);
+		it("should edit a substring within a line", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("ed-partial.txt");
+			await shared.write(filePath, "The quick brown fox jumps over the lazy dog");
+			const result = await shared.edit(filePath, "brown fox", "red cat");
+			expect(result.error).toBeUndefined();
+			expect(result.occurrences).toBe(1);
+			expect((await shared.execute(`cat ${filePath}`)).output).toContain("The quick red cat jumps");
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/ls-info.ts
+/**
+* Register lsInfo() tests (absolute paths, files + subdirs, empty dir,
+* nonexistent dir, hidden files, spaces, unicode, large dir, trailing slash,
+* special characters).
+*/
+function registerLsInfoTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("lsInfo", () => {
+		it("should return absolute paths", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-absolute");
+			await shared.write(`${baseDir}/file.txt`, "content");
+			const result = await shared.lsInfo(baseDir);
+			expect(result.length).toBe(1);
+			expect(result[0].path).toBe(`${baseDir}/file.txt`);
+		}, timeout);
+		it("should list files and subdirectories", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-basic");
+			await shared.write(`${baseDir}/file1.txt`, "content1");
+			await shared.write(`${baseDir}/file2.txt`, "content2");
+			await shared.execute(`mkdir -p '${baseDir}/subdir'`);
+			const result = await shared.lsInfo(baseDir);
+			expect(result.length).toBe(3);
+			const paths = result.map((info) => info.path.replace(/\/$/, ""));
+			expect(paths).toContain(`${baseDir}/file1.txt`);
+			expect(paths).toContain(`${baseDir}/file2.txt`);
+			expect(paths).toContain(`${baseDir}/subdir`);
+			for (const info of result) if (info.path.replace(/\/$/, "").endsWith("/subdir")) expect(info.is_dir).toBe(true);
+			else expect(info.is_dir).toBe(false);
+		}, timeout);
+		it("should return empty list for empty directory", async () => {
+			const shared = getShared();
+			const emptyDir = config.resolvePath("li-empty-dir");
+			await shared.execute(`mkdir -p '${emptyDir}'`);
+			expect(await shared.lsInfo(emptyDir)).toEqual([]);
+		}, timeout);
+		it("should return empty list for nonexistent directory", async () => {
+			const nonexistentDir = config.resolvePath("li-does-not-exist-12345");
+			expect(await getShared().lsInfo(nonexistentDir)).toEqual([]);
+		}, timeout);
+		it("should include hidden files", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-hidden");
+			await shared.write(`${baseDir}/.hidden`, "hidden content");
+			await shared.write(`${baseDir}/visible.txt`, "visible content");
+			const paths = (await shared.lsInfo(baseDir)).map((info) => info.path);
+			expect(paths).toContain(`${baseDir}/.hidden`);
+			expect(paths).toContain(`${baseDir}/visible.txt`);
+		}, timeout);
+		it("should handle directories with spaces in names", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-spaces");
+			await shared.write(`${baseDir}/file with spaces.txt`, "content");
+			await shared.execute(`mkdir -p '${baseDir}/dir with spaces'`);
+			const paths = (await shared.lsInfo(baseDir)).map((info) => info.path.replace(/\/$/, ""));
+			expect(paths).toContain(`${baseDir}/file with spaces.txt`);
+			expect(paths).toContain(`${baseDir}/dir with spaces`);
+		}, timeout);
+		it("should handle unicode filenames", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-unicode");
+			await shared.write(`${baseDir}/\u6D4B\u8BD5\u6587\u4EF6.txt`, "content");
+			await shared.write(`${baseDir}/\u0444\u0430\u0439\u043B.txt`, "content");
+			expect((await shared.lsInfo(baseDir)).length).toBe(2);
+		}, timeout);
+		it("should handle large directories", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-large");
+			await shared.execute(`mkdir -p '${baseDir}' && cd '${baseDir}' && for i in \$(seq 0 49); do echo 'content' > file_\$(printf '%03d' \$i).txt; done`);
+			const result = await shared.lsInfo(baseDir);
+			expect(result.length).toBe(50);
+			const paths = result.map((info) => info.path);
+			expect(paths).toContain(`${baseDir}/file_000.txt`);
+			expect(paths).toContain(`${baseDir}/file_049.txt`);
+		}, timeout);
+		it("should handle trailing slash in path", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-trailing");
+			await shared.write(`${baseDir}/file.txt`, "content");
+			expect((await shared.lsInfo(`${baseDir}/`)).length).toBeGreaterThanOrEqual(1);
+		}, timeout);
+		it("should handle special characters in filenames", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("li-special-chars");
+			await shared.write(`${baseDir}/file(1).txt`, "content");
+			await shared.write(`${baseDir}/file-3.txt`, "content");
+			const paths = (await shared.lsInfo(baseDir)).map((info) => info.path);
+			expect(paths).toContain(`${baseDir}/file(1).txt`);
+			expect(paths).toContain(`${baseDir}/file-3.txt`);
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/grep-raw.ts
+/**
+* Register grepRaw() tests (basic search, glob filter, no matches,
+* multi matches, literal matching, unicode, case sensitivity, special chars,
+* empty dir, nested dirs, line numbers).
+*/
+function registerGrepRawTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("grepRaw", () => {
+		it("should find basic literal pattern matches", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-basic");
+			await shared.write(`${baseDir}/file1.txt`, "Hello world\nGoodbye world");
+			await shared.write(`${baseDir}/file2.txt`, "Hello there\nGoodbye friend");
+			const result = await shared.grepRaw("Hello", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			const matches = result;
+			expect(matches.length).toBe(2);
+			const paths = matches.map((m) => m.path);
+			expect(paths.some((p) => p.includes("file1.txt"))).toBe(true);
+			expect(paths.some((p) => p.includes("file2.txt"))).toBe(true);
+			for (const match of matches) {
+				expect(match.line).toBe(1);
+				expect(match.text).toContain("Hello");
+			}
+		}, timeout);
+		it("should filter files with glob pattern", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-glob");
+			await shared.write(`${baseDir}/test.txt`, "pattern_match");
+			await shared.write(`${baseDir}/test.py`, "pattern_match");
+			await shared.write(`${baseDir}/test.md`, "pattern_match");
+			const result = await shared.grepRaw("pattern_match", baseDir, "*.py");
+			expect(Array.isArray(result)).toBe(true);
+			const matches = result;
+			expect(matches.length).toBe(1);
+			expect(matches[0].path).toContain("test.py");
+		}, timeout);
+		it("should return empty array when no matches found", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-no-match");
+			await shared.write(`${baseDir}/file.txt`, "Hello world");
+			const result = await shared.grepRaw("nonexistent_str", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			expect(result.length).toBe(0);
+		}, timeout);
+		it("should find multiple matches in a single file", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-multi");
+			await shared.write(`${baseDir}/fruits.txt`, "apple\nbanana\napple\norange\napple");
+			const result = await shared.grepRaw("apple", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			const matches = result;
+			expect(matches.length).toBe(3);
+			expect(matches.map((m) => m.line)).toEqual([
+				1,
+				3,
+				5
+			]);
+		}, timeout);
+		it("should match literal strings not regex", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-literal");
+			await shared.write(`${baseDir}/numbers.txt`, "test123\ntest456\nabcdef");
+			const result = await shared.grepRaw("test123", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			const matches = result;
+			expect(matches.length).toBe(1);
+			expect(matches[0].text).toContain("test123");
+		}, timeout);
+		it("should find unicode patterns", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-unicode");
+			await shared.write(`${baseDir}/unicode.txt`, "Hello 世界\nПривет мир\n测试 pattern");
+			const result = await shared.grepRaw("世界", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			const matches = result;
+			expect(matches.length).toBe(1);
+			expect(matches[0].text).toContain("世界");
+		}, timeout);
+		it("should be case-sensitive by default", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-case");
+			await shared.write(`${baseDir}/case.txt`, "Hello\nhello\nHELLO");
+			const result = await shared.grepRaw("Hello", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			const matches = result;
+			expect(matches.length).toBe(1);
+			expect(matches[0].text).toContain("Hello");
+		}, timeout);
+		it("should handle special characters as literals", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-special");
+			await shared.write(`${baseDir}/special.txt`, "Price: $100\nPath: /usr/bin\nPattern: [a-z]*");
+			const result1 = await shared.grepRaw("$100", baseDir);
+			expect(Array.isArray(result1)).toBe(true);
+			const matches1 = result1;
+			expect(matches1.length).toBe(1);
+			expect(matches1[0].text).toContain("$100");
+			const result2 = await shared.grepRaw("[a-z]*", baseDir);
+			expect(Array.isArray(result2)).toBe(true);
+			const matches2 = result2;
+			expect(matches2.length).toBe(1);
+			expect(matches2[0].text).toContain("[a-z]*");
+		}, timeout);
+		it("should return empty array for empty directory", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-empty-dir");
+			await shared.execute(`mkdir -p '${baseDir}'`);
+			const result = await shared.grepRaw("anything", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			expect(result.length).toBe(0);
+		}, timeout);
+		it("should search recursively across nested directories", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-nested");
+			await shared.write(`${baseDir}/root.txt`, "target_nested here");
+			await shared.write(`${baseDir}/sub1/level1.txt`, "target_nested here");
+			await shared.write(`${baseDir}/sub1/sub2/level2.txt`, "target_nested here");
+			const result = await shared.grepRaw("target_nested", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			expect(result.length).toBe(3);
+		}, timeout);
+		it("should report correct line numbers", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gr-line-nums");
+			const content = Array.from({ length: 100 }, (_, i) => `Line ${i + 1}`).join("\n");
+			await shared.write(`${baseDir}/long.txt`, content);
+			const result = await shared.grepRaw("Line 50", baseDir);
+			expect(Array.isArray(result)).toBe(true);
+			const matches = result;
+			expect(matches.length).toBe(1);
+			expect(matches[0].line).toBe(50);
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/glob-info.ts
+/**
+* Register globInfo() tests (wildcard, recursive, no matches, directories,
+* extension filter, hidden files, character classes, question mark,
+* multiple extensions, deeply nested).
+*/
+function registerGlobInfoTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("globInfo", () => {
+		it("should match basic wildcard pattern", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-basic");
+			await shared.write(`${baseDir}/file1.txt`, "content");
+			await shared.write(`${baseDir}/file2.txt`, "content");
+			await shared.write(`${baseDir}/file3.py`, "content");
+			const result = await shared.globInfo("*.txt", baseDir);
+			expect(result.length).toBe(2);
+			const paths = result.map((info) => info.path);
+			expect(paths).toContain("file1.txt");
+			expect(paths).toContain("file2.txt");
+			expect(paths.every((p) => !p.endsWith(".py"))).toBe(true);
+		}, timeout);
+		it("should match recursive pattern (**)", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-recursive");
+			await shared.write(`${baseDir}/root.txt`, "content");
+			await shared.write(`${baseDir}/subdir1/nested1.txt`, "content");
+			await shared.write(`${baseDir}/subdir2/nested2.txt`, "content");
+			const result = await shared.globInfo("**/*.txt", baseDir);
+			expect(result.length).toBeGreaterThanOrEqual(2);
+			const paths = result.map((info) => info.path);
+			expect(paths.some((p) => p.includes("nested1.txt"))).toBe(true);
+			expect(paths.some((p) => p.includes("nested2.txt"))).toBe(true);
+		}, timeout);
+		it("should return empty array when no matches", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-no-match");
+			await shared.write(`${baseDir}/file.txt`, "content");
+			expect(await shared.globInfo("*.py", baseDir)).toEqual([]);
+		}, timeout);
+		it("should include directories in results", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-dirs");
+			await shared.execute(`mkdir -p '${baseDir}/dir1' '${baseDir}/dir2'`);
+			await shared.write(`${baseDir}/file.txt`, "content");
+			const result = await shared.globInfo("*", baseDir);
+			expect(result.length).toBe(3);
+			const dirCount = result.filter((info) => info.is_dir).length;
+			const fileCount = result.filter((info) => !info.is_dir).length;
+			expect(dirCount).toBe(2);
+			expect(fileCount).toBe(1);
+		}, timeout);
+		it("should match specific file extensions", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-ext");
+			await shared.write(`${baseDir}/test.py`, "content");
+			await shared.write(`${baseDir}/test.txt`, "content");
+			await shared.write(`${baseDir}/test.md`, "content");
+			const result = await shared.globInfo("*.py", baseDir);
+			expect(result.length).toBe(1);
+			expect(result[0].path).toContain("test.py");
+		}, timeout);
+		it("should match hidden files explicitly", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-hidden");
+			await shared.write(`${baseDir}/.hidden1`, "content");
+			await shared.write(`${baseDir}/.hidden2`, "content");
+			await shared.write(`${baseDir}/visible.txt`, "content");
+			const paths = (await shared.globInfo(".*", baseDir)).map((info) => info.path);
+			expect(paths.some((p) => p.includes(".hidden1") || p.includes(".hidden2"))).toBe(true);
+			expect(paths.every((p) => !p.includes("visible"))).toBe(true);
+		}, timeout);
+		it("should match character class patterns", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-charclass");
+			await shared.write(`${baseDir}/file1.txt`, "content");
+			await shared.write(`${baseDir}/file2.txt`, "content");
+			await shared.write(`${baseDir}/file3.txt`, "content");
+			await shared.write(`${baseDir}/fileA.txt`, "content");
+			const result = await shared.globInfo("file[1-2].txt", baseDir);
+			expect(result.length).toBe(2);
+			const paths = result.map((info) => info.path);
+			expect(paths).toContain("file1.txt");
+			expect(paths).toContain("file2.txt");
+			expect(paths).not.toContain("file3.txt");
+			expect(paths).not.toContain("fileA.txt");
+		}, timeout);
+		it("should match single character wildcard (?)", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-question");
+			await shared.write(`${baseDir}/file1.txt`, "content");
+			await shared.write(`${baseDir}/file2.txt`, "content");
+			await shared.write(`${baseDir}/file10.txt`, "content");
+			const result = await shared.globInfo("file?.txt", baseDir);
+			expect(result.length).toBe(2);
+			expect(result.map((info) => info.path)).not.toContain("file10.txt");
+		}, timeout);
+		it("should match multiple extensions separately", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-multi-ext");
+			await shared.write(`${baseDir}/file.txt`, "content");
+			await shared.write(`${baseDir}/file.py`, "content");
+			await shared.write(`${baseDir}/file.md`, "content");
+			await shared.write(`${baseDir}/file.js`, "content");
+			const resultTxt = await shared.globInfo("*.txt", baseDir);
+			const resultPy = await shared.globInfo("*.py", baseDir);
+			expect(resultTxt.length).toBe(1);
+			expect(resultPy.length).toBe(1);
+		}, timeout);
+		it("should match deeply nested patterns", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("gl-deep");
+			await shared.write(`${baseDir}/a/b/c/d/deep.txt`, "content");
+			await shared.write(`${baseDir}/a/b/other.txt`, "content");
+			const result = await shared.globInfo("**/deep.txt", baseDir);
+			expect(result.length).toBeGreaterThanOrEqual(1);
+			expect(result.some((info) => info.path.includes("deep.txt"))).toBe(true);
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/initial-files.ts
+/**
+* Register initialFiles tests (basic, deeply nested, empty).
+*
+* These tests create temporary sandboxes and tear them down immediately.
+*/
+function registerInitialFilesTests(config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("initialFiles", () => {
+		it("should create sandbox with initial files", async () => {
+			const initPath = config.resolvePath("init-test.txt");
+			const nestedPath = config.resolvePath("nested/dir/file.txt");
+			const tmp = await withRetry(() => config.createSandbox({ initialFiles: {
+				[initPath]: "Hello from initial file!",
+				[nestedPath]: "Nested content"
+			} }));
+			try {
+				expect(tmp.isRunning).toBe(true);
+				const result1 = await tmp.execute(`cat ${initPath}`);
+				expect(result1.exitCode).toBe(0);
+				expect(result1.output.trim()).toBe("Hello from initial file!");
+				const result2 = await tmp.execute(`cat ${nestedPath}`);
+				expect(result2.exitCode).toBe(0);
+				expect(result2.output.trim()).toBe("Nested content");
+			} finally {
+				await config.closeSandbox?.(tmp);
+			}
+		}, timeout);
+		it("should create sandbox with deeply nested initial files", async () => {
+			const buttonPath = config.resolvePath("src/components/Button/index.tsx");
+			const helperPath = config.resolvePath("src/utils/helpers/string.ts");
+			const tmp = await withRetry(() => config.createSandbox({ initialFiles: {
+				[buttonPath]: "export const Button = () => <button>Click</button>;",
+				[helperPath]: "export const capitalize = (s: string) => s.toUpperCase();"
+			} }));
+			try {
+				expect(tmp.isRunning).toBe(true);
+				expect((await tmp.execute(`cat ${buttonPath}`)).output).toContain("Button");
+				expect((await tmp.execute(`cat ${helperPath}`)).output).toContain("capitalize");
+			} finally {
+				await config.closeSandbox?.(tmp);
+			}
+		}, timeout);
+		it("should create sandbox with empty initialFiles object", async () => {
+			const tmp = await withRetry(() => config.createSandbox({ initialFiles: {} }));
+			try {
+				expect(tmp.isRunning).toBe(true);
+				const result = await tmp.execute("echo \"Works!\"");
+				expect(result.exitCode).toBe(0);
+				expect(result.output).toContain("Works!");
+			} finally {
+				await config.closeSandbox?.(tmp);
+			}
+		}, timeout);
+		it("should make initialFiles accessible via read()", async () => {
+			const filePath = config.resolvePath("init-read-test.txt");
+			const tmp = await withRetry(() => config.createSandbox({ initialFiles: { [filePath]: "Content for read test" } }));
+			try {
+				expect(await tmp.read(filePath)).toContain("Content for read test");
+			} finally {
+				await config.closeSandbox?.(tmp);
+			}
+		}, timeout);
+		it("should make initialFiles accessible via downloadFiles()", async () => {
+			const filePath = config.resolvePath("init-download-test.txt");
+			const tmp = await withRetry(() => config.createSandbox({ initialFiles: { [filePath]: "Content for download test" } }));
+			try {
+				const results = await tmp.downloadFiles([filePath]);
+				expect(results[0].error).toBeNull();
+				expect(results[0].content).not.toBeNull();
+				expect(new TextDecoder().decode(results[0].content)).toContain("Content for download test");
+			} finally {
+				await config.closeSandbox?.(tmp);
+			}
+		}, timeout);
+		it("should execute a script created via initialFiles", async () => {
+			const scriptPath = config.resolvePath("init-script.sh");
+			const tmp = await withRetry(() => config.createSandbox({ initialFiles: { [scriptPath]: "#!/bin/sh\necho \"Hello from initialFiles script\"" } }));
+			try {
+				const result = await tmp.execute(`sh ${scriptPath}`);
+				expect(result.exitCode).toBe(0);
+				expect(result.output.trim()).toBe("Hello from initialFiles script");
+			} finally {
+				await config.closeSandbox?.(tmp);
+			}
+		}, timeout);
+		it("should make initialFiles in subdirectories visible via lsInfo()", async () => {
+			const dirPath = config.resolvePath("init-ls-dir");
+			const filePath = `${dirPath}/file.txt`;
+			const tmp = await withRetry(() => config.createSandbox({ initialFiles: { [filePath]: "ls test content" } }));
+			try {
+				expect((await tmp.lsInfo(dirPath)).map((e) => e.path.replace(/\/$/, ""))).toContain(filePath);
+			} finally {
+				await config.closeSandbox?.(tmp);
+			}
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/tests/integration.ts
+/**
+* Register integration workflow tests that combine multiple operations.
+*/
+function registerIntegrationTests(getShared, config, timeout) {
+	const { describe, it, expect } = config.runner;
+	describe("integration workflows", () => {
+		it("should complete a write-read-edit-read workflow", async () => {
+			const shared = getShared();
+			const filePath = config.resolvePath("intg-workflow.txt");
+			expect((await shared.write(filePath, "Original content")).error).toBeUndefined();
+			expect(await shared.read(filePath)).toContain("Original content");
+			expect((await shared.edit(filePath, "Original", "Modified")).error).toBeUndefined();
+			const updatedContent = await shared.read(filePath);
+			expect(updatedContent).toContain("Modified content");
+			expect(updatedContent).not.toContain("Original");
+		}, timeout);
+		it("should handle complex directory operations", async () => {
+			const shared = getShared();
+			const baseDir = config.resolvePath("intg-complex");
+			await shared.write(`${baseDir}/root.txt`, "root file");
+			await shared.write(`${baseDir}/subdir1/file1.txt`, "file 1");
+			await shared.write(`${baseDir}/subdir1/file2.py`, "file 2");
+			await shared.write(`${baseDir}/subdir2/file3.txt`, "file 3");
+			const lsPaths = (await shared.lsInfo(baseDir)).map((info) => info.path.replace(/\/$/, ""));
+			expect(lsPaths).toContain(`${baseDir}/root.txt`);
+			expect(lsPaths).toContain(`${baseDir}/subdir1`);
+			expect(lsPaths).toContain(`${baseDir}/subdir2`);
+			expect((await shared.globInfo("**/*.txt", baseDir)).length).toBe(3);
+			const grepResult = await shared.grepRaw("file", baseDir);
+			expect(Array.isArray(grepResult)).toBe(true);
+			expect(grepResult.length).toBeGreaterThanOrEqual(3);
+		}, timeout);
+	});
+}
+
+//#endregion
+//#region src/sandbox.ts
+/**
+* Standard integration test suite for sandbox providers.
+*
+* This module provides a reusable set of integration tests that verify
+* common sandbox behavior across all provider implementations. Each provider
+* calls `sandboxStandardTests()` with its own configuration to run these
+* tests against its sandbox implementation.
+*
+* **Design**: A single shared sandbox is created once (in `beforeAll`) and
+* reused across all command-execution and file-operation tests. Only
+* lifecycle tests that verify create/close behaviour and initialFiles tests
+* that require a fresh sandbox spin up a temporary instance — and they tear
+* it down immediately inside the test so the concurrent sandbox count never
+* exceeds 2.
+*
+* Tests cover:
+* - Sandbox lifecycle (create, isRunning, close, two-step initialization)
+* - Command execution (echo, exit codes, multiline output, stderr, env vars)
+* - File operations (upload, download, read, write, edit, multiple files)
+* - write() (new file, parent dirs, existing file, special chars, unicode, long content)
+* - read() (basic, nonexistent, offset, limit, offset+limit, unicode, chunked)
+* - edit() (single/multi occurrence, replaceAll, not found, special chars, multiline, unicode)
+* - lsInfo() (basic listing, empty dir, hidden files, large dir, absolute paths)
+* - grepRaw() (basic search, glob filter, case sensitivity, nested dirs, unicode)
+* - globInfo() (wildcard, recursive, extension filter, character classes, deeply nested)
+* - Initial files support (basic, nested, empty)
+* - Integration workflows (write-read-edit, complex directory operations)
+* - Error handling (file not found, non-existent command)
+*/
+/**
+* Default number of retry attempts for sandbox creation.
+*/
+const DEFAULT_MAX_RETRIES = 5;
+/**
+* Default delay in milliseconds between retries.
+*/
+const DEFAULT_RETRY_DELAY_MS = 15e3;
+/**
+* Retry an async operation with a fixed delay between attempts.
+*
+* Useful for working around transient sandbox concurrency limits:
+* when a provider rejects creation because the organisation has too
+* many running sandboxes, waiting a short while and retrying usually
+* succeeds once a previous sandbox finishes shutting down.
+*
+* @param fn - The async operation to attempt
+* @param maxRetries - Maximum number of attempts (default: 3)
+* @param delayMs - Milliseconds to wait between attempts (default: 10 000)
+* @returns The result of the first successful attempt
+*
+* @example
+* ```ts
+* const sandbox = await withRetry(() => DenoSandbox.create({ memoryMb: 768 }));
+* ```
+*/
+async function withRetry(fn, maxRetries = DEFAULT_MAX_RETRIES, delayMs = DEFAULT_RETRY_DELAY_MS) {
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt < maxRetries) await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+	throw lastError;
+}
+/**
+* Run the standard sandbox integration tests against a provider.
+*
+* A single shared sandbox is created in `beforeAll` and reused for the
+* majority of tests (command execution, file operations). Tests that
+* inherently need their own sandbox (lifecycle close/init, initialFiles)
+* create a temporary one and destroy it immediately, so the concurrent
+* sandbox count never exceeds **2** (shared + 1 temporary).
+*
+* @example
+* ```ts
+* import { sandboxStandardTests } from "@langchain/sandbox-standard-tests/vitest";
+* import { ModalSandbox } from "./sandbox.js";
+*
+* sandboxStandardTests({
+*   name: "ModalSandbox",
+*   skip: !process.env.MODAL_TOKEN_ID,
+*   timeout: 180_000,
+*   createSandbox: (opts) =>
+*     ModalSandbox.create({ imageName: "alpine:3.21", ...opts }),
+*   createUninitializedSandbox: () =>
+*     new ModalSandbox({ imageName: "alpine:3.21" }),
+*   closeSandbox: (sb) => sb.close(),
+*   resolvePath: (name) => `/tmp/${name}`,
+* });
+* ```
+*/
+function sandboxStandardTests(config) {
+	const { describe, beforeAll, afterAll } = config.runner;
+	const timeout = config.timeout ?? 12e4;
+	let outerDescribe;
+	if (config.skip) outerDescribe = describe.skip ?? (() => {});
+	else if (config.sequential) outerDescribe = describe.sequential ?? describe;
+	else outerDescribe = describe;
+	outerDescribe(`${config.name} Standard Tests`, () => {
+		let shared;
+		const getShared = () => shared;
+		beforeAll(async () => {
+			shared = await withRetry(() => config.createSandbox());
+		}, timeout);
+		afterAll(async () => {
+			try {
+				await config.closeSandbox?.(shared);
+			} catch {}
+		}, timeout);
+		registerLifecycleTests(getShared, config, timeout);
+		registerCommandExecutionTests(getShared, config, timeout);
+		registerFileOperationTests(getShared, config, timeout);
+		registerWriteTests(getShared, config, timeout);
+		registerReadTests(getShared, config, timeout);
+		registerEditTests(getShared, config, timeout);
+		registerLsInfoTests(getShared, config, timeout);
+		registerGrepRawTests(getShared, config, timeout);
+		registerGlobInfoTests(getShared, config, timeout);
+		registerInitialFilesTests(config, timeout);
+		registerIntegrationTests(getShared, config, timeout);
+	});
+}
+
+//#endregion
+Object.defineProperty(exports, 'sandboxStandardTests', {
+  enumerable: true,
+  get: function () {
+    return sandboxStandardTests;
+  }
+});
+Object.defineProperty(exports, 'withRetry', {
+  enumerable: true,
+  get: function () {
+    return withRetry;
+  }
+});
+//# sourceMappingURL=sandbox-C22TOwhI.cjs.map