feat: Sandbox parent PR (base/shell/remote/docker/tools/plugins)

strands-ts/eslint.config.js

@@ -55,6 +55,11 @@ function sdkRules(options) {
         process: 'readonly',
         setTimeout: 'readonly',
         clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        atob: 'readonly',
+        btoa: 'readonly',
+        crypto: 'readonly',
       },
     },
     plugins: {
@@ -90,6 +95,7 @@ function unitTestRules(options) {
         navigator: 'readonly',
         setTimeout: 'readonly',
         clearTimeout: 'readonly',
+        crypto: 'readonly',
       },
     },
     plugins: {

strands-ts/package.json

@@ -56,6 +56,18 @@
       "types": "./dist/src/vended-tools/bash/index.d.ts",
       "default": "./dist/src/vended-tools/bash/index.js"
     },
+    "./vended-tools/exec": {
+      "types": "./dist/src/vended-tools/exec/index.d.ts",
+      "default": "./dist/src/vended-tools/exec/index.js"
+    },
+    "./vended-tools/code-interpreter": {
+      "types": "./dist/src/vended-tools/code-interpreter/index.d.ts",
+      "default": "./dist/src/vended-tools/code-interpreter/index.js"
+    },
+    "./sandbox": {
+      "types": "./dist/src/sandbox/index.d.ts",
+      "default": "./dist/src/sandbox/index.js"
+    },
     "./a2a": {
       "types": "./dist/src/a2a/index.d.ts",
       "default": "./dist/src/a2a/index.js"

strands-ts/src/__fixtures__/agent-helpers.ts

@@ -12,6 +12,7 @@ import type { Role } from '../types/messages.js'
 import { StateStore } from '../state-store.js'
 import type { JSONValue } from '../types/json.js'
 import { ToolRegistry } from '../registry/tool-registry.js'
+import type { Sandbox } from '../sandbox/base.js'
 import type { HookableEvent, StreamEvent } from '../hooks/events.js'
 import type { HookableEventConstructor, HookCallback } from '../hooks/types.js'
 import { expectLoopMetrics, type LoopMetricsMatcher } from './metrics-helpers.js'
@@ -40,6 +41,10 @@ export interface MockAgentData {
    * Optional tool registry for the agent.
    */
   toolRegistry?: ToolRegistry
+  /**
+   * Sandbox instance for the agent.
+   */
+  sandbox?: Sandbox
   /**
    * Additional properties to spread onto the mock agent.
    */
@@ -66,6 +71,7 @@ export function createMockAgent(data?: MockAgentData): MockAgent {
     appState: new StateStore(data?.appState ?? {}),
     modelState: new StateStore(),
     toolRegistry: data?.toolRegistry ?? new ToolRegistry(),
+    sandbox: data?.sandbox,
     cancelSignal: new AbortController().signal,
     addHook: <T extends HookableEvent>(eventType: HookableEventConstructor<T>, callback: HookCallback<T>) => {
       trackedHooks.push({

strands-ts/src/__fixtures__/test-sandbox.node.ts

@@ -0,0 +1,33 @@
+import { spawn } from 'child_process'
+import { ShellSandbox } from '../sandbox/shell.js'
+import { shellQuote } from '../utils/shell-quote.js'
+import { streamProcess } from '../sandbox/stream-process.js'
+import type { ExecuteOptions } from '../sandbox/base.js'
+import type { ExecutionResult, StreamChunk } from '../sandbox/types.js'
+
+/**
+ * Test sandbox that executes commands within a specific working directory.
+ *
+ * Extends ShellSandbox (same base as DockerSandbox and RemoteSandbox) so it
+ * exercises the same code path real sandboxes use: base64 file encoding,
+ * shell quoting, ls parsing, etc. The only difference is commands run on
+ * the host rather than in a container or over SSH.
+ */
+export class TestSandbox extends ShellSandbox {
+  readonly workingDir: string
+
+  constructor(workingDir: string) {
+    super()
+    this.workingDir = workingDir
+  }
+
+  async *executeStreaming(
+    command: string,
+    options?: ExecuteOptions
+  ): AsyncGenerator<StreamChunk | ExecutionResult, void, undefined> {
+    const cwd = options?.cwd ?? this.workingDir
+    const fullCommand = `cd ${shellQuote(cwd)} && ${command}`
+    const proc = spawn('sh', ['-c', fullCommand])
+    yield* streamProcess(proc, { timeout: options?.timeout, signal: options?.signal })
+  }
+}

strands-ts/src/agent/__tests__/agent.model-retry.test.ts

@@ -11,6 +11,9 @@ import { ConstantBackoff } from '../../retry/backoff-strategy.js'
 import { ModelThrottledError } from '../../errors.js'
 import { AfterModelCallEvent } from '../../hooks/events.js'
 import { logger } from '../../logging/logger.js'
+import '../../sandbox/not-a-sandbox-local-environment.js'
+// eslint-disable-next-line no-restricted-imports
+import '../../vended-tools/sandbox-default-tools.js'
 
 describe('Agent retryStrategy wiring', () => {
   beforeEach(() => {
@@ -34,7 +37,6 @@ describe('Agent retryStrategy wiring', () => {
     })
 
     const invokePromise = agent.invoke('hi')
-    // Flush any pending timers the retry scheduled.
     await vi.runAllTimersAsync()
     const result = await invokePromise
 

strands-ts/src/agent/__tests__/agent.test.ts

@@ -907,7 +907,7 @@ describe('Agent', () => {
         await agent.invoke('First prompt')
         expect(agent.systemPrompt).toEqual([new TextBlock('You are a helpful assistant')])
 
-        // Should have been called with the given promp
+        // Should have been called with the given prompt and no tools (no sandbox configured)
         expect(streamSpy).toHaveBeenCalledWith(
           expect.any(Array),
           expect.objectContaining({

strands-ts/src/agent/agent.ts

@@ -8,6 +8,7 @@ import {
   type LocalAgent,
   type localAgentSymbol,
 } from '../types/agent.js'
+import type { Sandbox } from '../sandbox/base.js'
 import { BedrockModel } from '../models/bedrock.js'
 import {
   contentBlockFromData,
@@ -220,6 +221,14 @@ export type AgentConfig = {
    * Defaults to `'concurrent'`. See {@link ToolExecutorStrategy} for details.
    */
   toolExecutor?: ToolExecutorStrategy
+  /**
+   * Sandbox for tool code execution and filesystem access.
+   * When provided, sandbox default tools (fileEditor, exec, codeInterpreter) are
+   * auto-registered and execute within the sandbox.
+   * When omitted, no sandbox tools are auto-registered.
+   * Pass `false` to explicitly disable sandbox and sandbox tool auto-registration.
+   */
+  sandbox?: Sandbox | false
 }
 
 /** Default name assigned to agents when none is provided. */
@@ -262,6 +271,19 @@ export class Agent implements LocalAgent, InvokableAgent {
    */
   public model: Model
 
+  /**
+   * Sandbox for tool code execution and filesystem access.
+   * Set immediately if passed via config, otherwise defaults to NotASandboxLocalEnvironment during initialize().
+   */
+  private _sandbox: Sandbox | false | undefined
+
+  get sandbox(): Sandbox {
+    if (!this._sandbox) {
+      throw new Error('Sandbox is not available. Pass a Sandbox instance to the agent config to enable it.')
+    }
+    return this._sandbox
+  }
+
   /**
    * The system prompt to pass to the model provider.
    */
@@ -407,6 +429,8 @@ export class Agent implements LocalAgent, InvokableAgent {
       this._appendMessageAndFireHooks(message, invocationState)
     )
 
+    this._sandbox = config?.sandbox
+
     this._initialized = false
   }
 
@@ -443,6 +467,17 @@ export class Agent implements LocalAgent, InvokableAgent {
       return
     }
 
+    const userProvidedSandbox = this._sandbox !== undefined && this._sandbox !== false
+
+    if (!userProvidedSandbox && typeof process !== 'undefined' && process.versions?.node) {
+      const { NotASandboxLocalEnvironment } = await import('../sandbox/not-a-sandbox-local-environment.js')
+      this._sandbox = new NotASandboxLocalEnvironment()
+    }
+
+    if (this._sandbox) {
+      await this._sandbox.start()
+    }
+
     // Initialize MCP clients and register their tools
     await Promise.all(
       this._mcpClients.map(async (client) => {
@@ -457,6 +492,15 @@ export class Agent implements LocalAgent, InvokableAgent {
 
     await this._pluginRegistry.initialize(this)
 
+    if (userProvidedSandbox) {
+      const { SANDBOX_DEFAULT_TOOLS } = await import('../vended-tools/sandbox-default-tools.js')
+      for (const tool of SANDBOX_DEFAULT_TOOLS) {
+        if (!this._toolRegistry.get(tool.name)) {
+          this._toolRegistry.add(tool)
+        }
+      }
+    }
+
     await this._hooksRegistry.invokeCallbacks(new InitializedEvent({ agent: this }))
 
     this._initialized = true

strands-ts/src/index.ts

@@ -300,6 +300,17 @@ export { AgentTrace } from './telemetry/tracer.js'
 // Local Metrics
 export { AgentMetrics } from './telemetry/meter.js'
 
+// Sandbox (base class and types only — Node-specific implementations available via './sandbox' sub-export)
+export { Sandbox, type ExecuteOptions } from './sandbox/base.js'
+export type {
+  StreamType,
+  StreamChunk,
+  FileInfo,
+  OutputFile,
+  ExecutionResult,
+  SandboxSnapshot,
+} from './sandbox/types.js'
+
 // Multi-agent orchestration
 export { Graph } from './multiagent/index.js'
 export { Swarm } from './multiagent/index.js'

strands-ts/src/sandbox/__tests__/remote.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { RemoteSandbox } from '../remote.js'
+import * as childProcess from 'child_process'
+
+vi.mock('child_process', async () => {
+  const actual = await vi.importActual<typeof childProcess>('child_process')
+  return { ...actual, spawn: vi.fn() }
+})
+
+function createMockProcess() {
+  const proc = {
+    stdout: { on: vi.fn() },
+    stderr: { on: vi.fn() },
+    on: vi.fn(),
+    kill: vi.fn(),
+  }
+
+  // Simulate immediate close with exit code 0
+  proc.on.mockImplementation((event: string, cb: (code: number | null) => void) => {
+    if (event === 'close') {
+      // Schedule the close callback
+      Promise.resolve().then(() => cb(0))
+    }
+  })
+
+  return proc
+}
+
+describe('RemoteSandbox (unit)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('constructor', () => {
+    it('stores host and workingDir', () => {
+      const sandbox = new RemoteSandbox({ host: 'myhost', workingDir: '/workspace' })
+      expect(sandbox.host).toBe('myhost')
+      expect(sandbox.workingDir).toBe('/workspace')
+    })
+
+    it('defaults port to 22', () => {
+      const sandbox = new RemoteSandbox({ host: 'myhost', workingDir: '/ws' })
+      // Port is private but we can verify via the SSH args in stream()
+      expect(sandbox).toBeDefined()
+    })
+  })
+
+  describe('stream() SSH argument construction', () => {
+    it('builds correct SSH args with defaults', async () => {
+      const mockProc = createMockProcess()
+      vi.mocked(childProcess.spawn).mockReturnValue(mockProc as never)
+
+      const sandbox = new RemoteSandbox({ host: 'user@server.com', workingDir: '/remote/path' })
+
+      // Start consuming the generator to trigger spawn
+      const gen = sandbox.executeStreaming('echo hi')
+      const iter = gen[Symbol.asyncIterator]()
+      await iter.next()
+
+      expect(childProcess.spawn).toHaveBeenCalledWith('ssh', [
+        '-o',
+        'StrictHostKeyChecking=accept-new',
+        '-o',
+        'BatchMode=yes',
+        '-p',
+        '22',
+        'user@server.com',
+        "cd '/remote/path' && echo hi",
+      ])
+    })
+
+    it('includes identity file when provided', async () => {
+      const mockProc = createMockProcess()
+      vi.mocked(childProcess.spawn).mockReturnValue(mockProc as never)
+
+      const sandbox = new RemoteSandbox({
+        host: 'server',
+        workingDir: '/ws',
+        identityFile: '/home/user/.ssh/key',
+      })
+
+      const gen = sandbox.executeStreaming('ls')
+      const iter = gen[Symbol.asyncIterator]()
+      await iter.next()
+
+      const args = vi.mocked(childProcess.spawn).mock.calls[0]![1] as string[]
+      expect(args).toContain('-i')
+      expect(args).toContain('/home/user/.ssh/key')
+    })
+
+    it('uses custom port', async () => {
+      const mockProc = createMockProcess()
+      vi.mocked(childProcess.spawn).mockReturnValue(mockProc as never)
+
+      const sandbox = new RemoteSandbox({
+        host: 'server',
+        workingDir: '/ws',
+        port: 2222,
+      })
+
+      const gen = sandbox.executeStreaming('ls')
+      const iter = gen[Symbol.asyncIterator]()
+      await iter.next()
+
+      const args = vi.mocked(childProcess.spawn).mock.calls[0]![1] as string[]
+      expect(args).toContain('-p')
+      expect(args).toContain('2222')
+    })
+
+    it('quotes cwd with single quotes', async () => {
+      const mockProc = createMockProcess()
+      vi.mocked(childProcess.spawn).mockReturnValue(mockProc as never)
+
+      const sandbox = new RemoteSandbox({
+        host: 'server',
+        workingDir: "/path/with spaces/and'quotes",
+      })
+
+      const gen = sandbox.executeStreaming('ls')
+      const iter = gen[Symbol.asyncIterator]()
+      await iter.next()
+
+      const args = vi.mocked(childProcess.spawn).mock.calls[0]![1] as string[]
+      const remoteCommand = args[args.length - 1]
+      expect(remoteCommand).toContain("cd '/path/with spaces/and'\\''quotes'")
+    })
+
+    it('uses cwd option when provided', async () => {
+      const mockProc = createMockProcess()
+      vi.mocked(childProcess.spawn).mockReturnValue(mockProc as never)
+
+      const sandbox = new RemoteSandbox({ host: 'server', workingDir: '/default' })
+
+      const gen = sandbox.executeStreaming('ls', { cwd: '/override' })
+      const iter = gen[Symbol.asyncIterator]()
+      await iter.next()
+
+      const args = vi.mocked(childProcess.spawn).mock.calls[0]![1] as string[]
+      const remoteCommand = args[args.length - 1]
+      expect(remoteCommand).toContain("cd '/override'")
+    })
+  })
+
+  describe('start()', () => {
+    it('creates working directory with cwd: /', async () => {
+      const mockProc = createMockProcess()
+      vi.mocked(childProcess.spawn).mockReturnValue(mockProc as never)
+
+      const sandbox = new RemoteSandbox({ host: 'server', workingDir: '/my/workspace' })
+      await sandbox.start()
+
+      const args = vi.mocked(childProcess.spawn).mock.calls[0]![1] as string[]
+      const remoteCommand = args[args.length - 1]
+      expect(remoteCommand).toContain("cd '/'")
+      expect(remoteCommand).toContain("mkdir -p '/my/workspace'")
+    })
+  })
+})