nexo_ai 0.8.0 → 0.9.0

data/docs/workflows.md

@@ -115,7 +115,7 @@ the count staged.
 
 `artifact(name, content:)` records a **named deliverable** on the run — a digest,
 a report, an improved file, a generated script. The body is written to the
-sandbox at `/artifacts/<name>` (so later steps can read it) and recorded on the
+sandbox at `artifacts/<name>` (so later steps can read it) and recorded on the
 run. `run.artifacts` reads it back as an **ordered array** of string-keyed hashes
 (`{"name" =>, "content" =>, "at" =>}`) in both stores:
 
@@ -150,6 +150,52 @@ artifact("digest.md", from: "app/templates/digest.md.erb",
 
 See [`examples/artifact_from_template.rb`](../examples/artifact_from_template.rb) for
 the full offline flow (`ruby -Ilib examples/artifact_from_template.rb`).
+### Agent output — `produces`
+
+`from:` renders ERB and is **only** for templates you wrote. An agent's output is model
+output, so it is copied **verbatim** instead. An agent declares what it produces, and may
+produce as many artifacts as it likes:
+
+```ruby
+class Publisher < Nexo::Agent
+  skills :dashboard_designer
+  produces "dashboard.html", "digest.json", "out/*.csv"
+end
+```
+
+`run_agent` copies those out of the sandbox and records them on the run the moment the
+agent finishes — **including when it suspended for approval or raised**, which are exactly
+the paths where results would otherwise be lost. Under the hood that is
+`artifact(name, path:)`, the verbatim third mode, which you can also call directly.
+
+Why this matters: a workflow builds **one** sandbox that every `run_agent` borrows, so a
+hand-off between stages is just "agent B reads a path agent A wrote". On `:local` that is a
+real directory and survives anything. On `:docker`/`:apple` it does not — `Container#close`
+is `rm -f`, and a run's sandbox is released on **every** terminal path, `suspended`
+included. So pausing for a human approval destroyed everything produced before the pause,
+while the identical code on `:local` kept it. Declared artifacts survive the teardown.
+
+Declared, never inferred: sweeping the sandbox would also collect staged skill scripts,
+templates and scratch files, and naming outputs is the only honest way for an agent to say
+it produced nothing. A declared artifact that was never written is skipped, not fatal.
+
+Bytes that are not valid UTF-8 are Base64-wrapped so they survive a JSON column. Read a
+body back with `Nexo::Workflow.artifact_body(art)` rather than `art["content"]`, which is
+Base64 text for binary.
+
+### Handing output to the next stage — `restore_artifacts`
+
+```ruby
+run_agent("extract")          # Extractor produces gmail.json
+restore_artifacts             # put recorded artifacts back in the sandbox
+run_agent("synthesize")       # Synthesizer reads gmail.json
+```
+
+`Skills.materialize` gets a skill's files *into* a sandbox; this is the other direction and
+then back in again, so a pipeline behaves the same whether the tier is persistent or
+ephemeral — including across a suspend and resume, where the sandbox that held the files no
+longer exists. Pass `only:` to restore a subset.
+
 
 The `artifacts` column ships with fresh installs. Apps installed before this
 release add it with:

data/lib/nexo/agent.rb

@@ -22,7 +22,7 @@ module Nexo
     # configuration instead of silently resetting to defaults.
     CONFIG_IVARS = %i[
       @model @assume_model_exists @provider @sandbox @permissions @instructions
-      @skills @mcp @mcp_allow @fetch_allow @search_backend
+      @skills @mcp @mcp_allow @fetch_allow @search_backend @requires @produces
     ].freeze
 
     class << self
@@ -102,6 +102,59 @@ module Nexo
         names.empty? ? (@skills || []) : (@skills = ((@skills || []) + names).uniq)
       end
 
+      # What this agent needs from whatever sandbox it runs in — checked once,
+      # before the first turn, against Sandbox#environment:
+      #
+      #   class Publisher < Nexo::Agent
+      #     skills :dashboard_designer
+      #     requires commands: {"ruby" => ">= 3.1"}, locale: :utf8
+      #   end
+      #
+      # Declared HERE, in Nexo's own vocabulary, rather than in the skill file:
+      # whoever wires an agent to a sandbox is the only person who can *fix* a
+      # gap, so the declaration and the fix live in the same place. A skill states
+      # its needs in prose via +compatibility:+, which is the spec's field for it
+      # and is aimed at a human or a model.
+      #
+      # +commands:+ maps a command that must be on +PATH+ to a version constraint
+      # — a Gem::Requirement string (+">= 3.1"+) or +"*"+ for "any version". A
+      # command whose version cannot be read (busybox +sh+ prints none) satisfies
+      # any constraint by being present: an unreadable version is not evidence of
+      # a wrong one. +locale:+ takes +:utf8+ (any UTF-8 locale — the useful case)
+      # or an exact String.
+      #
+      # Deliberately coarse, and never packages: gems, wheels and npm modules
+      # belong to the image, not here (see Sandbox#environment).
+      def requires(commands: nil, locale: nil)
+        return @requires if commands.nil? && locale.nil?
+
+        @requires = {commands: commands || {}, locale: locale}
+      end
+
+      # The artifacts this agent produces — sandbox paths, or globs, that a
+      # workflow copies out of the sandbox and records on the run as soon as the
+      # agent finishes:
+      #
+      #   class Publisher < Nexo::Agent
+      #     produces "dashboard.html", "digest.json", "out/*.csv"
+      #   end
+      #
+      # Accumulating and deduped, like +skills+: an agent may produce many
+      # artifacts, and several +produces+ lines add up rather than replacing.
+      #
+      # This is the agent's OUTPUT, not a template. Workflow#artifact's +from:+
+      # mode renders ERB and is only ever for files you wrote; what an agent
+      # produces is model output and is copied verbatim (Workflow#artifact +path:+).
+      #
+      # Declared rather than inferred because a sweep of the sandbox would also
+      # collect staged skill scripts, templates and scratch files — and because
+      # naming outputs is the only honest way for an agent to say it produced
+      # nothing. A declared artifact that is absent when the agent finishes is
+      # skipped, not fatal.
+      def produces(*names)
+        names.empty? ? (@produces || []) : (@produces = ((@produces || []) + names).uniq)
+      end
+
       # Declares an MCP server for this agent (Spec 6). Accumulating: multiple
       # +mcp+ lines are collected. With no args (+name+ nil and +opts+ empty) it
       # reads the list (default +[]+); otherwise it appends the friendly,
@@ -246,6 +299,7 @@ module Nexo
       apply_mcp(c)
       apply_fetch(c)
       apply_search(c)
+      apply_tool_concurrency(c)
       c
     end
 
@@ -254,9 +308,87 @@ module Nexo
     # so swapping +loop:+ swaps the engine without touching this class. The
     # optional +&on_event+ block receives +(type, payload)+ progress events.
     def prompt(text, max_turns: 25, &on_event)
+      verify_environment!
       @loop.run(agent: self, prompt: text, max_turns: max_turns, &on_event)
     end
 
+    # Checks the agent's declared ::requires against its sandbox, once, before the
+    # first turn. A no-op — and zero cost, no probe at all — when nothing is
+    # declared, which is the default.
+    #
+    # Fails BEFORE the model is called, because the alternative is what this
+    # exists to prevent: the agent spends turns deciding to run a script, runs it,
+    # and gets +sh: ruby: not found+ or an Encoding::InvalidByteSequenceError three
+    # frames into a JSON parse. One legible sentence naming what is missing and
+    # where beats a stack trace after the fact.
+    #
+    # Raises Nexo::EnvironmentError listing every unmet requirement at once, so a
+    # misprovisioned image is fixed in one pass rather than one round trip per
+    # missing command.
+    def verify_environment!
+      return if @environment_verified
+
+      req = self.class.requires
+      @environment_verified = true
+      return if req.nil?
+
+      missing = unmet_requirements(req, @sandbox.environment)
+      return if missing.empty?
+
+      raise Nexo::EnvironmentError,
+        "#{self.class} cannot run here: #{missing.join("; ")}. " \
+        "Provision the sandbox, or drop the `requires` declaration."
+    end
+
+    private
+
+    # The declared requirements this environment does not meet, as human-readable
+    # phrases. Reports the probe's own failure first when it could not run at all:
+    # "no ruby" and "I never got to look" are different problems with different
+    # fixes, and saying the first when the second is true sends the reader to the
+    # wrong place.
+    def unmet_requirements(req, env)
+      return ["could not inspect the sandbox (#{env[:error]})"] if env[:error]
+
+      missing = req[:commands].filter_map do |name, constraint|
+        found = env[:commands][name.to_s]
+        next "no #{name} on PATH" if found.nil?
+        next unless version_short?(found[:version], constraint)
+
+        "#{name} #{found[:version]} does not satisfy #{constraint}"
+      end
+      missing << locale_complaint(req[:locale], env[:locale]) if locale_unmet?(req[:locale], env[:locale])
+      missing
+    end
+
+    # Whether a found command's version fails +constraint+. A missing version, an
+    # unparseable constraint, or +"*"+ all pass: presence is the requirement, and
+    # an unreadable version is not evidence of a wrong one.
+    def version_short?(version, constraint)
+      return false if version.nil? || constraint.nil? || constraint.to_s.strip == "*"
+
+      !Gem::Requirement.new(constraint.to_s).satisfied_by?(Gem::Version.new(version))
+    rescue ArgumentError
+      false
+    end
+
+    # +:utf8+ asks for any UTF-8 locale (the only case that comes up in practice);
+    # a String asks for that exact locale. An unset locale never satisfies either
+    # — that is the container default, and the bug this catches.
+    def locale_unmet?(required, actual)
+      return false if required.nil?
+      return true if actual.nil?
+
+      (required == :utf8) ? !actual.match?(/utf-?8/i) : actual != required.to_s
+    end
+
+    def locale_complaint(required, actual)
+      want = (required == :utf8) ? "a UTF-8 locale" : "locale #{required}"
+      actual.nil? ? "no locale set (needs #{want})" : "locale #{actual} is not #{want}"
+    end
+
+    public
+
     # The agent's Nexo permission mode mapped onto an opt-in backend's own
     # permission vocabulary (see PERMISSION_MODE_MAP). Consumed by
     # Loops::AgentSDK; the default Loops::RubyLLM does its gating inside the
@@ -336,7 +468,7 @@ module Nexo
       texts = []
       texts << @instructions if @instructions
       texts << @sandbox.instructions if @sandbox.instructions
-      self.class.skills.each { |name| texts << Skills.find(name).content }
+      self.class.skills.each { |name| texts << skill_instructions(Skills.find(name)) }
 
       texts.each_with_index do |text, i|
         chat = chat.with_instructions(text, append: i.positive?)
@@ -344,6 +476,32 @@ module Nexo
       chat
     end
 
+    # One skill's contribution to the system prompt: its body, plus its
+    # +compatibility:+ frontmatter when set.
+    #
+    # +compatibility:+ is the Agent Skills spec's own field for what a skill needs
+    # in order to run ("requires a Ruby interpreter and a UTF-8 locale"), and it is
+    # free text by design — the spec deliberately does not make it machine-checkable.
+    # Nexo parsed it and then dropped it, so the one place an author can state a
+    # requirement never reached the model. That matters now that a skill can ship a
+    # script Nexo stages into a sandbox (Skills.materialize): the environment is no
+    # longer the author's machine, and the model is the one deciding whether to run
+    # the thing.
+    #
+    # Labelled rather than concatenated, so the model can tell a requirement from an
+    # instruction. Absent or blank +compatibility:+ contributes nothing, leaving the
+    # prompt byte-for-byte as before for every skill that does not set it. +license:+
+    # and +allowed-tools:+ are deliberately NOT surfaced: the first is prompt noise,
+    # and the second would be a second source of truth about what an agent may do,
+    # competing with Nexo::Permissions, which is the real gate.
+    def skill_instructions(skill)
+      body = skill.content.to_s
+      compat = skill.compatibility.to_s.strip if skill.respond_to?(:compatibility)
+      return body if compat.nil? || compat.empty?
+
+      "#{body}\n\nCompatibility: #{compat}".strip
+    end
+
     # Lazily connects the declared MCP servers and attaches their tools, each
     # wrapped in a MCP::GatedTool so every invocation is authorized through this
     # agent's Permissions first. Attached after the four sandbox tools and the
@@ -360,11 +518,49 @@ module Nexo
 
       @mcp_clients ||= self.class.mcp.map { |cfg| Nexo::MCP.build(**cfg) }
       gated = @mcp_clients.flat_map(&:tools).map do |tool|
-        Nexo::MCP::GatedTool.new(tool: tool, permissions: @permissions)
+        wrap_mcp_tool(Nexo::MCP::GatedTool.new(tool: tool, permissions: @permissions))
       end
       chat.with_tools(*gated) unless gated.empty?
     end
 
+    # Applies Nexo.config.tool_concurrency to the chat, LAST — every +with_tools+ call
+    # resets the chat's concurrency to its current value, so setting it before the
+    # tools are attached would be undone. +nil+ leaves RubyLLM's own setting alone.
+    def apply_tool_concurrency(chat)
+      mode = Nexo.config.tool_concurrency
+      return if mode.nil?
+      return unless chat.respond_to?(:with_tools)
+
+      chat.with_tools(concurrency: mode)
+    end
+
+    # Hook: called once per MCP tool, AFTER it is wrapped in a permission-gating
+    # MCP::GatedTool and before it is attached. Returns the tool to attach; the
+    # default returns it unchanged.
+    #
+    # Override to decorate every MCP tool an agent gets — capping an oversized reply,
+    # recording timings, redacting a field. A third-party MCP server's response shape
+    # is not yours to change, and its tools are attached by the harness rather than by
+    # you, so without this seam the only way in was to override the private
+    # +#apply_mcp+.
+    #
+    #   class MailAgent < Nexo::Agent
+    #     mcp :mail, transport: :stdio, command: "apple-mail-mcp"
+    #
+    #     def wrap_mcp_tool(tool)
+    #       CappedTool.new(tool: tool, max_chars: 4_000)
+    #     end
+    #   end
+    #
+    # A wrapper must keep the duck type the chat relies on — +#name+, +#description+,
+    # +#params_schema+ and +#call+. GatedTool delegates the rest through
+    # +method_missing+, so wrappers compose. Gating happens underneath, so a wrapper
+    # only ever sees an already-authorized call: wrapping cannot widen what the agent
+    # may do.
+    def wrap_mcp_tool(tool)
+      tool
+    end
+
     # Attaches a single Nexo::Tools::Fetch scoped to the agent's +fetch_allow+
     # hosts (Spec 9). Returns early when no host is declared, so an agent that never
     # calls +fetch_allow+ gets no fetch tool. Attached right after +apply_mcp+ so

data/lib/nexo/configuration.rb

@@ -25,6 +25,14 @@ module Nexo
     # which always runs its own reactor when called.
     attr_accessor :concurrency
 
+    # How RubyLLM executes MULTIPLE tool calls returned in a single assistant turn:
+    # +:fibers+ (via +async+, the same driver Nexo.concurrent uses), +:threads+, or
+    # +false+ for one at a time. +nil+ (the default) leaves RubyLLM's own setting
+    # alone, so existing behaviour is unchanged until you opt in.
+    #
+    # Distinct from #concurrency, which governs how Nexo itself runs blocking work.
+    attr_accessor :tool_concurrency
+
     # Max in-flight tasks for Nexo.concurrent fan-out (Spec 5), default +8+.
     # The single most important knob for staying under provider rate limits.
     attr_accessor :max_in_flight

data/lib/nexo/loops/ruby_llm.rb

@@ -22,10 +22,19 @@ module Nexo
       # +chat:+ lets a Nexo::Session inject the hydrated, continuing chat so the
       # loop runs over the persisted thread; left nil it builds the agent's own
       # fresh chat exactly as before — the default (no-session) path is unchanged.
+      # +max_turns+ is a BUDGET, not a hard stop. ruby_llm runs the whole tool loop
+      # inside #ask and its callbacks cannot halt it, so this loop cannot cut a run
+      # short. What it can do is COUNT the tool calls and say so: exceeding the budget
+      # emits a +:turn_limit_exceeded+ event (once) carrying the count and the limit.
+      #
+      # Previously the parameter was accepted and never read, which made it look like
+      # a safety bound it has never been. Treat it as telemetry: if you need a hard
+      # ceiling, bound the work inside your tools, or use Loops::AgentSDK whose engine
+      # enforces its own max_turns natively.
       def run(agent:, prompt:, max_turns: 25, chat: nil, &on_event)
         chat ||= agent.chat
 
-        wire_observability(chat, &on_event)
+        wire_observability(chat, max_turns: max_turns, &on_event)
 
         response = chat.ask(prompt)
         on_event&.call(:done, response)
@@ -47,20 +56,39 @@ module Nexo
       # prompt observes with its own block rather than the first one. A fresh chat
       # (the default per-prompt path) simply wires once — byte-for-byte the prior
       # behavior.
-      def wire_observability(chat, &on_event)
+      def wire_observability(chat, max_turns: nil, &on_event)
         return unless chat.respond_to?(:before_tool_call) && chat.respond_to?(:after_tool_result)
 
         chat.instance_variable_set(:@nexo_on_event, on_event)
+        chat.instance_variable_set(:@nexo_max_turns, max_turns)
+        # The count belongs to the PROMPT, not the chat: a continuing Session runs the
+        # loop repeatedly over one chat, and each prompt gets its own budget.
+        chat.instance_variable_set(:@nexo_turns, 0)
+        chat.instance_variable_set(:@nexo_turns_reported, false)
         return if chat.instance_variable_get(:@nexo_observed)
 
         chat.instance_variable_set(:@nexo_observed, true)
         chat.before_tool_call do |tc|
+          count_turn(chat)
           chat.instance_variable_get(:@nexo_on_event)&.call(:tool_call, tc)
         end
         chat.after_tool_result do |r|
           chat.instance_variable_get(:@nexo_on_event)&.call(:tool_result, r)
         end
       end
+
+      # Counts one tool call and reports the first time the budget is passed. Reported
+      # once per prompt, not per call, so a long run does not drown its own event log.
+      def count_turn(chat)
+        limit = chat.instance_variable_get(:@nexo_max_turns)
+        turns = chat.instance_variable_get(:@nexo_turns).to_i + 1
+        chat.instance_variable_set(:@nexo_turns, turns)
+        return unless limit && turns > limit
+        return if chat.instance_variable_get(:@nexo_turns_reported)
+
+        chat.instance_variable_set(:@nexo_turns_reported, true)
+        chat.instance_variable_get(:@nexo_on_event)&.call(:turn_limit_exceeded, {turns: turns, max_turns: limit})
+      end
     end
   end
 end

data/lib/nexo/sandbox.rb

@@ -60,5 +60,111 @@ module Nexo
     def mtime(path)
       nil
     end
+
+    # Commands the default #environment probe looks for. Deliberately short —
+    # each entry costs a +command -v+ plus one +--version+ when found — and
+    # extensible per call for anything else a skill's script might need.
+    PROBE_COMMANDS = %w[ruby python3 node sh].freeze
+
+    # The shape #environment always answers with, built fresh on every call.
+    # Deliberately a method and not a frozen constant: the +:commands+ Hash is
+    # mutated while parsing, and +CONST.dup+ is shallow — sharing one inner Hash
+    # let every probe accumulate into the constant, so a sandbox with no shell
+    # answered with the previous sandbox's findings. +:error+ is nil on a
+    # successful probe and carries the reason when one could not be run.
+    def self.empty_environment
+      {commands: {}, locale: nil, error: nil}
+    end
+
+    # One POSIX +sh+ script, no interpreter required on the far side, so the probe
+    # works on a busybox image. +command -v+ locates each command and a single
+    # +--version+ reports it; the format placeholder is filled by #environment.
+    PROBE_SCRIPT = <<~SH
+      printf 'locale=%%s\\n' "${LC_ALL:-${LC_CTYPE:-${LANG:-}}}"
+      for c in %<commands>s; do
+        p=$(command -v "$c" 2>/dev/null) || continue
+        v=$("$c" --version 2>/dev/null | head -1)
+        printf 'cmd=%%s\\t%%s\\t%%s\\n' "$c" "$p" "$v"
+      done
+    SH
+
+    # What this execution environment actually provides, as data:
+    #
+    #   sandbox.environment
+    #   # => { commands: { "ruby" => { path: "/usr/local/bin/ruby", version: "4.0.0" } },
+    #   #      locale: "C.UTF-8" }
+    #
+    # #instructions describes the environment *for the model*; this is the same
+    # question answered *for code*, so a caller can check before staging a skill's
+    # script rather than discovering the answer as a stack trace several turns in.
+    # A container typically has no locale at all, under which Ruby's default
+    # external encoding is US-ASCII and a bare File.read on a UTF-8 file raises —
+    # and an image can carry a full Ruby toolchain and still report no locale, so
+    # the two are reported as independent axes.
+    #
+    # Deliberately coarse: commands on +PATH+ and the locale, never packages. Gems,
+    # wheels and npm modules belong to whoever builds the image, and modelling them
+    # here would be a cross-language dependency resolver competing with the manifest
+    # every ecosystem already has.
+    #
+    # Costs one #shell round trip and is memoized for the sandbox's lifetime (0.14s
+    # on +:local+, 0.25–0.48s on a container, measured). A sandbox with no shell
+    # A sandbox with no shell (Virtual) reports empty. A probe that fails for any
+    # other reason — the container would not start, the client is unreachable —
+    # also reports empty, but carries the reason under +:error+: this is
+    # diagnostics and must never be the reason a run dies, yet "I probed and found
+    # nothing" and "I could not probe" are different answers and a caller building
+    # an error message needs to tell them apart.
+    def environment(commands: PROBE_COMMANDS)
+      @environment ||= {}
+      @environment[commands] ||= probe_environment(commands)
+    end
+
+    private
+
+    # Runs the probe and parses its output. Rescues everything: see #environment.
+    def probe_environment(commands)
+      return Sandbox.empty_environment.merge(error: "sandbox has no shell") unless supports?(:shell)
+
+      out = shell(format(PROBE_SCRIPT, commands: Array(commands).join(" ")))
+      parse_environment(out[:stdout].to_s)
+    rescue StandardError, NotImplementedError => e
+      Sandbox.empty_environment.merge(error: "#{e.class}: #{salient_line(e.message)}")
+    end
+
+    # The most useful single line of a multi-line runtime failure. Neither the
+    # first line nor a blind truncation works: a container runtime prints a
+    # progress banner first ("[1/6] Fetching image", "container start failed")
+    # and puts the actual cause last ("The volume is read only"). Prefer the last
+    # line that announces an error, else the last non-empty line.
+    def salient_line(message)
+      lines = message.to_s.lines.map(&:strip).reject(&:empty?)
+      # Written as a plain scan on purpose. The idiomatic spellings deadlock the
+      # linter — Style/ReverseFind rewrites `reverse.find` to Enumerable#rfind,
+      # which does not exist on the Ruby 3.3 floor this gem supports, and
+      # Performance/Detect rewrites `select.last` straight back to `reverse.find`.
+      line = nil
+      lines.each { |l| line = l if l.match?(/error|fail|cause/i) }
+      line ||= lines.last
+      line.to_s[0, 300]
+    end
+
+    # Turns the probe's line protocol into the #environment Hash. An empty locale
+    # line means "unset", which is the interesting case, so it maps to +nil+ rather
+    # than an empty String.
+    def parse_environment(stdout)
+      env = Sandbox.empty_environment
+      stdout.each_line do |line|
+        case line.chomp
+        when /\Alocale=(.*)\z/
+          env[:locale] = $1.empty? ? nil : $1
+        when /\Acmd=([^\t]*)\t([^\t]*)\t(.*)\z/
+          # A command that prints no version (busybox sh) still counts as present;
+          # an unreadable version is not evidence of a wrong one.
+          env[:commands][$1] = {path: $2, version: $3[/(\d+(?:\.\d+)+)/]}
+        end
+      end
+      env
+    end
   end
 end

data/lib/nexo/sandboxes/container.rb

@@ -39,6 +39,23 @@ module Nexo
       # supported local runtimes in v1.
       RUNTIMES = {docker: "docker", apple: "container"}.freeze
 
+      # What each runtime's CLI can actually express. Verified live against
+      # +container+ 1.2.2 on macOS and Docker 29.4: Apple's CLI rejects
+      # +--security-opt+ and +--pids-limit+ with "Unknown option", which aborts
+      # +container run+ before the sandbox ever starts.
+      #
+      # +writable_tmpfs+ is not about the flag being accepted — Apple accepts
+      # +--tmpfs+ — but about what it does: combined with +--read-only+ the mount is
+      # NOT writable there, so a read-only rootfs leaves no usable scratch.
+      #
+      # Anything a runtime cannot honor is reported through #hardening_gaps rather
+      # than dropped quietly: running with weaker isolation, or with a workspace you
+      # cannot write to, must be visible.
+      CAPABILITIES = {
+        docker: {security_opt: true, pids_limit: true, writable_tmpfs: true},
+        apple: {security_opt: false, pids_limit: false, writable_tmpfs: false}
+      }.freeze
+
       # The container working directory (default +/workspace+, a container path),
       # the selected +runtime+ (+:docker+ / +:apple+), and the required +image+.
       attr_reader :cwd, :runtime, :image
@@ -81,10 +98,20 @@ module Nexo
         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.
+      # Writes +content+ to +path+ (guarded) inside the container, creating parent
+      # directories first. Content travels on stdin, never interpolated into the argv,
+      # so arbitrary bytes are safe.
+      #
+      # Matches Local#write on both counts, which it previously did not: without the
+      # +mkdir+ a nested path failed with "Directory nonexistent", and because the
+      # exit status was discarded the caller was told the write had succeeded. Raises
+      # +IOError+ on failure, mirroring how #read raises +Errno::ENOENT+.
       def write(path, content)
-        exec_stdin!(content, "sh", "-c", 'cat > "$0"', guard_path(path))
+        full = guard_path(path)
+        out = exec_stdin!(content, "sh", "-c", 'mkdir -p "$(dirname "$0")" && cat > "$0"', full)
+        raise IOError, "container write failed: #{path}: #{out[:stderr].strip}" unless out[:status].zero?
+
+        full
       end
 
       # Returns the container paths matching the glob +pattern+ (guarded). Empty
@@ -120,6 +147,20 @@ module Nexo
         @cid = nil
       end
 
+      # Hardening the caller asked for that this runtime cannot express, as short
+      # human-readable strings. Empty on +:docker+. Callers that require a guarantee
+      # should check this rather than assume every runtime honors every knob.
+      def hardening_gaps
+        gaps = []
+        gaps << "--security-opt no-new-privileges is not supported by #{@runtime}" unless capable?(:security_opt)
+        gaps << "--pids-limit is not supported by #{@runtime}" if @pids_limit && !capable?(:pids_limit)
+        if @readonly_rootfs && !capable?(:writable_tmpfs)
+          gaps << "#{@runtime} --tmpfs is not writable under --read-only; " \
+                  "set readonly_rootfs: false or add a :rw bind for a writable workspace"
+        end
+        gaps
+      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).
@@ -160,11 +201,11 @@ module Nexo
         argv = [@bin, "run", "-d", "--name", @name,
           "--label", "nexo.sandbox.id=#{@name}",
           "--network", @network.to_s,
-          "--cap-drop", "ALL",
-          "--security-opt", "no-new-privileges"]
+          "--cap-drop", "ALL"]
+        argv += ["--security-opt", "no-new-privileges"] if capable?(:security_opt)
         @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 += ["--pids-limit", @pids_limit.to_s] if @pids_limit && capable?(:pids_limit)
         argv += ["--memory", @memory.to_s] unless @memory.nil?
         argv += ["--cpus", @cpus.to_s] unless @cpus.nil?
         argv += ["--user", @user.to_s] unless @user.nil?
