nexo_ai 0.1.0 → 0.7.0

data/lib/nexo/sandboxes/container.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module Nexo
+  module Sandboxes
+    # Runs an agent's tools inside a throwaway OCI container via the +docker+
+    # (default) or Apple +container+ CLI — shell-out only, no client gem, no
+    # Compose, no image builder. Implements the four-method sandbox contract
+    # (+read+/+write+/+shell+/+glob+) plus +close+ by shelling the runtime binary
+    # through +Open3+, so a model-driven agent never touches the host filesystem
+    # or shell directly.
+    #
+    # Hardened by default, every knob an explicit opt-out:
+    #
+    # * +--network none+ (no egress) — loosen with +network:+.
+    # * +--cap-drop ALL+ — restore individual caps with +cap_add:+.
+    # * +--read-only+ rootfs + an ephemeral +--tmpfs <cwd>:rw+ writable scratch —
+    #   disable with +readonly_rootfs: false+.
+    # * +--security-opt no-new-privileges+ (always on).
+    # * +--pids-limit 512+ fork-bomb guard — override/omit with +pids_limit:+.
+    # * Host binds mounted **read-only** by default; a bind is writable only when
+    #   the developer says so per-bind (+{ to:, mode: :rw }+).
+    #
+    # Non-root is NOT forced — the image's own uid is respected; +user:+ is an
+    # opt-in defense-in-depth. The hardening above applies regardless of uid.
+    #
+    # The container starts **lazily** on first tool use and its id is memoized.
+    # Ephemeral by default: +close+ force-removes the container. With +name:+ +
+    # +reconnect: true+ the container is reused across sandboxes and +close+ leaves
+    # it in place.
+    #
+    # Argv construction is pure (+run_argv+ and the exec argv builders) so the
+    # offline suite asserts the exact +Open3+ argv with no daemon. Live runs are
+    # +NEXO_LIVE+-gated smoke, never a core-suite dependency.
+    class Container < Sandbox
+      # Maps the +runtime:+ option onto the host CLI binary. Frozen — the only two
+      # supported local runtimes in v1.
+      RUNTIMES = {docker: "docker", apple: "container"}.freeze
+
+      # The container working directory (default +/workspace+, a container path),
+      # the selected +runtime+ (+:docker+ / +:apple+), and the required +image+.
+      attr_reader :cwd, :runtime, :image
+
+      # +image:+ is required (no default image). +runtime:+ selects the binary.
+      # Every other keyword loosens one hardening default; see the class docs and
+      # the README hardened-defaults table.
+      def initialize(image: nil, runtime: :docker, cwd: "/workspace", binds: {},
+        network: :none, cap_add: [], memory: nil, cpus: nil, pids_limit: 512,
+        user: nil, env: {}, name: nil, reconnect: false, readonly_rootfs: true)
+        raise ConfigurationError, "container sandbox requires image:" if image.nil?
+
+        @bin = RUNTIMES.fetch(runtime) do
+          raise ConfigurationError, "unknown container runtime: #{runtime.inspect}"
+        end
+        @runtime = runtime
+        @image = image
+        @cwd = cwd
+        @binds = binds
+        @network = network
+        @cap_add = cap_add
+        @memory = memory
+        @cpus = cpus
+        @pids_limit = pids_limit
+        @user = user
+        @env = env
+        @name = name || "nexo-#{Nexo.generate_run_id}"
+        @reconnect = reconnect
+        @readonly_rootfs = readonly_rootfs
+        @cid = nil
+      end
+
+      # Returns the contents of +path+ (guarded against escaping +cwd+) as a
+      # String. Raises +Errno::ENOENT+ when the file is absent, matching the other
+      # sandboxes' read contract.
+      def read(path)
+        out = exec!("cat", "--", guard_path(path))
+        raise Errno::ENOENT, path unless out[:status].zero?
+
+        out[:stdout]
+      end
+
+      # Writes +content+ to +path+ (guarded) inside the container. Content travels
+      # on stdin, never interpolated into the argv, so arbitrary bytes are safe.
+      def write(path, content)
+        exec_stdin!(content, "sh", "-c", 'cat > "$0"', guard_path(path))
+      end
+
+      # Returns the container paths matching the glob +pattern+ (guarded). Empty
+      # output yields +[]+.
+      #
+      # The guarded pattern is passed as a positional parameter (+$1+), NEVER
+      # interpolated into the script text, so shell metacharacters in a
+      # model-supplied pattern (+;+, +$()+, backticks) are inert data — +for f in
+      # $1+ still performs pathname (glob) expansion, but nothing in +$1+ is ever
+      # parsed as a command.
+      def glob(pattern)
+        script = 'for f in $1; do [ -e "$f" ] && echo "$f"; done'
+        out = exec!("sh", "-c", script, "sh", guard_path(pattern))
+        out[:stdout].split("\n")
+      end
+
+      # Runs +command+ inside the container and returns
+      # +{ stdout:, stderr:, status: }+ (status is the integer exit code). The
+      # wall-clock bound lives in +Timeout.timeout+ around +Open3.capture3+.
+      def shell(command, timeout: 30)
+        exec!("sh", "-c", command, timeout: timeout)
+      end
+
+      # Force-removes the container (ephemeral default) and clears the memo.
+      # Idempotent: safe with nothing started or called more than once. With
+      # +reconnect: true+ the container is left in place for a later sandbox to
+      # reattach by its exact identity label. Teardown stays id-based
+      # (+<bin> rm -f <cid>+): the memoized id is exact and unambiguous.
+      def close
+        if @cid && !@reconnect
+          system(@bin, "rm", "-f", @cid, out: File::NULL, err: File::NULL)
+        end
+        @cid = nil
+      end
+
+      # A short, human-readable description of the execution environment for the
+      # agent to inject later (consumed by the Refinements spec; until then the
+      # method simply exists and is correct).
+      def instructions
+        "You run inside a #{@runtime} container (image #{@image}), cwd #{@cwd}, " \
+          "network #{@network}. Only #{@cwd} and any :rw binds are writable."
+      end
+
+      # +true+ for the four sandbox capabilities. Unlike Virtual, +:shell+ is
+      # supported here (a real process runs the command).
+      def supports?(cap)
+        %i[read write shell glob].include?(cap)
+      end
+
+      # The last-modified time of +path+ (guarded) inside the container, read by
+      # shelling +stat -c %Y+ (GNU coreutils epoch seconds). Returns a +Time+, or
+      # +nil+ when the file is absent — so a new-file write skips the
+      # read-before-write guard. Used only by the R4 clobber guard.
+      def mtime(path)
+        out = exec!("stat", "-c", "%Y", "--", guard_path(path))
+        return nil unless out[:status].zero?
+
+        epoch = out[:stdout].strip
+        epoch.empty? ? nil : Time.at(Integer(epoch))
+      rescue ArgumentError
+        nil
+      end
+
+      private
+
+      # The exact +run+ argv, built purely so the offline suite can assert it with
+      # no daemon. Hardened flags come first; every loosening knob appends only
+      # when set.
+      def run_argv
+        # The identity label goes immediately after --name and before every
+        # loosening/hardening knob — it is what makes an *exact* reconnect
+        # possible (see #reconnect_argv). The key is exactly +nexo.sandbox.id+.
+        argv = [@bin, "run", "-d", "--name", @name,
+          "--label", "nexo.sandbox.id=#{@name}",
+          "--network", @network.to_s,
+          "--cap-drop", "ALL",
+          "--security-opt", "no-new-privileges"]
+        @cap_add.each { |cap| argv += ["--cap-add", cap.to_s] }
+        argv += ["--read-only", "--tmpfs", "#{@cwd}:rw"] if @readonly_rootfs
+        argv += ["--pids-limit", @pids_limit.to_s] unless @pids_limit.nil?
+        argv += ["--memory", @memory.to_s] unless @memory.nil?
+        argv += ["--cpus", @cpus.to_s] unless @cpus.nil?
+        argv += ["--user", @user.to_s] unless @user.nil?
+        @env.each { |key, value| argv += ["-e", "#{key}=#{value}"] }
+        @binds.each { |host, dst| argv += ["-v", bind_spec(host, dst)] }
+        # +tail -f /dev/null+ is busybox-portable (Alpine, Debian-slim, ruby-slim
+        # all hold open); +sleep infinity+ is NOT busybox-safe and exits at once
+        # on a slim image, failing every later +exec+.
+        argv += ["-w", @cwd, @image, "tail", "-f", "/dev/null"]
+        argv
+      end
+
+      # Builds one +-v host:ctr:mode+ spec. Binds default to +:ro+; a Hash form
+      # +{ to:, mode: :rw }+ makes a single bind writable.
+      def bind_spec(host, dst)
+        to, mode = dst.is_a?(Hash) ? [dst.fetch(:to), dst.fetch(:mode, :ro)] : [dst, :ro]
+        "#{host}:#{to}:#{mode}"
+      end
+
+      # Lazily starts (or, when reconnecting, reuses) the container and memoizes
+      # its id. Raises Nexo::Error on a start failure.
+      def ensure_started!
+        return @cid if @cid
+
+        @cid = reconnect_existing if @reconnect
+        return @cid if @cid
+
+        out, err, status = Open3.capture3(*run_argv)
+        raise Nexo::Error, "container start failed: #{err.strip}" unless status.success?
+
+        @cid = out.strip
+      end
+
+      # Reconnect path: find the container previously created under +@name+ by its
+      # EXACT identity label (never a name substring) and, if present, restart it
+      # (a no-op when already running) and reuse its id.
+      #
+      # * 0 matches  -> +nil+ (so +ensure_started!+ falls through to a fresh +run+).
+      # * 1 match    -> +start+ it and reuse that id.
+      # * >1 matches -> raise +Nexo::Error+; never guess which one to attach.
+      #
+      # Only genuinely unexpected errors (a daemon/CLI failure) fail open to the
+      # create path; the ambiguity raise and the Apple-posture +ConfigurationError+
+      # (both +Nexo::Error+ subclasses) are re-raised, never swallowed.
+      #
+      # Runtime isolation is inherent: the query shells the runtime-specific +@bin+
+      # (docker vs. Apple +container+), and each runtime keeps its own id namespace,
+      # so a +:docker+ container can never be reattached by an +:apple+ sandbox or
+      # vice versa.
+      def reconnect_existing
+        # Apple reconnect posture (Spec 20 R4/Q4): Apple's +container+ CLI has no
+        # live-verified exact +label=+ filter, and a name substring match is unsafe,
+        # so reconnect on +:apple+ raises rather than risk attaching the wrong
+        # container. Wire the verified mechanism here once Group 0 confirms one.
+        if @runtime == :apple
+          raise ConfigurationError,
+            "reconnect: true is not supported on the Apple :container runtime — " \
+            "it has no verified exact label filter (Spec 20 Q4); use runtime: :docker " \
+            "for reconnect, or run an ephemeral :apple sandbox (reconnect: false)"
+        end
+
+        out, _err, status = Open3.capture3(*reconnect_argv)
+        return nil unless status.success?
+
+        ids = out.strip.split("\n").reject(&:empty?)
+        return nil if ids.empty?
+        if ids.size > 1
+          raise Nexo::Error, "ambiguous reconnect: #{ids.size} containers labeled #{@name}"
+        end
+
+        system(@bin, "start", ids.first, out: File::NULL, err: File::NULL)
+        ids.first
+      rescue Nexo::Error
+        raise
+      rescue
+        nil
+      end
+
+      # The exact reconnect query argv, built purely so the offline suite can assert
+      # it with no daemon. Matches by the exact identity label set in +run_argv+
+      # (+label=nexo.sandbox.id=<name>+), NOT a +name=<name>+ substring filter.
+      def reconnect_argv
+        [@bin, "ps", "-aqf", "label=nexo.sandbox.id=#{@name}"]
+      end
+
+      # Runs +cmd+ inside the started container, wall-clock bounded. Returns the
+      # +{ stdout:, stderr:, status: }+ shape (integer exit code) proven by
+      # Local#shell; +Open3.capture3+ has no +timeout:+ kwarg on the target Ruby.
+      def exec!(*cmd, timeout: 30)
+        ensure_started!
+        out, err, status = Timeout.timeout(timeout) do
+          Open3.capture3(*exec_argv(*cmd))
+        end
+        {stdout: out, stderr: err, status: status.exitstatus}
+      end
+
+      # As #exec!, but feeds +data+ to the command on stdin (used by +write+ so
+      # file contents never enter the argv). +-i+ keeps stdin open.
+      def exec_stdin!(data, *cmd, timeout: 30)
+        ensure_started!
+        out, err, status = Timeout.timeout(timeout) do
+          Open3.capture3(*exec_argv(*cmd, interactive: true), stdin_data: data)
+        end
+        {stdout: out, stderr: err, status: status.exitstatus}
+      end
+
+      # The +exec+ argv (pure, offline-assertable). +interactive:+ inserts +-i+.
+      def exec_argv(*cmd, interactive: false)
+        argv = [@bin, "exec"]
+        argv << "-i" if interactive
+        argv += [@cid, *cmd]
+        argv
+      end
+
+      # Local's path-escape guard, applied to the CONTAINER path: expand against
+      # +cwd+ and raise +SecurityError+ if it escapes. Runs before any +exec+.
+      def guard_path(path)
+        full = File.expand_path(path, @cwd)
+        unless full == @cwd || full.start_with?(@cwd + File::SEPARATOR)
+          raise SecurityError, "path escapes sandbox: #{path}"
+        end
+        full
+      end
+    end
+  end
+end

