@strands-agents/sdk 1.3.0 → 1.5.0

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

@@ -0,0 +1,38 @@
+/**
+ * Docker sandbox — executes commands in a Docker container via `docker exec`.
+ */
+import type { ExecuteOptions } from './base.js';
+import { PosixShellSandbox } from './posix-shell.js';
+import type { ExecutionResult, StreamChunk } from './types.js';
+import type { Tool } from '../tools/tool.js';
+/**
+ * Options for constructing a {@link DockerSandbox}.
+ */
+export interface DockerSandboxOptions {
+    /** ID or name of a running Docker container. */
+    container: string;
+    /**
+     * Working directory for executed commands. If omitted, no `-w` flag is set and
+     * commands run in the container's configured working directory.
+     *
+     * Set this to run elsewhere; the path must exist and be writable by the effective {@link user}.
+     */
+    workingDir?: string;
+    /**
+     * User to run commands as, in `"uid"`, `"uid:gid"`, or `"name"` form. If omitted,
+     * no `--user` flag is set and commands run as the container's configured user.
+     *
+     * Set this to override the container's identity, e.g. `"root"` or `"1000:1000"`.
+     */
+    user?: string;
+}
+/** Execute commands in a Docker container via `docker exec`. */
+export declare class DockerSandbox extends PosixShellSandbox {
+    readonly container: string;
+    readonly workingDir: string | undefined;
+    private readonly _user;
+    constructor(options: DockerSandboxOptions);
+    executeStreaming(command: string, options?: ExecuteOptions): AsyncGenerator<StreamChunk | ExecutionResult, void, undefined>;
+    getTools(): Tool[];
+}
+//# sourceMappingURL=docker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../../src/sandbox/docker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAmB,MAAM,kBAAkB,CAAA;AAErE,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAI5C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,gEAAgE;AAChE,qBAAa,aAAc,SAAQ,iBAAiB;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;gBAE9B,OAAO,EAAE,oBAAoB;IAOlC,gBAAgB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GACvB,cAAc,CAAC,WAAW,GAAG,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC;IAgCxD,QAAQ,IAAI,IAAI,EAAE;CAW5B"}

package/dist/src/sandbox/docker.js

