@strands-agents/sdk 1.4.0 → 1.5.0

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

@@ -6,6 +6,7 @@
  * code execution, and file I/O) and convenience wrappers for common patterns.
  */
 import type { ExecutionResult, FileInfo, StreamChunk } from './types.js';
+import type { Tool } from '../tools/tool.js';
 /**
  * Options for command and code execution.
  */
@@ -16,6 +17,12 @@ export interface ExecuteOptions {
     cwd?: string | undefined;
     /** Abort signal to cancel execution. The process is killed when the signal fires. */
     signal?: AbortSignal | undefined;
+    /**
+     * Environment variables to set for this command. Built-in sandboxes always apply these,
+     * though the mechanism differs (Docker `-e` flags, SSH `env` prefix); custom `Sandbox`
+     * implementations must handle env explicitly or it has no effect.
+     */
+    env?: Record<string, string> | undefined;
 }
 /**
  * Abstract execution environment.
@@ -38,7 +45,7 @@ export declare abstract class Sandbox {
      * exit code and complete output.
      *
      * @param command - The shell command to execute.
-     * @param options - Execution options (timeout, cwd).
+     * @param options - Execution options.
      * @returns Async iterable yielding StreamChunks followed by a final ExecutionResult.
      */
     abstract executeStreaming(command: string, options?: ExecuteOptions): AsyncIterable<StreamChunk | ExecutionResult>;