data/lib/nexo/sandboxes/local.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "open3"
+require "fileutils"
+require "timeout"
+
+module Nexo
+  module Sandboxes
+    # Host filesystem + shell sandbox, for trusted dev/CI use. The developer opts
+    # into this explicitly (the default is Virtual); two guards keep a
+    # model-driven agent contained:
+    #
+    # * Path-escape guard — every +read+/+write+ path is expanded against +cwd+
+    #   and must stay inside it, otherwise +SecurityError+ is raised.
+    # * Narrowed ENV — the shell sees only PATH, HOME, LANG (plus explicit
+    #   +env:+ additions), never the full process environment.
+    #
+    # Under a fiber reactor (Spec 5) these blocking file/shell syscalls would
+    # stall every other concurrent fiber. When +Nexo.config.concurrency == :async+
+    # each operation is offloaded to a worker thread (see #offload); otherwise
+    # it runs inline, byte-for-byte the Spec 1 behavior with zero overhead. The
+    # offload never changes return values or the security properties below.
+    class Local < Sandbox
+      # The expanded workspace root; every path is guarded to stay inside it.
+      attr_reader :cwd
+
+      # Roots the sandbox at +cwd+ (expanded, default +Dir.pwd+) and narrows the
+      # shell environment to +PATH+/+HOME+/+LANG+ plus any explicit +env:+ entries.
+      def initialize(cwd: Dir.pwd, env: {})
+        @cwd = File.expand_path(cwd)
+        # The physical root (symlinks resolved), used by the escape guards so a
+        # symlink inside cwd can't leak a target outside it.
+        @real_cwd = File.exist?(@cwd) ? File.realpath(@cwd) : @cwd
+        # Deliberately narrow env — never hand a model-driven shell the whole ENV.
+        @env = ENV.to_h.slice("PATH", "HOME", "LANG").merge(env)
+      end
+
+      def read(path)
+        offload { File.read(absolute(path)) }
+      end
+
+      def glob(pattern)
+        # Guard the pattern itself so it can't escape via "../.." (metacharacters
+        # like * are preserved by expand_path), then drop any match whose real
+        # path (symlinks resolved) lands outside the sandbox.
+        full = File.expand_path(pattern, @cwd)
+        unless within?(full, @cwd)
+          raise SecurityError, "glob pattern escapes sandbox: #{pattern}"
+        end
+        offload { Dir.glob(full) }.select { |match| real_within?(match) }
+      end
+
+      def write(path, content)
+        offload do
+          full = absolute(path)
+          FileUtils.mkdir_p(File.dirname(full))
+          File.write(full, content)
+        end
+      end
+
+      # A plain-text description of this host environment for the agent's system
+      # prompt: the host cwd, that the real host filesystem and shell are
+      # reachable, and that access is guarded to +cwd+.
+      def instructions
+        "You run on the host machine, cwd #{@cwd}. The real host filesystem " \
+          "and shell are reachable; file access is guarded to #{@cwd}."
+      end
+
+      # Supports all four capabilities — unlike Virtual, a real process runs
+      # the shell command here.
+      def supports?(cap)
+        %i[read write shell glob].include?(cap)
+      end
+
+      # The last-modified time of +path+ (guarded against escaping +cwd+), or
+      # +nil+ when the file is absent — so a new-file write skips the
+      # read-before-write guard.
+      def mtime(path)
+        full = absolute(path)
+        File.exist?(full) ? File.mtime(full) : nil
+      end
+
+      def shell(command, timeout: 30)
+        offload do
+          # ruby_llm's target Ruby has no `timeout:` kwarg on Open3.capture3
+          # (verified), so the wall-clock bound lives in Timeout.timeout.
+          out, err, status = Timeout.timeout(timeout) do
+            Open3.capture3(@env, command, chdir: @cwd)
+          end
+          {stdout: out, stderr: err, status: status.exitstatus}
+        end
+      end
+
+      private
+
+      # Runs a blocking block off the reactor when async concurrency is enabled,
+      # inline otherwise. The decision is driven by config, not by
+      # +Fiber.scheduler+ detection: under +:async+ the block runs on a worker
+      # thread so the reactor keeps serving other fibers; under +:threaded+ (the
+      # default) it runs inline — identical to Spec 1, zero overhead.
+      #
+      # +Async::WorkerPool+ is not available in the installed +async+ (2.x), so
+      # the offload primitive is +Thread.new(&block).value+, which always works
+      # and re-raises any exception from the block in the calling fiber (so the
+      # path-escape +SecurityError+ still propagates unchanged).
+      def offload(&block)
+        if Nexo.config.concurrency == :async
+          thread = Thread.new(&block)
+          # #value re-raises any block exception (e.g. the path-escape
+          # SecurityError) in the caller; silence the thread's own duplicate
+          # report so an expected, re-raised error isn't printed to stderr.
+          thread.report_on_exception = false
+          thread.value
+        else
+          block.call
+        end
+      end
+
+      def absolute(path)
+        full = File.expand_path(path, @cwd)
+        # Check the PHYSICAL location (symlinks resolved), not the lexical path, so
+        # a symlink inside cwd pointing outside it — including a dangling one a
+        # write would follow — can't escape the sandbox.
+        unless within?(resolved(full), @real_cwd)
+          raise SecurityError, "path escapes sandbox: #{path}"
+        end
+        full
+      end
+
+      # True when +path+ is +base+ itself or lies beneath it (lexical prefix).
+      def within?(path, base)
+        path == base || path.start_with?(base + File::SEPARATOR)
+      end
+
+      # Whether an existing filesystem entry's real (symlink-resolved) path stays
+      # inside the sandbox. A match that vanishes or can't be resolved is excluded.
+      def real_within?(path)
+        within?(File.realpath(path), @real_cwd)
+      rescue
+        false
+      end
+
+      # The physical path a read/write would actually touch: resolve symlinks on
+      # the longest existing prefix and re-append the not-yet-existing tail, and
+      # follow a dangling symlink leaf to its target (a write would). Lets the
+      # escape guard see where the operation really lands, not just its spelling.
+      def resolved(full)
+        return File.realpath(full) if File.exist?(full)
+        return resolved(File.expand_path(File.readlink(full), File.dirname(full))) if File.symlink?(full)
+
+        parent = File.dirname(full)
+        base = File.exist?(parent) ? File.realpath(parent) : resolved(parent)
+        File.join(base, File.basename(full))
+      end
+    end
+  end
+end