@@ -0,0 +1,59 @@
+/**
+ * Docker sandbox — executes commands in a Docker container via `docker exec`.
+ */
+import { PosixShellSandbox, validateEnvKeys } from './posix-shell.js';
+import { streamProcess } from './stream-process.js';
+import { makeFileEditor, DEFAULT_FILE_EDITOR_DESCRIPTION } from '../vended-tools/file-editor/index.js';
+import { makeBash, SANDBOX_BASH_DESCRIPTION } from '../vended-tools/bash/index.js';
+/** Execute commands in a Docker container via `docker exec`. */
+export class DockerSandbox extends PosixShellSandbox {
+    container;
+    workingDir;
+    _user;
+    constructor(options) {
+        super();
+        this.container = options.container;
+        this.workingDir = options.workingDir;
+        this._user = options.user;
+    }
+    async *executeStreaming(command, options) {
+        const args = ['exec'];
+        // Unset user/cwd defer to the container's own configuration.
+        if (this._user !== undefined)
+            args.push('--user', this._user);
+        const cwd = options?.cwd ?? this.workingDir;
+        if (cwd !== undefined)
+            args.push('-w', cwd);
+        if (options?.env) {
+            validateEnvKeys(options.env);
+            for (const [key, val] of Object.entries(options.env)) {
+                // Values are passed as process argv (not through a shell), so no escaping is
+                // needed -- Docker stores them verbatim. This is why values aren't shell-quoted
+                // here, unlike the SSH backend which builds a shell command string.
+                args.push('-e', `${key}=${val}`);
+            }
+        }
+        // docker exec requires the container and command after all flags. Furthermore, '--'
+        // terminates flag parsing so the container is always treated as a positional argument.
+        // Without this, a name like '--privileged' would be parsed as a flag, overriding the
+        // exec options above.
+        args.push('--', this.container, 'sh', '-c', command);
+        yield* streamProcess('docker', args, {
+            timeout: options?.timeout,
+            signal: options?.signal,
+            enoentMessage: 'docker is not installed or not on PATH',
+        });
+    }
+    getTools() {
+        const cwd = this.workingDir ? ` Working directory: ${this.workingDir}.` : '';
+        return [
+            makeFileEditor(this, {
+                description: `${DEFAULT_FILE_EDITOR_DESCRIPTION} Files are in Docker container "${this.container}".`,
+            }),
+            makeBash(this, {
+                description: `${SANDBOX_BASH_DESCRIPTION} Runs in Docker container "${this.container}".${cwd}`,
+            }),
+        ];
+    }
+}
+//# sourceMappingURL=docker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docker.js","sourceRoot":"","sources":["../../../src/sandbox/docker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnD,OAAO,EAAE,cAAc,EAAE,+BAA+B,EAAE,MAAM,sCAAsC,CAAA;AACtG,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAwBlF,gEAAgE;AAChE,MAAM,OAAO,aAAc,SAAQ,iBAAiB;IACzC,SAAS,CAAQ;IACjB,UAAU,CAAoB;IACtB,KAAK,CAAoB;IAE1C,YAAY,OAA6B;QACvC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;QAClC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAA;QACpC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAA;IAC3B,CAAC;IAED,KAAK,CAAC,CAAC,gBAAgB,CACrB,OAAe,EACf,OAAwB;QAExB,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,CAAA;QAErB,6DAA6D;QAC7D,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QAE7D,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,UAAU,CAAA;QAC3C,IAAI,GAAG,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAE3C,IAAI,OAAO,EAAE,GAAG,EAAE,CAAC;YACjB,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;YAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrD,6EAA6E;gBAC7E,gFAAgF;gBAChF,oEAAoE;gBACpE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAA;YAClC,CAAC;QACH,CAAC;QAED,oFAAoF;QACpF,uFAAuF;QACvF,qFAAqF;QACrF,sBAAsB;QACtB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;QAEpD,KAAK,CAAC,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE;YACnC,OAAO,EAAE,OAAO,EAAE,OAAO;YACzB,MAAM,EAAE,OAAO,EAAE,MAAM;YACvB,aAAa,EAAE,wCAAwC;SACxD,CAAC,CAAA;IACJ,CAAC;IAEQ,QAAQ;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,uBAAuB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;QAC5E,OAAO;YACL,cAAc,CAAC,IAAI,EAAE;gBACnB,WAAW,EAAE,GAAG,+BAA+B,mCAAmC,IAAI,CAAC,SAAS,IAAI;aACrG,CAAC;YACF,QAAQ,CAAC,IAAI,EAAE;gBACb,WAAW,EAAE,GAAG,wBAAwB,8BAA8B,IAAI,CAAC,SAAS,KAAK,GAAG,EAAE;aAC/F,CAAC;SACH,CAAA;IACH,CAAC;CACF"}

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

