@strands-agents/sdk 1.3.0 → 1.4.0

package/dist/src/sandbox/__tests__/posix-shell.test.node.js

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import { TestSandbox } from '../../__fixtures__/test-sandbox.node.js';
+import { streamProcess } from '../stream-process.js';
+const TEST_DIR = '/tmp/strands-test-shell-sandbox';
+describe.skipIf(process.platform === 'win32')('PosixShellSandbox', () => {
+    let sandbox;
+    beforeEach(() => {
+        fs.rmSync(TEST_DIR, { recursive: true, force: true });
+        fs.mkdirSync(TEST_DIR, { recursive: true });
+        sandbox = new TestSandbox(TEST_DIR);
+    });
+    afterEach(() => {
+        fs.rmSync(TEST_DIR, { recursive: true, force: true });
+    });
+    describe('execute (via shell commands)', () => {
+        it('runs a command', async () => {
+            const result = await sandbox.execute('echo hello');
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).toBe('hello\n');
+        });
+        it('runs in workingDir', async () => {
+            const result = await sandbox.execute('pwd');
+            expect(result.stdout.trim()).toContain('strands-test-shell-sandbox');
+        });
+        it('respects cwd option', async () => {
+            const result = await sandbox.execute('pwd', { cwd: '/tmp' });
+            expect(result.stdout.trim()).toMatch(/\/tmp$/);
+        });
+    });
+    describe('executeCode (via shell quoting)', () => {
+        it('runs python code through shell', async () => {
+            const result = await sandbox.executeCode('print(2 + 2)', 'python3');
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).toBe('4\n');
+        });
+        it('handles code with special characters', async () => {
+            const result = await sandbox.executeCode('print(\'hello "world"\')', 'python3');
+            expect(result.stdout).toBe('hello "world"\n');
+        });
+        it('handles code with single quotes', async () => {
+            const result = await sandbox.executeCode('print("it\'s working")', 'python3');
+            expect(result.stdout).toBe("it's working\n");
+        });
+    });
+    describe('language validation', () => {
+        it('rejects path traversal', async () => {
+            await expect(sandbox.executeCode('x', '../../../bin/sh')).rejects.toThrow('invalid characters');
+        });
+        it('rejects shell metacharacters', async () => {
+            await expect(sandbox.executeCode('x', 'python;rm -rf /')).rejects.toThrow('invalid characters');
+        });
+        it('rejects spaces', async () => {
+            await expect(sandbox.executeCode('x', 'python -c')).rejects.toThrow('invalid characters');
+        });
+        it('allows valid interpreters', async () => {
+            const result = await sandbox.executeCode('print("safe")', 'python3');
+            expect(result.exitCode).toBe(0);
+        });
+        it('allows dots and hyphens', async () => {
+            const result = await sandbox.executeCode('x', 'fake-lang.99');
+            expect(result.exitCode).toBe(127);
+        });
+    });
+    describe('read/write (via base64 encoding over shell)', () => {
+        it('text file roundtrip', async () => {
+            await sandbox.writeText('test.txt', 'hello shell');
+            const text = await sandbox.readText('test.txt');
+            expect(text).toBe('hello shell');
+        });
+        it('binary file roundtrip', async () => {
+            const bytes = new Uint8Array([0, 1, 2, 127, 128, 254, 255]);
+            await sandbox.writeFile('binary.bin', bytes);
+            const read = await sandbox.readFile('binary.bin');
+            expect(Array.from(read)).toStrictEqual(Array.from(bytes));
+        });
+        it('all 256 byte values roundtrip', async () => {
+            const bytes = new Uint8Array(256);
+            for (let i = 0; i < 256; i++)
+                bytes[i] = i;
+            await sandbox.writeFile('all-bytes.bin', bytes);
+            const read = await sandbox.readFile('all-bytes.bin');
+            expect(Array.from(read)).toStrictEqual(Array.from(bytes));
+        });
+        it('creates parent directories', async () => {
+            await sandbox.writeText('deep/nested/file.txt', 'deep');
+            const text = await sandbox.readText('deep/nested/file.txt');
+            expect(text).toBe('deep');
+        });
+        it('handles unicode content', async () => {
+            const content = '日本語 🚀 émojis';
+            await sandbox.writeText('unicode.txt', content);
+            const text = await sandbox.readText('unicode.txt');
+            expect(text).toBe(content);
+        });
+        it('handles shell metacharacters in content', async () => {
+            const content = '$(rm -rf /) `whoami` && || $HOME';
+            await sandbox.writeText('meta.txt', content);
+            const text = await sandbox.readText('meta.txt');
+            expect(text).toBe(content);
+        });
+        it('throws on nonexistent file', async () => {
+            await expect(sandbox.readFile('nope.txt')).rejects.toThrow();
+        });
+    });
+    describe('remove', () => {
+        it('removes a file', async () => {
+            await sandbox.writeText('delete-me.txt', 'bye');
+            await sandbox.removeFile('delete-me.txt');
+            await expect(sandbox.readFile('delete-me.txt')).rejects.toThrow();
+        });
+        it('throws on nonexistent file', async () => {
+            await expect(sandbox.removeFile('nope.txt')).rejects.toThrow();
+        });
+    });
+    describe('list (via ls -1ap parsing)', () => {
+        it('lists directory contents', async () => {
+            await sandbox.writeText('a.txt', 'a');
+            await sandbox.writeText('b.txt', 'b');
+            const files = await sandbox.listFiles('.');
+            const names = files.map((f) => f.name);
+            expect(names).toContain('a.txt');
+            expect(names).toContain('b.txt');
+        });
+        it('identifies directories', async () => {
+            await sandbox.execute('mkdir -p subdir');
+            const files = await sandbox.listFiles('.');
+            const subdir = files.find((f) => f.name === 'subdir');
+            expect(subdir?.isDir).toBe(true);
+        });
+        it('excludes . and .. entries', async () => {
+            await sandbox.writeText('file.txt', '');
+            const files = await sandbox.listFiles('.');
+            const names = files.map((f) => f.name);
+            expect(names).not.toContain('.');
+            expect(names).not.toContain('..');
+        });
+        it('throws on nonexistent directory', async () => {
+            await expect(sandbox.listFiles('/tmp/nonexistent-dir-xyz')).rejects.toThrow();
+        });
+        it('throws when path is a file, not a directory', async () => {
+            await sandbox.writeText('not-a-dir.txt', 'hello');
+            await expect(sandbox.listFiles('not-a-dir.txt')).rejects.toThrow();
+        });
+    });
+    describe('shellQuote', () => {
+        it('handles paths with spaces', async () => {
+            await sandbox.execute('mkdir -p "with spaces"');
+            await sandbox.writeText('with spaces/file.txt', 'spaced');
+            const text = await sandbox.readText('with spaces/file.txt');
+            expect(text).toBe('spaced');
+        });
+        it('handles paths with single quotes', async () => {
+            await sandbox.execute('mkdir -p "it\'s"');
+            await sandbox.writeText("it's/file.txt", 'quoted');
+            const text = await sandbox.readText("it's/file.txt");
+            expect(text).toBe('quoted');
+        });
+    });
+    describe('timeout', () => {
+        it('kills process on timeout', async () => {
+            const start = Date.now();
+            await expect(sandbox.execute('sleep 60', { timeout: 0.2 })).rejects.toThrow('timed out');
+            const elapsed = Date.now() - start;
+            expect(elapsed).toBeLessThan(2000);
+        });
+        it('does not timeout fast commands', async () => {
+            const result = await sandbox.execute('echo fast', { timeout: 5 });
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).toBe('fast\n');
+        });
+    });
+    describe('abort signal', () => {
+        it('kills process when signal is aborted', async () => {
+            const controller = new AbortController();
+            const promise = sandbox.execute('sleep 60', { signal: controller.signal });
+            setTimeout(() => controller.abort(), 100);
+            await expect(promise).rejects.toThrow('aborted');
+        });
+        it('rejects immediately if signal is already aborted', async () => {
+            const controller = new AbortController();
+            controller.abort();
+            await expect(sandbox.execute('sleep 60', { signal: controller.signal })).rejects.toThrow('aborted');
+        });
+    });
+    describe('concurrent execution', () => {
+        it('handles multiple concurrent commands', async () => {
+            const results = await Promise.all([
+                sandbox.execute('echo one'),
+                sandbox.execute('echo two'),
+                sandbox.execute('echo three'),
+            ]);
+            expect(results.map((r) => r.stdout.trim()).sort()).toStrictEqual(['one', 'three', 'two']);
+        });
+        it('handles concurrent file writes to different files', async () => {
+            await Promise.all([
+                sandbox.writeText('a.txt', 'aaa'),
+                sandbox.writeText('b.txt', 'bbb'),
+                sandbox.writeText('c.txt', 'ccc'),
+            ]);
+            const [a, b, c] = await Promise.all([
+                sandbox.readText('a.txt'),
+                sandbox.readText('b.txt'),
+                sandbox.readText('c.txt'),
+            ]);
+            expect(a).toBe('aaa');
+            expect(b).toBe('bbb');
+            expect(c).toBe('ccc');
+        });
+    });
+    describe('streaming', () => {
+        it('yields StreamChunks then ExecutionResult', async () => {
+            const chunks = [];
+            for await (const chunk of sandbox.executeStreaming('echo hello')) {
+                chunks.push(chunk);
+            }
+            const streamChunks = chunks.filter((c) => c.type === 'streamChunk');
+            const results = chunks.filter((c) => c.type === 'executionResult');
+            expect(streamChunks.length).toBeGreaterThan(0);
+            expect(results).toHaveLength(1);
+        });
+    });
+    describe('streamProcess edge cases', () => {
+        it('returns exit code 127 when command is not found', async () => {
+            const result = await sandbox.execute('nonexistent_binary_xyz_12345');
+            expect(result.exitCode).toBe(127);
+            expect(result.stderr).toContain('not found');
+        });
+        it('maps signal termination to 128 + signal number', async () => {
+            // sh -c 'kill -9 $$' sends SIGKILL to itself → exit code 128 + 9 = 137
+            const result = await sandbox.execute("sh -c 'kill -9 $$'");
+            expect(result.exitCode).toBe(137);
+        });
+        it('returns enoentMessage when spawned binary does not exist', async () => {
+            const chunks = [];
+            for await (const chunk of streamProcess('nonexistent_binary_xyz_12345', [], {
+                enoentMessage: 'binary not found',
+            })) {
+                chunks.push(chunk);
+            }
+            const result = chunks.find((c) => c.type === 'executionResult');
+            expect(result).toStrictEqual({
+                type: 'executionResult',
+                exitCode: 127,
+                stdout: '',
+                stderr: 'binary not found',
+                outputFiles: [],
+            });
+        });
+    });
+});
+//# sourceMappingURL=posix-shell.test.node.js.map