@@ -177,6 +218,11 @@ module Nexo
         argv
       end
 
+      # Whether this runtime's CLI can express +knob+.
+      def capable?(knob)
+        CAPABILITIES.fetch(@runtime, CAPABILITIES[:docker]).fetch(knob, true)
+      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)

data/lib/nexo/sandboxes/remote.rb

@@ -25,8 +25,29 @@ module Nexo
     # default sandbox stays +:virtual+.
     class Remote < Sandbox
       # Stores any object responding to +read+/+write+/+exec+/+close+.
-      def initialize(client:)
+      #
+      # +instructions:+ describes the remote environment for the agent's system
+      # prompt — working directory, available tooling, what is writable. Local and
+      # Container derive that themselves; a remote sandbox cannot, because only the
+      # shim knows where it points. Supplying it is strongly recommended: the tier
+      # most likely to surprise a weak tool-caller is the one it knows least about.
+      def initialize(client:, instructions: nil)
         @client = client
+        @instructions = instructions
+      end
+
+      # A short, plain-text description of the execution environment. Falls back to an
+      # honest generic statement rather than +nil+, so an agent is never left assuming
+      # it runs on the host.
+      #
+      # NOTE: unlike Local and Container, +Remote+ performs NO path confinement — every
+      # path is passed to the client untouched. Confining the agent to a working
+      # directory is the client's responsibility, not Nexo's.
+      def instructions
+        @instructions ||
+          "You run inside a remote sandbox managed by an external provider. The " \
+          "working directory, available tooling, and writable paths are defined by " \
+          "that provider."
       end
 
       # Reads +path+ via the client.