@@ -0,0 +1,26 @@
+/**
+ * Error types for sandbox command and code execution.
+ *
+ * These are runtime throwables raised by sandbox execution; consumers can
+ * branch on them via `instanceof` to distinguish timeouts from aborts.
+ */
+/**
+ * Thrown by sandbox execution when the configured `timeout` elapses.
+ */
+export declare class SandboxTimeoutError extends Error {
+    constructor(seconds: number);
+}
+/**
+ * Thrown by sandbox execution when the abort signal fires.
+ */
+export declare class SandboxAbortError extends Error {
+    constructor();
+}
+/**
+ * Thrown by {@link Sandbox.listFiles} when the path does not exist, distinguishing
+ * genuine absence from permission or transport failures (which throw plain errors).
+ */
+export declare class SandboxPathNotFoundError extends Error {
+    constructor(path: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/sandbox/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;;CAK3C;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,IAAI,EAAE,MAAM;CAIzB"}

package/dist/src/sandbox/errors.js

@@ -0,0 +1,35 @@
+/**
+ * Error types for sandbox command and code execution.
+ *
+ * These are runtime throwables raised by sandbox execution; consumers can
+ * branch on them via `instanceof` to distinguish timeouts from aborts.
+ */
+/**
+ * Thrown by sandbox execution when the configured `timeout` elapses.
+ */
+export class SandboxTimeoutError extends Error {
+    constructor(seconds) {
+        super(`Execution timed out after ${seconds} seconds`);
+        this.name = 'SandboxTimeoutError';
+    }
+}
+/**
+ * Thrown by sandbox execution when the abort signal fires.
+ */
+export class SandboxAbortError extends Error {
+    constructor() {
+        super('Execution aborted');
+        this.name = 'SandboxAbortError';
+    }
+}
+/**
+ * Thrown by {@link Sandbox.listFiles} when the path does not exist, distinguishing
+ * genuine absence from permission or transport failures (which throw plain errors).
+ */
+export class SandboxPathNotFoundError extends Error {
+    constructor(path) {
+        super(`Path not found: ${path}`);
+        this.name = 'SandboxPathNotFoundError';
+    }
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/sandbox/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,6BAA6B,OAAO,UAAU,CAAC,CAAA;QACrD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C;QACE,KAAK,CAAC,mBAAmB,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,YAAY,IAAY;QACtB,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;IACxC,CAAC;CACF"}

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

@@ -0,0 +1,5 @@
+export { Sandbox, type ExecuteOptions } from './base.js';
+export { PosixShellSandbox } from './posix-shell.js';
+export type { StreamType, StreamChunk, FileInfo, OutputFile, ExecutionResult } from './types.js';
+export { LANGUAGE_PATTERN } from './constants.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAChG,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/src/sandbox/index.js

@@ -0,0 +1,4 @@
+export { Sandbox } from './base.js';
+export { PosixShellSandbox } from './posix-shell.js';
+export { LANGUAGE_PATTERN } from './constants.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAuB,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/src/sandbox/not-a-sandbox-local-environment.d.ts

@@ -0,0 +1,16 @@
+import { Sandbox } from './base.js';
+import type { ExecuteOptions } from './base.js';
+import type { ExecutionResult, FileInfo, StreamChunk } from './types.js';
+/**
+ * Runs on the host with no isolation. Used as the default when no sandbox is configured.
+ */
+export declare class NotASandboxLocalEnvironment extends Sandbox {
+    private _resolvePath;
+    executeStreaming(command: string, options?: ExecuteOptions): AsyncGenerator<StreamChunk | ExecutionResult, void, undefined>;
+    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=not-a-sandbox-local-environment.d.ts.map

package/dist/src/sandbox/not-a-sandbox-local-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-a-sandbox-local-environment.d.ts","sourceRoot":"","sources":["../../../src/sandbox/not-a-sandbox-local-environment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAI/C,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAWxE;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,OAAO;IACtD,OAAO,CAAC,YAAY;IAIb,gBAAgB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GACvB,cAAc,CAAC,WAAW,GAAG,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC;IAQ1D,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;IAqB3D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CA0BnD"}

package/dist/src/sandbox/not-a-sandbox-local-environment.js

@@ -0,0 +1,83 @@
+import { readFile, writeFile, unlink, mkdir, readdir, stat } from 'fs/promises';
+import { dirname, isAbsolute, join } from 'path';
+import { Sandbox } from './base.js';
+import { LANGUAGE_PATTERN, shellQuote } from './constants.js';
+import { SandboxPathNotFoundError } from './errors.js';
+import { streamProcess } from './stream-process.js';
+import { buildShellEnvPrefix } from './posix-shell.js';
+/** Returns true if the error is a missing entry (ENOENT) or a non-directory path component (ENOTDIR). */
+function isMissingPathError(error) {
+    if (error === null || typeof error !== 'object' || !('code' in error)) {
+        return false;
+    }
+    return error.code === 'ENOENT' || error.code === 'ENOTDIR';
+}
+/**
+ * Runs on the host with no isolation. Used as the default when no sandbox is configured.
+ */
+export class NotASandboxLocalEnvironment extends Sandbox {
+    _resolvePath(path) {
+        return isAbsolute(path) ? path : join(process.cwd(), path);
+    }
+    async *executeStreaming(command, options) {
+        const cwd = options?.cwd ?? process.cwd();
+        yield* streamProcess('sh', ['-c', `cd ${shellQuote(cwd)} && ${buildShellEnvPrefix(options?.env)}${command}`], {
+            timeout: options?.timeout,
+            signal: options?.signal,
+        });
+    }
+    async *executeCodeStreaming(code, language, options) {
+        if (!LANGUAGE_PATTERN.test(language)) {
+            throw new Error(`language parameter contains invalid characters: ${language}`);
+        }
+        const cwd = options?.cwd ?? process.cwd();
+        const encoded = btoa(Array.from(new TextEncoder().encode(code), (b) => String.fromCharCode(b)).join(''));
+        const eof = `STRANDS_EOF_${crypto.randomUUID().slice(0, 16)}`;
+        yield* streamProcess('sh', [
+            '-c',
+            `cd ${shellQuote(cwd)} && ${buildShellEnvPrefix(options?.env)}base64 -d << '${eof}' | ${language}\n${encoded}\n${eof}`,
+        ], {
+            timeout: options?.timeout,
+            signal: options?.signal,
+            enoentMessage: `Language interpreter not found: ${language}`,
+        });
+    }
+    async readFile(path) {
+        return readFile(this._resolvePath(path));
+    }
+    async writeFile(path, content) {
+        const fullPath = this._resolvePath(path);
+        await mkdir(dirname(fullPath), { recursive: true });
+        await writeFile(fullPath, content);
+    }
+    async removeFile(path) {
+        await unlink(this._resolvePath(path));
+    }
+    async listFiles(path) {
+        const fullPath = this._resolvePath(path);
+        let entries;
+        try {
+            entries = await readdir(fullPath, { withFileTypes: true });
+        }
+        catch (err) {
+            // A missing path (or a file where a directory was expected) is non-existence;
+            // permission and other errors propagate so callers can surface them.
+            if (isMissingPathError(err)) {
+                throw new SandboxPathNotFoundError(path);
+            }
+            throw err;
+        }
+        const results = [];
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            try {
+                const entryStat = await stat(join(fullPath, entry.name));
+                results.push({ name: entry.name, isDir: entryStat.isDirectory(), size: entryStat.size });
+            }
+            catch {
+                results.push({ name: entry.name });
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=not-a-sandbox-local-environment.js.map

package/dist/src/sandbox/not-a-sandbox-local-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-a-sandbox-local-environment.js","sourceRoot":"","sources":["../../../src/sandbox/not-a-sandbox-local-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAC/E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAEtD,yGAAyG;AACzG,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAA;AAC5D,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,OAAO;IAC9C,YAAY,CAAC,IAAY;QAC/B,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAA;IAC5D,CAAC;IAED,KAAK,CAAC,CAAC,gBAAgB,CACrB,OAAe,EACf,OAAwB;QAExB,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;QACzC,KAAK,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,UAAU,CAAC,GAAG,CAAC,OAAO,mBAAmB,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE;YAC5G,OAAO,EAAE,OAAO,EAAE,OAAO;YACzB,MAAM,EAAE,OAAO,EAAE,MAAM;SACxB,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,CAAC,oBAAoB,CACzB,IAAY,EACZ,QAAgB,EAChB,OAAwB;QAExB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,mDAAmD,QAAQ,EAAE,CAAC,CAAA;QAChF,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;QACxG,MAAM,GAAG,GAAG,eAAe,MAAM,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;QAC7D,KAAK,CAAC,CAAC,aAAa,CAClB,IAAI,EACJ;YACE,IAAI;YACJ,MAAM,UAAU,CAAC,GAAG,CAAC,OAAO,mBAAmB,CAAC,OAAO,EAAE,GAAG,CAAC,iBAAiB,GAAG,OAAO,QAAQ,KAAK,OAAO,KAAK,GAAG,EAAE;SACvH,EACD;YACE,OAAO,EAAE,OAAO,EAAE,OAAO;YACzB,MAAM,EAAE,OAAO,EAAE,MAAM;YACvB,aAAa,EAAE,mCAAmC,QAAQ,EAAE;SAC7D,CACF,CAAA;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,OAAO,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;IAC1C,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,OAAmB;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QACxC,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACnD,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,IAAY;QAC3B,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QACxC,IAAI,OAAO,CAAA;QACX,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,8EAA8E;YAC9E,qEAAqE;YACrE,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,wBAAwB,CAAC,IAAI,CAAC,CAAA;YAC1C,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;QACD,MAAM,OAAO,GAAe,EAAE,CAAA;QAE9B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;gBACxD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,CAAA;YAC1F,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YACpC,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAA;IAChB,CAAC;CACF"}

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

@@ -0,0 +1,53 @@
+/**
+ * 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';
+/**
+ * Validate environment variable names against {@link ENV_KEY_PATTERN}.
+ * @throws If any key is not a valid POSIX environment variable name.
+ */
+export declare function validateEnvKeys(env: Record<string, string>): void;
+/**
+ * Build a shell `export KEY=VALUE && ...` prefix for a command, or `''` when there are none.
+ * Keys are validated; values are {@link shellQuote}d. Used by shell-string backends (e.g. SSH);
+ * backends that set env via native flags (e.g. Docker's `-e`) call {@link validateEnvKeys} directly.
+ *
+ * Uses `export` rather than an `env KEY=VALUE` command wrapper so the variables are set in the
+ * shell itself and inherited by every stage of a pipeline. `executeCode` runs `base64 ... | <lang>`,
+ * and an `env` wrapper would only bind the left side of the pipe, never reaching the interpreter.
+ * The trailing `&&` keeps the surrounding `cd ... && <prefix><command>` chain fail-fast.
+ */
+export declare function buildShellEnvPrefix(env?: Record<string, string>): string;
+/**
+ * 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).
+ *
+ * Subclasses must apply `options.env` in `executeStreaming` or it has no effect:
+ * backends that build a shell-command string prepend {@link buildShellEnvPrefix};
+ * backends that set env via process flags (e.g. Docker's `-e`) call
+ * {@link validateEnvKeys} and pass the values directly.
+ */
+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;AAG/C,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAMjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAOxE;AAED;;;;;;;;;;;;;;;;;GAiBG;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;CAyBnD"}

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

@@ -0,0 +1,116 @@
+/**
+ * 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 { ENV_KEY_PATTERN, LANGUAGE_PATTERN, shellQuote } from './constants.js';
+import { SandboxPathNotFoundError } from './errors.js';
+/**
+ * Validate environment variable names against {@link ENV_KEY_PATTERN}.
+ * @throws If any key is not a valid POSIX environment variable name.
+ */
+export function validateEnvKeys(env) {
+    for (const key of Object.keys(env)) {
+        if (!ENV_KEY_PATTERN.test(key)) {
+            throw new Error(`Invalid environment variable name: ${key}`);
+        }
+    }
+}
+/**
+ * Build a shell `export KEY=VALUE && ...` prefix for a command, or `''` when there are none.
+ * Keys are validated; values are {@link shellQuote}d. Used by shell-string backends (e.g. SSH);
+ * backends that set env via native flags (e.g. Docker's `-e`) call {@link validateEnvKeys} directly.
+ *
+ * Uses `export` rather than an `env KEY=VALUE` command wrapper so the variables are set in the
+ * shell itself and inherited by every stage of a pipeline. `executeCode` runs `base64 ... | <lang>`,
+ * and an `env` wrapper would only bind the left side of the pipe, never reaching the interpreter.
+ * The trailing `&&` keeps the surrounding `cd ... && <prefix><command>` chain fail-fast.
+ */
+export function buildShellEnvPrefix(env) {
+    if (!env || Object.keys(env).length === 0) {
+        return '';
+    }
+    validateEnvKeys(env);
+    const assignments = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
+    return `export ${assignments.join(' ')} && `;
+}
+/**
+ * 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).
+ *
+ * Subclasses must apply `options.env` in `executeStreaming` or it has no effect:
+ * backends that build a shell-command string prepend {@link buildShellEnvPrefix};
+ * backends that set env via process flags (e.g. Docker's `-e`) call
+ * {@link validateEnvKeys} and pass the values directly.
+ */
+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);
+        // Exit 77 distinguishes a missing directory from ls's own failures (locale-independent).
+        const result = await this.execute(`test -d ${quoted} || exit 77; env QUOTING_STYLE=literal ls -1ap ${quoted}`);
+        if (result.exitCode === 77) {
+            throw new SandboxPathNotFoundError(path);
+        }
+        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

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * SSH sandbox — executes commands on a remote host via OpenSSH.
+ */
+import type { ExecuteOptions } from './base.js';
+import { PosixShellSandbox } from './posix-shell.js';
+import type { ExecutionResult, StreamChunk } from './types.js';
+import type { Tool } from '../tools/tool.js';
+/**
+ * Options for constructing an {@link SshSandbox}.
+ */
+export interface SshSandboxOptions {
+    /** SSH destination (e.g., `"user@host"`, `"192.168.1.10"`). */
+    host: string;
+    /** Working directory on the remote host. */
+    workingDir: string;
+    /** Path to SSH private key file. */
+    identityFile?: string;
+    /** SSH port. Defaults to 22. */
+    port?: number;
+    /** Additional SSH options passed as `-o` flags. */
+    sshOptions?: string[];
+    /**
+     * Allow connections to hosts with unknown or changed SSH keys.
+     *
+     * When `false` (default), uses `StrictHostKeyChecking=accept-new` — trusts on
+     * first connect but rejects if the key changes.
+     * When `true`, uses `StrictHostKeyChecking=no` — disables host key verification.
+     */
+    allowUnknownHosts?: boolean;
+    /**
+     * Bypass the SSH option allowlist.
+     *
+     * When `false` (default), unknown options throw at construction time.
+     * When `true`, all options are passed through without validation.
+     */
+    allowUnsafeSshOptions?: boolean;
+}
+/**
+ * Execute commands on a remote host via SSH.
+ *
+ * Stateless — each {@link executeStreaming} call spawns a fresh `ssh` process.
+ * All sessions use `BatchMode=yes` — interactive prompts are disabled and
+ * authentication must be key-based.
+ */
+export declare class SshSandbox extends PosixShellSandbox {
+    readonly host: string;
+    readonly workingDir: string;
+    private readonly _identityFile;
+    private readonly _port;
+    private readonly _allowUnknownHosts;
+    private readonly _sshOptions;
+    constructor(options: SshSandboxOptions);
+    executeStreaming(command: string, options?: ExecuteOptions): AsyncGenerator<StreamChunk | ExecutionResult, void, undefined>;
+    getTools(): Tool[];
+}
+//# sourceMappingURL=ssh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ssh.d.ts","sourceRoot":"","sources":["../../../src/sandbox/ssh.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAuB,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGzE,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AA4C5C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAA;IAClB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAED;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,iBAAiB;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;gBAE1B,OAAO,EAAE,iBAAiB;IAmB/B,gBAAgB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GACvB,cAAc,CAAC,WAAW,GAAG,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC;IAmCxD,QAAQ,IAAI,IAAI,EAAE;CAU5B"}