data/lib/nexo/sandboxes/remote.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Nexo
+  module Sandboxes
+    # A provider-agnostic remote sandbox: it runs an agent's tools inside some
+    # remote container (E2B / Daytona / Modal / Docker / your own) by delegating
+    # the four-method Sandbox contract to an injected +client+.
+    #
+    # The client is any object responding to +read+/+write+/+exec+/+close+. That
+    # four-method contract is the entire integration surface — +Remote+ contains
+    # ZERO vendor code, so switching providers is swapping the injected object,
+    # not changing Nexo. Adapt a vendor client to the contract with a tiny shim
+    # (see the README's shim-pattern example).
+    #
+    #   sandbox = Nexo::Sandboxes::Remote.new(client: my_container_client)
+    #
+    # The client's +exec+ is expected to return the same shape the Sandbox
+    # +shell+ contract documents — +{ stdout:, stderr:, status: }+ — so +#shell+
+    # passes it straight through and +#glob+ can read +[:stdout]+. Adapting a
+    # vendor client to that shape is the shim's job (see the README example).
+    #
+    # Escalating to +:remote+ is always an explicit choice in user code; the
+    # default sandbox stays +:virtual+.
+    class Remote < Sandbox
+      # Stores any object responding to +read+/+write+/+exec+/+close+.
+      def initialize(client:)
+        @client = client
+      end
+
+      # Reads +path+ via the client.
+      def read(path)
+        @client.read(path)
+      end
+
+      # Writes +content+ to +path+ via the client.
+      def write(path, content)
+        @client.write(path, content)
+      end
+
+      # Runs +command+ via the client's +exec+ and returns its result. The client
+      # is expected to honor +timeout:+ (seconds) the way the rest of the contract
+      # honors the Sandbox shape.
+      def shell(command, timeout: 30)
+        @client.exec(command, timeout: timeout)
+      end
+
+      # Supports all four capabilities: the injected client runs a real remote
+      # process, so — unlike Virtual — an agent on a Remote sandbox gets the Shell
+      # tool attached (Agent#chat gates Shell on +supports?(:shell)+).
+      def supports?(cap)
+        %i[read write shell glob].include?(cap)
+      end
+
+      # Lists paths matching +pattern+ by expanding it remotely and splitting the
+      # client's stdout into an array of lines.
+      #
+      # The pattern is handed to an inner shell as a positional parameter (+$1+),
+      # so +for f in $1+ performs the remote glob expansion, while Shellwords
+      # keeps both the script and the pattern single opaque tokens to the outer
+      # shell — a model-supplied pattern (e.g. +"x; rm -rf ~"+) can't inject
+      # commands (assumes a POSIX +sh+ on the remote, which the shell contract
+      # already implies).
+      def glob(pattern)
+        script = 'for f in $1; do [ -e "$f" ] && echo "$f"; done'
+        command = "sh -c #{Shellwords.escape(script)} sh #{Shellwords.escape(pattern)}"
+        @client.exec(command)[:stdout].to_s.split("\n")
+      end
+
+      # Releases the remote session via the client.
+      def close
+        @client.close
+      end
+    end
+  end
+end