package/dist/src/sandbox/__tests__/posix-shell.test.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"posix-shell.test.node.js","sourceRoot":"","sources":["../../../../src/sandbox/__tests__/posix-shell.test.node.ts"],"names":[],"mappings":"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"}

package/dist/src/sandbox/base.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Base sandbox interface.
+ *
+ * Defines the abstract {@link Sandbox} class that all sandbox implementations
+ * must extend. The class provides six abstract operations (command execution,
+ * code execution, and file I/O) and convenience wrappers for common patterns.
+ */
+import type { ExecutionResult, FileInfo, StreamChunk } from './types.js';
+/**
+ * Options for command and code execution.
+ */
+export interface ExecuteOptions {
+    /** Maximum execution time in seconds. `undefined` means no timeout. */
+    timeout?: number | undefined;
+    /** Working directory for execution. `undefined` means use the sandbox default. */
+    cwd?: string | undefined;
+    /** Abort signal to cancel execution. The process is killed when the signal fires. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Abstract execution environment.
+ *
+ * A Sandbox provides the runtime context where tools execute code,
+ * run commands, and interact with a filesystem. Multiple tools share
+ * the same Sandbox instance, giving them a common working directory
+ * and filesystem.
+ *
+ * Streaming methods (`executeStreaming`, `executeCodeStreaming`) are the abstract primitives.
+ * Non-streaming convenience methods (`execute`, `executeCode`) consume
+ * the stream and return the final result.
+ */
+export declare abstract class Sandbox {
+    /**
+     * Execute a shell command, streaming output.
+     *
+     * Yields {@link StreamChunk} objects for stdout and stderr as output
+     * arrives. The final yield is an {@link ExecutionResult} with the
+     * exit code and complete output.
+     *
+     * @param command - The shell command to execute.
+     * @param options - Execution options (timeout, cwd).
+     * @returns Async iterable yielding StreamChunks followed by a final ExecutionResult.
+     */
+    abstract executeStreaming(command: string, options?: ExecuteOptions): AsyncIterable<StreamChunk | ExecutionResult>;
+    /**
+     * Execute source code via a language interpreter, streaming output.
+     *
+     * @param code - The source code to execute.
+     * @param language - The interpreter to use (e.g., `"python3"`, `"node"`).
+     * @param options - Execution options (timeout, cwd).
+     * @returns Async iterable yielding StreamChunks followed by a final ExecutionResult.
+     */
+    abstract executeCodeStreaming(code: string, language: string, options?: ExecuteOptions): AsyncIterable<StreamChunk | ExecutionResult>;
+    /**
+     * Read a file from the sandbox filesystem as raw bytes.
+     *
+     * Returns `Uint8Array` to support both text and binary files.
+     * Use {@link readText} for a convenience wrapper that decodes to a string.
+     *
+     * @param path - Path to the file to read.
+     * @returns The file contents as raw bytes.
+     * @throws Error if the file does not exist.
+     */
+    abstract readFile(path: string): Promise<Uint8Array>;
+    /**
+     * Write raw bytes to a file in the sandbox filesystem.
+     *
+     * Implementations should create parent directories if they do not exist.
+     * Use {@link writeText} for a convenience wrapper that encodes a string.
+     *
+     * @param path - Path to the file to write.
+     * @param content - The content to write.
+     */
+    abstract writeFile(path: string, content: Uint8Array): Promise<void>;
+    /**
+     * Remove a file from the sandbox filesystem.
+     *
+     * @param path - Path to the file to remove.
+     * @throws Error if the file does not exist.
+     */
+    abstract removeFile(path: string): Promise<void>;
+    /**
+     * List files in a sandbox directory.
+     *
+     * Returns {@link FileInfo} entries with name, isDir, and size metadata.
+     * Fields `isDir` and `size` may be `undefined` if the backend cannot
+     * determine them.
+     *
+     * @param path - Path to the directory to list.
+     * @returns Array of FileInfo entries for the directory contents.
+     * @throws Error if the directory does not exist.
+     */
+    abstract listFiles(path: string): Promise<FileInfo[]>;
+    /**
+     * Execute a shell command and return the result.
+     *
+     * Consumes {@link executeStreaming} and returns the final {@link ExecutionResult}.
+     * Use `executeStreaming` when you need to process output as it arrives.
+     *
+     * @param command - The shell command to execute.
+     * @param options - Execution options (timeout, cwd).
+     * @returns The execution result with exit code and output.
+     */
+    execute(command: string, options?: ExecuteOptions): Promise<ExecutionResult>;
+    /**
+     * Execute source code and return the result.
+     *
+     * Consumes {@link executeCodeStreaming} and returns the final {@link ExecutionResult}.
+     * Use `executeCodeStreaming` when you need to process output as it arrives.
+     *
+     * @param code - The source code to execute.
+     * @param language - The interpreter to use.
+     * @param options - Execution options (timeout, cwd).
+     * @returns The execution result with exit code and output.
+     */
+    executeCode(code: string, language: string, options?: ExecuteOptions): Promise<ExecutionResult>;
+    /**
+     * Read a text file from the sandbox filesystem.
+     *
+     * Convenience wrapper over {@link readFile} that decodes bytes as UTF-8.
+     * For other encodings, call `readFile` and decode manually.
+     *
+     * @param path - Path to the file to read.
+     * @returns The file contents decoded as a UTF-8 string.
+     */
+    readText(path: string): Promise<string>;
+    /**
+     * Write a text file to the sandbox filesystem.
+     *
+     * Convenience wrapper over {@link writeFile} that encodes a string as UTF-8.
+     * For other encodings, encode manually and call `writeFile`.
+     *
+     * @param path - Path to the file to write.
+     * @param content - The text content to write.
+     */
+    writeText(path: string, content: string): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/src/sandbox/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/sandbox/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CACjC;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,OAAO;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,WAAW,GAAG,eAAe,CAAC;IAElH;;;;;;;OAOG;IACH,QAAQ,CAAC,oBAAoB,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,aAAa,CAAC,WAAW,GAAG,eAAe,CAAC;IAE/C;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAEpD;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAEpE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIrD;;;;;;;;;OASG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IASlF;;;;;;;;;;OAUG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IASrG;;;;;;;;OAQG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C;;;;;;;;OAQG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9D"}

package/dist/src/sandbox/base.js

@@ -0,0 +1,84 @@
+/**
+ * Base sandbox interface.
+ *
+ * Defines the abstract {@link Sandbox} class that all sandbox implementations
+ * must extend. The class provides six abstract operations (command execution,
+ * code execution, and file I/O) and convenience wrappers for common patterns.
+ */
+/**
+ * Abstract execution environment.
+ *
+ * A Sandbox provides the runtime context where tools execute code,
+ * run commands, and interact with a filesystem. Multiple tools share
+ * the same Sandbox instance, giving them a common working directory
+ * and filesystem.
+ *
+ * Streaming methods (`executeStreaming`, `executeCodeStreaming`) are the abstract primitives.
+ * Non-streaming convenience methods (`execute`, `executeCode`) consume
+ * the stream and return the final result.
+ */
+export class Sandbox {
+    // ---- Non-streaming convenience methods ----
+    /**
+     * Execute a shell command and return the result.
+     *
+     * Consumes {@link executeStreaming} and returns the final {@link ExecutionResult}.
+     * Use `executeStreaming` when you need to process output as it arrives.
+     *
+     * @param command - The shell command to execute.
+     * @param options - Execution options (timeout, cwd).
+     * @returns The execution result with exit code and output.
+     */
+    async execute(command, options) {
+        for await (const chunk of this.executeStreaming(command, options)) {
+            if (chunk.type === 'executionResult') {
+                return chunk;
+            }
+        }
+        throw new Error('executeStreaming() did not yield an ExecutionResult');
+    }
+    /**
+     * Execute source code and return the result.
+     *
+     * Consumes {@link executeCodeStreaming} and returns the final {@link ExecutionResult}.
+     * Use `executeCodeStreaming` when you need to process output as it arrives.
+     *
+     * @param code - The source code to execute.
+     * @param language - The interpreter to use.
+     * @param options - Execution options (timeout, cwd).
+     * @returns The execution result with exit code and output.
+     */
+    async executeCode(code, language, options) {
+        for await (const chunk of this.executeCodeStreaming(code, language, options)) {
+            if (chunk.type === 'executionResult') {
+                return chunk;
+            }
+        }
+        throw new Error('executeCodeStreaming() did not yield an ExecutionResult');
+    }
+    /**
+     * Read a text file from the sandbox filesystem.
+     *
+     * Convenience wrapper over {@link readFile} that decodes bytes as UTF-8.
+     * For other encodings, call `readFile` and decode manually.
+     *
+     * @param path - Path to the file to read.
+     * @returns The file contents decoded as a UTF-8 string.
+     */
+    async readText(path) {
+        return new TextDecoder().decode(await this.readFile(path));
+    }
+    /**
+     * Write a text file to the sandbox filesystem.
+     *
+     * Convenience wrapper over {@link writeFile} that encodes a string as UTF-8.
+     * For other encodings, encode manually and call `writeFile`.
+     *
+     * @param path - Path to the file to write.
+     * @param content - The text content to write.
+     */
+    async writeText(path, content) {
+        await this.writeFile(path, new TextEncoder().encode(content));
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/src/sandbox/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/sandbox/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,OAAO;IAwE3B,8CAA8C;IAE9C;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,OAAwB;QACrD,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YAClE,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;gBACrC,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;IACxE,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,QAAgB,EAAE,OAAwB;QACxE,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;YAC7E,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;gBACrC,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAA;IAC5E,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;IAC5D,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,OAAe;QAC3C,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;IAC/D,CAAC;CACF"}

package/dist/src/sandbox/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Regex pattern for validating language/interpreter names.
+ * Allows alphanumeric characters, dots, hyphens, and underscores.
+ * Rejects path separators, spaces, and shell metacharacters to prevent injection.
+ */
+export declare const LANGUAGE_PATTERN: RegExp;
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/sandbox/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/sandbox/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAsB,CAAA"}

package/dist/src/sandbox/constants.js

@@ -0,0 +1,7 @@
+/**
+ * Regex pattern for validating language/interpreter names.
+ * Allows alphanumeric characters, dots, hyphens, and underscores.
+ * Rejects path separators, spaces, and shell metacharacters to prevent injection.
+ */
+export const LANGUAGE_PATTERN = /^[a-zA-Z0-9._-]+$/;
+//# sourceMappingURL=constants.js.map

package/dist/src/sandbox/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/sandbox/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAA"}

package/dist/src/sandbox/posix-shell.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shell sandbox with default implementations for file and code operations.
+ *
+ * Subclasses only need to implement {@link PosixShellSandbox.executeStreaming} —
+ * all other operations are implemented by running shell commands through it.
+ * Use this for remote environments where only shell access is available
+ * (Docker containers, SSH connections, cloud runtimes).
+ */
+import { Sandbox } from './base.js';
+import type { ExecuteOptions } from './base.js';
+import type { ExecutionResult, FileInfo, StreamChunk } from './types.js';
+/**
+ * Abstract sandbox that provides shell-based defaults for file and code operations.
+ * Assumes a POSIX-compatible shell (sh/bash) on the target.
+ *
+ * Subclasses only need to implement {@link executeStreaming}. The remaining
+ * operations — `executeCodeStreaming`, `readFile`, `writeFile`, `removeFile`,
+ * and `listFiles` — are implemented via shell commands piped through
+ * `executeStreaming`.
+ *
+ * Subclasses may override any method with a native implementation for
+ * better performance or to handle edge cases (e.g., binary-safe file
+ * transfer via Docker stdin pipes, or native API calls for cloud backends).
+ */
+export declare abstract class PosixShellSandbox extends Sandbox {
+    executeCodeStreaming(code: string, language: string, options?: ExecuteOptions): AsyncGenerator<StreamChunk | ExecutionResult, void, undefined>;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: Uint8Array): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    listFiles(path: string): Promise<FileInfo[]>;
+}
+//# sourceMappingURL=posix-shell.d.ts.map

package/dist/src/sandbox/posix-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posix-shell.d.ts","sourceRoot":"","sources":["../../../src/sandbox/posix-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE/C,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxE;;;;;;;;;;;;GAYG;AACH,8BAAsB,iBAAkB,SAAQ,OAAO;IAC9C,oBAAoB,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,cAAc,CAAC,WAAW,GAAG,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC;IAS3D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAqBnD"}

package/dist/src/sandbox/posix-shell.js

@@ -0,0 +1,78 @@
+/**
+ * Shell sandbox with default implementations for file and code operations.
+ *
+ * Subclasses only need to implement {@link PosixShellSandbox.executeStreaming} —
+ * all other operations are implemented by running shell commands through it.
+ * Use this for remote environments where only shell access is available
+ * (Docker containers, SSH connections, cloud runtimes).
+ */
+import { Sandbox } from './base.js';
+import { LANGUAGE_PATTERN } from './constants.js';
+import { shellQuote } from '../utils/shell-quote.js';
+/**
+ * Abstract sandbox that provides shell-based defaults for file and code operations.
+ * Assumes a POSIX-compatible shell (sh/bash) on the target.
+ *
+ * Subclasses only need to implement {@link executeStreaming}. The remaining
+ * operations — `executeCodeStreaming`, `readFile`, `writeFile`, `removeFile`,
+ * and `listFiles` — are implemented via shell commands piped through
+ * `executeStreaming`.
+ *
+ * Subclasses may override any method with a native implementation for
+ * better performance or to handle edge cases (e.g., binary-safe file
+ * transfer via Docker stdin pipes, or native API calls for cloud backends).
+ */
+export class PosixShellSandbox extends Sandbox {
+    async *executeCodeStreaming(code, language, options) {
+        if (!LANGUAGE_PATTERN.test(language)) {
+            throw new Error(`language parameter contains invalid characters: ${language}`);
+        }
+        const encoded = btoa(Array.from(new TextEncoder().encode(code), (b) => String.fromCharCode(b)).join(''));
+        const eof = `STRANDS_EOF_${crypto.randomUUID().slice(0, 16)}`;
+        yield* this.executeStreaming(`base64 -d << '${eof}' | ${language}\n${encoded}\n${eof}`, options);
+    }
+    async readFile(path) {
+        const result = await this.execute(`base64 < ${shellQuote(path)}`);
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || `Failed to read file: ${path}`);
+        }
+        return Uint8Array.from(atob(result.stdout.replace(/\s/g, '')), (c) => c.charCodeAt(0));
+    }
+    async writeFile(path, content) {
+        const encoded = btoa(Array.from(content, (b) => String.fromCharCode(b)).join(''));
+        const quoted = shellQuote(path);
+        const eof = `STRANDS_EOF_${crypto.randomUUID().slice(0, 16)}`;
+        const cmd = `mkdir -p "$(dirname ${quoted})" && base64 -d << '${eof}' > ${quoted}\n${encoded}\n${eof}`;
+        const result = await this.execute(cmd);
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || `Failed to write file: ${path}`);
+        }
+    }
+    async removeFile(path) {
+        const result = await this.execute(`rm ${shellQuote(path)}`);
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || `Failed to remove file: ${path}`);
+        }
+    }
+    async listFiles(path) {
+        const quoted = shellQuote(path);
+        const result = await this.execute(`test -d ${quoted} || exit 1; env QUOTING_STYLE=literal ls -1ap ${quoted}`);
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || `Failed to list directory: ${path}`);
+        }
+        const entries = [];
+        for (const raw of result.stdout.split('\n')) {
+            const line = raw.replace(/\r$/, '');
+            if (!line || line === './' || line === '../') {
+                continue;
+            }
+            const isDir = line.endsWith('/');
+            const name = isDir ? line.slice(0, -1) : line;
+            if (name) {
+                entries.push({ name, isDir });
+            }
+        }
+        return entries;
+    }
+}
+//# sourceMappingURL=posix-shell.js.map