@@ -47,7 +54,7 @@ export declare abstract class Sandbox {
      *
      * @param code - The source code to execute.
      * @param language - The interpreter to use (e.g., `"python3"`, `"node"`).
-     * @param options - Execution options (timeout, cwd).
+     * @param options - Execution options.
      * @returns Async iterable yielding StreamChunks followed by a final ExecutionResult.
      */
     abstract executeCodeStreaming(code: string, language: string, options?: ExecuteOptions): AsyncIterable<StreamChunk | ExecutionResult>;
@@ -91,6 +98,17 @@ export declare abstract class Sandbox {
      * @throws Error if the directory does not exist.
      */
     abstract listFiles(path: string): Promise<FileInfo[]>;
+    /**
+     * Prefix applied to tool names when registered on an agent (e.g. `'sandbox'` produces
+     * `sandbox_bash`). Set to `undefined` to disable prefixing. Defaults to `'sandbox'`.
+     */
+    toolPrefix: string | undefined;
+    /**
+     * Tools this sandbox vends to an agent, registered during `Agent.initialize()`.
+     * A tool is skipped if the user already registered one with the same name.
+     * Override to provide them.
+     */
+    getTools(): Tool[];
     /**
      * Execute a shell command and return the result.
      *
@@ -98,7 +116,7 @@ export declare abstract class Sandbox {
      * Use `executeStreaming` when you need to process output as it arrives.
      *
      * @param command - The shell command to execute.
-     * @param options - Execution options (timeout, cwd).
+     * @param options - Execution options.
      * @returns The execution result with exit code and output.
      */
     execute(command: string, options?: ExecuteOptions): Promise<ExecutionResult>;
@@ -110,7 +128,7 @@ export declare abstract class Sandbox {
      *
      * @param code - The source code to execute.
      * @param language - The interpreter to use.
-     * @param options - Execution options (timeout, cwd).
+     * @param options - Execution options.
      * @returns The execution result with exit code and output.
      */
     executeCode(code: string, language: string, options?: ExecuteOptions): Promise<ExecutionResult>;

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

@@ -1 +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"}
+{"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;AACxE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C;;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;IAChC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;CACzC;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;IAErD;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAY;IAE1C;;;;OAIG;IACH,QAAQ,IAAI,IAAI,EAAE;IAMlB;;;;;;;;;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

@@ -18,6 +18,19 @@
  * the stream and return the final result.
  */
 export class Sandbox {
+    /**
+     * Prefix applied to tool names when registered on an agent (e.g. `'sandbox'` produces
+     * `sandbox_bash`). Set to `undefined` to disable prefixing. Defaults to `'sandbox'`.
+     */
+    toolPrefix = 'sandbox';
+    /**
+     * Tools this sandbox vends to an agent, registered during `Agent.initialize()`.
+     * A tool is skipped if the user already registered one with the same name.
+     * Override to provide them.
+     */
+    getTools() {
+        return [];
+    }
     // ---- Non-streaming convenience methods ----
     /**
      * Execute a shell command and return the result.
@@ -26,7 +39,7 @@ export class Sandbox {
      * Use `executeStreaming` when you need to process output as it arrives.
      *
      * @param command - The shell command to execute.
-     * @param options - Execution options (timeout, cwd).
+     * @param options - Execution options.
      * @returns The execution result with exit code and output.
      */
     async execute(command, options) {
@@ -45,7 +58,7 @@ export class Sandbox {
      *
      * @param code - The source code to execute.
      * @param language - The interpreter to use.
-     * @param options - Execution options (timeout, cwd).
+     * @param options - Execution options.
      * @returns The execution result with exit code and output.
      */
     async executeCode(code, language, options) {

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

@@ -1 +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"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/sandbox/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuBH;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,OAAO;IAwE3B;;;OAGG;IACH,UAAU,GAAuB,SAAS,CAAA;IAE1C;;;;OAIG;IACH,QAAQ;QACN,OAAO,EAAE,CAAA;IACX,CAAC;IAED,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

@@ -4,4 +4,22 @@
  * Rejects path separators, spaces, and shell metacharacters to prevent injection.
  */
 export declare const LANGUAGE_PATTERN: RegExp;
+/**
+ * Regex pattern for validating environment variable names: a leading letter or
+ * underscore, followed by letters, digits, or underscores (valid POSIX names).
+ * Names outside this set are rejected to prevent shell-syntax injection where a
+ * key is interpolated into a command, and to fail with a clear error otherwise.
+ */
+export declare const ENV_KEY_PATTERN: RegExp;
+/**
+ * Shell-escape a string for safe inclusion in a shell command.
+ *
+ * Wraps the value in single quotes and escapes any embedded single quotes
+ * using the '\'' pattern. Single quotes disable all shell expansion
+ * (variables, backticks, globbing), making this safe against injection.
+ *
+ * @param value - The string to escape.
+ * @returns The shell-escaped string wrapped in single quotes.
+ */
+export declare function shellQuote(value: string): string;
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/sandbox/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAsB,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/sandbox/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAsB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAA6B,CAAA;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/src/sandbox/constants.js

@@ -4,4 +4,24 @@
  * Rejects path separators, spaces, and shell metacharacters to prevent injection.
  */
 export const LANGUAGE_PATTERN = /^[a-zA-Z0-9._-]+$/;
+/**
+ * Regex pattern for validating environment variable names: a leading letter or
+ * underscore, followed by letters, digits, or underscores (valid POSIX names).
+ * Names outside this set are rejected to prevent shell-syntax injection where a
+ * key is interpolated into a command, and to fail with a clear error otherwise.
+ */
+export const ENV_KEY_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Shell-escape a string for safe inclusion in a shell command.
+ *
+ * Wraps the value in single quotes and escapes any embedded single quotes
+ * using the '\'' pattern. Single quotes disable all shell expansion
+ * (variables, backticks, globbing), making this safe against injection.
+ *
+ * @param value - The string to escape.
+ * @returns The shell-escaped string wrapped in single quotes.
+ */
+export function shellQuote(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
 //# sourceMappingURL=constants.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/sandbox/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAA"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/sandbox/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,0BAA0B,CAAA;AAEzD;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,GAAG,CAAA;AACjD,CAAC"}

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

@@ -0,0 +1,3 @@
+import type { Sandbox } from './base.js';
+export declare const defaultSandbox: import("../default-slot.js").DefaultSlot<Sandbox>;
+//# sourceMappingURL=default.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../../../src/sandbox/default.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGxC,eAAO,MAAM,cAAc,mDAE1B,CAAA"}

package/dist/src/sandbox/default.js

@@ -0,0 +1,3 @@
+import { createDefaultSlot } from '../default-slot.js';
+export const defaultSandbox = createDefaultSlot('No Sandbox configured. Pass a `sandbox` to the Agent to use sandbox features in this environment.');
+//# sourceMappingURL=default.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default.js","sourceRoot":"","sources":["../../../src/sandbox/default.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAEtD,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAC7C,mGAAmG,CACpG,CAAA"}

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":"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"}

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

@@ -9,6 +9,22 @@
 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.
@@ -21,6 +37,11 @@ import type { ExecutionResult, FileInfo, StreamChunk } from './types.js';
  * 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>;

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

@@ -1 +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"}
+{"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

@@ -7,8 +7,37 @@
  * (Docker containers, SSH connections, cloud runtimes).
  */
 import { Sandbox } from './base.js';
-import { LANGUAGE_PATTERN } from './constants.js';
-import { shellQuote } from '../utils/shell-quote.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.
@@ -21,6 +50,11 @@ import { shellQuote } from '../utils/shell-quote.js';
  * 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) {
@@ -56,7 +90,11 @@ export class PosixShellSandbox extends Sandbox {
     }
     async listFiles(path) {
         const quoted = shellQuote(path);
-        const result = await this.execute(`test -d ${quoted} || exit 1; env QUOTING_STYLE=literal ls -1ap ${quoted}`);
+        // 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}`);
         }