data/lib/nexo/sandboxes/virtual.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Nexo
+  module Sandboxes
+    # In-memory sandbox with zero host access — the safe default. Files live in a
+    # Hash keyed by normalized absolute path, so nothing the model writes ever
+    # touches the host filesystem.
+    #
+    # +#shell+ raises +NotImplementedError+ on purpose: in-memory means there is
+    # no process to run a command in. That is the safety property, not a gap.
+    class Virtual < Sandbox
+      # Starts an empty in-memory filesystem rooted at +cwd+ (default +/workspace+).
+      def initialize(cwd: "/workspace")
+        @cwd = cwd
+        @files = {}
+      end
+
+      def read(path)
+        @files.fetch(norm(path)) { raise Errno::ENOENT, path }
+      end
+
+      def write(path, content)
+        @files[norm(path)] = content
+      end
+
+      def glob(pattern)
+        normalized = norm(pattern)
+        @files.keys.select { |key| File.fnmatch(normalized, key) }
+      end
+
+      def shell(_command, **)
+        raise NotImplementedError, "virtual sandbox has no shell"
+      end
+
+      private
+
+      def norm(path)
+        File.expand_path(path, @cwd)
+      end
+    end
+  end
+end

data/lib/nexo/sandboxes.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Nexo
+  # Namespace for the concrete sandbox tiers plus the single resolver shared by
+  # Agent and Workflow so the two can't drift (Spec 15). Reproduces the
+  # Agent's prior resolution *exactly*; the host +cwd:+ applies only to +:local+
+  # (a Sandboxes::Container keeps its own +/workspace+ default — the host dir
+  # enters a container only through a +binds:+ entry).
+  module Sandboxes
+    module_function
+
+    # Resolves a sandbox declaration (symbol / Hash / pre-built instance) into a
+    # concrete Sandbox. +cwd:+ is the host working directory used only by
+    # +:local+; container tiers ignore it. Raises ConfigurationError for an
+    # unknown value, and +image:+ stays required for containers (the
+    # Sandboxes::Container constructor raises when it is absent).
+    def resolve(value, cwd: Dir.pwd)
+      return value if value.is_a?(Nexo::Sandbox)
+
+      case value
+      when :virtual then Virtual.new
+      when :local then Local.new(cwd: cwd)
+      when :docker, :apple then Container.new(runtime: value) # image: required -> raises if absent
+      when Hash then resolve_hash(value, cwd)
+      else raise Nexo::ConfigurationError, "unknown sandbox: #{value.inspect}"
+      end
+    end
+
+    # Resolves the +{ type:, **opts }+ Hash form. +:docker+/+:apple+ pass every
+    # other key straight through to Sandboxes::Container (so an explicit Hash
+    # +cwd:+ or the +/workspace+ default wins — never the host +cwd+); +:local+
+    # honors an explicit Hash +cwd:+, otherwise falls back to the host +cwd+.
+    def resolve_hash(opts, cwd)
+      type = opts.fetch(:type)
+      rest = opts.except(:type)
+      case type
+      when :docker, :apple then Container.new(runtime: type, **rest)
+      when :local then Local.new(cwd: rest.fetch(:cwd, cwd))
+      else raise Nexo::ConfigurationError, "unknown sandbox type: #{type.inspect}"
+      end
+    end
+  end
+end