Class: Nexo::Sandbox

Inherits:
Object
  • Object
show all
Defined in:
lib/nexo/sandbox.rb

Overview

The execution-environment seam. A sandbox is where an agent's tools actually touch files and run commands; swapping the sandbox swaps the whole execution context (in-memory, host, or — later — remote) by constructor injection.

Concrete sandboxes implement the four-method contract below. The base class raises NotImplementedError for each so an incomplete subclass fails loudly.

See Sandboxes::Virtual (default, zero host access) and Sandboxes::Local (host filesystem + shell, guarded).

Instance Method Summary collapse

Instance Method Details

#close ⇒ Object

Releases any resources the sandbox holds. No-op by default.



36
37
38
 
# File 'lib/nexo/sandbox.rb', line 36

def close
  nil
end

#glob(pattern) ⇒ Object

Returns the paths matching the glob pattern.

Raises:

  • (NotImplementedError) 


31
32
33
 
# File 'lib/nexo/sandbox.rb', line 31

def glob(pattern)
  raise NotImplementedError
end

#instructions ⇒ Object

A short, plain-text description of the execution environment (cwd, host access, network) for the agent to inject into the system prompt. Base returns nil — inject nothing. Real-filesystem sandboxes (Local, Container) override this so a weak tool-caller knows where it runs.



44
45
46
 
# File 'lib/nexo/sandbox.rb', line 44

def instructions
  nil
end

#mtime(path) ⇒ Object

The last-modified time of path, used by the read-before-write + stale guard for real-filesystem sandboxes. Base returns nil (no external mutation to guard against, e.g. Virtual), which disables the guard.



60
61
62
 
# File 'lib/nexo/sandbox.rb', line 60

def mtime(path)
  nil
end

#read(path) ⇒ Object

Returns the contents of path as a String.

Raises:

  • (NotImplementedError) 


15
16
17
 
# File 'lib/nexo/sandbox.rb', line 15

def read(path)
  raise NotImplementedError
end

#shell(command, timeout: 30) ⇒ Object

Runs command and returns { stdout:, stderr:, status: } (status is the integer exit code). timeout is in seconds.

Raises:

  • (NotImplementedError) 


26
27
28
 
# File 'lib/nexo/sandbox.rb', line 26

def shell(command, timeout: 30)
  raise NotImplementedError
end

#supports?(capability) ⇒ Boolean

Whether the sandbox supports capability (one of :read, :write, :glob, :shell). The base supports everything but :shell (an in-memory sandbox has no process to run a command in), so an agent only attaches the Shell tool when the sandbox reports it. Real-process sandboxes (Local, Container) override to add :shell.

Returns:

  • (Boolean) 


53
54
55
 
# File 'lib/nexo/sandbox.rb', line 53

def supports?(capability)
  capability != :shell
end

#write(path, content) ⇒ Object

Writes content to path.

Raises:

  • (NotImplementedError) 


20
21
22
 
# File 'lib/nexo/sandbox.rb', line 20

def write(path, content)
  raise NotImplementedError
end