nexo_ai 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af80f73909a7207f4414d45ae28de58bd36555e8aa186f27a7d76b93b6d6ac85
-  data.tar.gz: 91efdbb90334708bc98ddfa099bf1d74f87424fdb6a29bdb0dd83ec6a326e844
+  metadata.gz: 8815820e94035d1d5c68defa4e862111c95572852098b735e885eaf98b6a3407
+  data.tar.gz: 57ca3d98c0d1acd6877276e9322715a7e003928b2da258866b1e7ccabcf33b29
 SHA512:
-  metadata.gz: 985b074e6c59e6e5aa2353beef2fd14890efceb5f8cd20d7c3611ced5861f3fdf7a086a12b67a90ba2fbd8358c5288ac3c1e774bb3c2bb512a0868f2cc053b75
-  data.tar.gz: '091eff209c74596c4acb2b767182c21fd7f717416fc8a8ef9b3150e245b65d11ab185d8eb546d63dd508d36f7e81faced7c182fcd26fcbe3ad2998561e06965f'
+  metadata.gz: 8ad1a55220bcddd2ea1e2d06ea2bc2c680ae4f2a52c1cd8f24e0942f66ad38e38c6b1dc992fcc766b720400083bb07b500feaae9285fbb671e203bfa3f46e0f4
+  data.tar.gz: cea3ce8167dae3b4e44a5d87c84e42f04a333c7cd7e5aae8ad236133b821ba10fd3688e63851035d2c1b494b9c533807fa29bfbfd1c3439ed8c8ce6473fe1e52

data/CHANGELOG.md

@@ -1,5 +1,90 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-20
+
+Durable workflows without a database.
+
+### Added
+
+- `Nexo.config.run_store` — set a store instance and it wins over the automatic
+  choice (ActiveRecord under Rails, in-memory otherwise).
+- `Nexo::RunStore::Disk` — a file-backed store, one JSON document per run under a
+  directory, written atomically (temp file + rename). This is what makes `checkpoint`,
+  `suspend!`/`resume` and a run's recorded artifacts available to a host with no
+  database: all of them read state back from the store, and the in-memory one dies
+  with the process. `Disk::Run` subclasses `Memory::Run`, so the run shape and every
+  read helper are shared and host code behaves identically on either store. `#all`
+  lists the directory newest-first. `claim_for_resume!` re-reads from disk so a stale
+  copy cannot win a claim; it is atomic within a process, not across machines.
+
+## [0.9.0] - 2026-08-20
+
+Skills and sandboxes learn to talk about the environment, and an agent's output finally
+survives its sandbox. A skill can state what it needs (`compatibility:`, which was parsed
+and then dropped), a sandbox can report what it has (`Sandbox#environment`), and an agent
+can require the two to match before the first turn. Separately, an agent's declared output
+is now collected before teardown — a workflow releases its sandbox on **every** terminal
+path, `suspended` included, so pausing for a human approval used to destroy everything the
+run had produced on a container tier while the identical code on `:local` kept it. Along
+the way `Workflow#artifact` turned out never to have worked outside `:virtual`. Verified
+end to end against Docker 29.4.0 and Apple `container` 1.2.2.
+
+### Added
+
+- **A skill's `compatibility:` frontmatter now reaches the model.** `apply_instructions`
+  passed only `skill.content`, so `compatibility:` — the Agent Skills spec's own field for
+  stating what a skill needs in order to run — was parsed and then dropped. It is now
+  appended to the skill's body as a labelled `Compatibility: …` line. Skills that do not
+  set it contribute exactly their body, byte for byte, as before. `license:` and
+  `allowed-tools:` stay unsurfaced on purpose: 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`.
+- **`Sandbox#environment` — a sandbox can report what it actually provides.** One POSIX
+  `sh` round trip returns the commands on `PATH` (with versions) and the locale, memoized
+  for the sandbox's lifetime and extensible per call. It never raises: a shell-less
+  sandbox and a probe that could not run both answer empty, carrying the reason under
+  `:error`, because "there is no ruby" and "I never got to look" have different fixes.
+  Deliberately coarse — commands and locale, never packages.
+- **`requires` on an agent, checked before the first turn.**
+  `requires commands: {"ruby" => ">= 3.1"}, locale: :utf8` raises `Nexo::EnvironmentError`
+  listing every unmet requirement at once, instead of letting the run reach
+  `sh: ruby: not found` several turns in. Declaring nothing is the default and costs no
+  probe. Motivating case: a container has **no locale even when it has a full toolchain**,
+  under which Ruby's default external encoding is `US-ASCII` and a bare `File.read` on a
+  UTF-8 file raises — measured on Docker and Apple `container` alike.
+- **`Nexo::EnvironmentError`** (a `ConfigurationError`) for the above: the fix is in the
+  image or the sandbox wiring rather than in the Ruby.
+- **`produces` on an agent, collected into the run before the sandbox dies.** An agent
+  declares the artifacts it writes (`produces "dashboard.html", "out/*.json"` — many per
+  agent, globs allowed) and `run_agent` copies them out and records them on the run the
+  moment the agent finishes, **including when it suspended for approval or raised**. A
+  workflow releases its sandbox on every terminal path and `Container#close` is `rm -f`,
+  so before this a durable-approval pause destroyed everything the run had produced, while
+  the identical code on `:local` kept it. Verified end to end through real ephemeral
+  containers on Docker 29.4.0 and Apple `container` 1.2.2.
+- **`Workflow#artifact(name, path:)`** — a verbatim third mode. `from:` renders ERB and is
+  documented as trusted templates only, which agent output can never be; `path:` copies
+  sandbox bytes with no rendering. Non-UTF-8 bytes are Base64-wrapped so they survive a
+  JSON column; `Workflow.artifact_body(art)` decodes.
+- **`Workflow#restore_artifacts`** — materializes recorded artifacts back into the run's
+  sandbox, so a later stage can read what an earlier one produced even on an ephemeral
+  tier. The missing counterpart to `Skills.materialize`.
+
+### Fixed
+
+- **`Workflow#artifact` wrote to an absolute `/artifacts/<name>`, which every real sandbox
+  rejects.** `Local#absolute` and `Container#guard_path` both raise
+  `SecurityError: path escapes sandbox`, so the feature only ever worked on `:virtual`,
+  whose in-memory paths are unguarded. The copy is now workspace-relative
+  (`artifacts/<name>`) and resolves under the root on all four tiers.
+
+### Changed
+
+- **The in-sandbox copy of an artifact moved from `/artifacts/<name>` to
+  `artifacts/<name>`**, relative to the sandbox root. Visible only to `:virtual` users —
+  the only ones for whom `#artifact` worked at all — and only if they read the copy back
+  by absolute path. The recorded `run.artifacts` data is unchanged.
+
 ## [0.8.1] - 2026-08-19
 
 Sandbox tiers made honest and skill resources made usable. A skill's `scripts/` and

data/docs/sandboxes.md

@@ -94,6 +94,85 @@ scope; none widens authority silently.
   )
   ```
 
+## Ask a sandbox what it has — `#environment`
+
+`#instructions` describes the execution environment *for the model*. `#environment`
+answers the same question *for code*, in one `#shell` round trip:
+
+```ruby
+sandbox.environment
+# => { commands: { "ruby" => { path: "/usr/local/bin/ruby", version: "4.0.0" } },
+#      locale: "C.UTF-8",
+#      error: nil }
+```
+
+It exists because a skill's script runs wherever the sandbox is, which is not the machine
+it was written on. Measured on three real sandboxes:
+
+| Sandbox | Probe | `locale` | Commands found |
+|---|---|---|---|
+| `:local` (host) | 0.14s | `en_US.UTF-8` | ruby 4.0.0, python3 3.14.5, node 26.3.0 |
+| `:docker alpine:latest` | 0.25s | **none** | sh only |
+| `:docker` full image (~5 GB) | 0.50s | **none** | ruby 4.0.0, python3 3.12.3, node 26.7.0 |
+| `:apple` full image | 1.84s | **none** | ruby 4.0.0, python3 3.12.3, node 26.4.0 |
+
+Note the last three rows: **a container has no locale even when it has a full toolchain.**
+Under an unset locale Ruby's default external encoding is `US-ASCII`, and a bare
+`File.read` on a UTF-8 file raises `Encoding::InvalidByteSequenceError`. "Has the
+interpreter" and "can read a UTF-8 file" are independent, so they are reported separately.
+
+The probe is POSIX `sh` — no interpreter needed on the far side, so it works on busybox —
+memoized for the sandbox's lifetime, and extensible per call:
+
+```ruby
+sandbox.environment(commands: %w[ruby convert])
+```
+
+**It never raises.** A sandbox with no shell (`Virtual`) and a probe that could not run
+both report empty, with the reason under `:error`:
+
+```ruby
+Nexo::Sandboxes::Virtual.new.environment[:error]
+# => "sandbox has no shell"
+```
+
+That distinction matters: "I looked and there is no ruby" and "I never got to look" have
+different fixes. An `:apple` container left on the default `readonly_rootfs: true`, for
+instance, cannot start a process at all (`The volume is read only`) — reported as an
+`:error`, not as an empty toolchain.
+
+**Scope is deliberately coarse: commands on `PATH` and the locale, never packages.** Gems,
+wheels and npm modules belong to whoever builds the image; modelling them here would be a
+cross-language dependency resolver competing with the manifest every ecosystem already has.
+
+### Declaring what an agent needs
+
+```ruby
+class Publisher < Nexo::Agent
+  skills :dashboard_designer
+  requires commands: {"ruby" => ">= 3.1"}, locale: :utf8
+end
+```
+
+Checked once, before the first turn, and it fails with every unmet requirement at once:
+
+```
+Publisher cannot run here: no ruby on PATH; no locale set (needs a UTF-8 locale).
+Provision the sandbox, or drop the `requires` declaration.
+```
+
+- `commands:` maps a command to a `Gem::Requirement` string, 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 case that actually comes up) or an exact
+  `String`.
+- Declaring nothing is the default and costs **no probe at all**.
+
+The declaration lives here, in Nexo's 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 sit together. A skill states its needs in prose through `compatibility:`, which is
+the Agent Skills spec's field for it and is aimed at a human or a model.
+
 ## Remote sandbox — bring your own container
 
 `Sandboxes::Remote` contains **zero vendor code**. It wraps any object that satisfies a

data/docs/skills.md

@@ -57,6 +57,35 @@ Without it installed, `require "nexo"` still loads; touching a skill raises a cl
 `Nexo::MissingDependencyError` telling you to add `gem "ruby_llm-skills"`. Referencing a
 skill that does not exist raises `Nexo::Error` naming the missing `SKILL.md` path.
 
+## Say what a skill needs with `compatibility:`
+
+A skill's script runs in whatever the agent's sandbox happens to be — which is not the
+machine the script was written on. A container typically has **no locale**, so Ruby's
+default external encoding is `US-ASCII` and a bare `File.read` on a UTF-8 file raises;
+it may also have no interpreter at all.
+
+`compatibility:` is the Agent Skills spec's field for saying so, and Nexo passes it to
+the model alongside the skill body:
+
+```yaml
+---
+name: dashboard-designer
+description: Render the briefing dashboard.
+compatibility: Requires a Ruby interpreter (>= 3.1) and a UTF-8 locale.
+---
+```
+
+The model sees the body, then `Compatibility: Requires a Ruby interpreter …` as a labelled
+line, so it can tell a requirement from a step. Skills that do not set the field contribute
+exactly their body, unchanged.
+
+It is **free text, by design** — the spec does not make it machine-checkable, and Nexo does
+not try to. It is documentation aimed at a human or a model, not a dependency manifest:
+provisioning the sandbox (a gem, a library, a config) is the job of whoever wires the agent
+to it, not of the skill file. `license:` and `allowed-tools:` are parsed by
+`ruby_llm-skills` but deliberately **not** surfaced — the first is prompt noise, and the
+second would compete with `Nexo::Permissions`, which is the real gate.
+
 ## Skill tools stay gated
 
 A skill contributes **instructions only**. A loaded skill ships no independent tools, and

data/docs/workflows.md

@@ -82,6 +82,34 @@ ActiveRecord when it is available and the in-memory store otherwise. The schema
 uses portable `json` columns (SQLite and PostgreSQL alike) and a UUID string
 primary key.
 
+### Durable without a database — `RunStore::Disk`
+
+The in-memory store dies with the process, and **everything durable reads state
+back from the store**: `checkpoint`, `suspend!`/`resume`, and a run's recorded
+artifacts. So for a CLI or a script — no Rails, no database, but a process that
+ends — point the store at a directory:
+
+```ruby
+Nexo.config.run_store = Nexo::RunStore::Disk.new(dir: "~/.local/state/myapp/runs")
+```
+
+One JSON document per run, rewritten whenever the run changes, written to a temp
+file and renamed so a crash cannot leave a truncated document behind. The run shape
+and every read helper are Memory's — `Disk::Run` subclasses it — so host code
+written against one store behaves identically on the other. `#all` lists the
+directory newest-first, which is what a host wants for *"what did the last run
+produce?"*.
+
+A configured store wins over the automatic choice, including under Rails.
+
+**Scope, honestly.** Rewriting the whole document per change suits the run sizes this
+is meant for (a CLI's own history) and is wrong for a busy multi-worker queue — that
+is what the ActiveRecord backend is for. `claim_for_resume!` re-reads from disk, so a
+stale in-memory copy cannot win a claim, but it is atomic **within** a process only.
+Runs are never pruned: retention is the host's policy and `dir` is a plain directory
+it can manage. `Workflow.reconcile_interrupted!` sweeps the Memory and ActiveRecord
+stores only.
+
 ## Input staging and artifacts
 
 A run owns a **sandbox** — declared with the `sandbox` class macro (default
@@ -115,7 +143,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 +178,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,
@@ -255,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
@@ -337,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?)
@@ -345,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

data/lib/nexo/configuration.rb

@@ -57,6 +57,14 @@ module Nexo
     # this only gates the opt-in Turbo mirror.
     attr_accessor :broadcast_events
 
+    # The run store Workflow persists runs through, default +nil+ → the automatic
+    # choice (ActiveRecord under Rails, in-memory otherwise). Set an instance to
+    # override, which is what a host outside Rails needs for anything durable:
+    # checkpoint/suspend/resume all read state back from the store, and the
+    # in-memory one dies with the process. +Nexo::RunStore::Disk.new(dir:)+ is the
+    # shipped answer for a CLI or a script.
+    attr_accessor :run_store
+
     # The ActiveJob queue Workflow.run_later enqueues onto (Spec 11 R1), default
     # +nil+ → ActiveJob's default queue. Set to a symbol (e.g. +:nexo+) to route
     # workflow jobs to a dedicated queue.
@@ -74,6 +82,7 @@ module Nexo
       @buffer_workflow_events = false
       @session_chat_model = "Chat" # ruby_llm's own default acts_as_chat host
       @broadcast_events = false # safe default: opt in to the Turbo mirror
+      @run_store = nil # nil → the automatic choice (ActiveRecord under Rails, else Memory)
       @job_queue = nil # nil → ActiveJob's default queue
     end
 

data/lib/nexo/run_store.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "json"
+require "fileutils"
+
 module Nexo
   # Storage seam for Workflow runs. Two interchangeable backends expose an
   # identical create/find interface and return run objects responding to the
@@ -11,11 +14,19 @@ module Nexo
   # +push_event(event)+, +save_events!+, +push_artifact(artifact)+,
   # +save_artifacts!+, and +save_state!+ (Spec 13).
   module RunStore
-    # Selects a backend: the ActiveRecord store when both ::ActiveRecord::Base
-    # and Nexo::WorkflowRun are defined (the Rails path), otherwise the in-memory
-    # store. With no Rails loaded the AR check short-circuits, so the plain-Ruby
-    # path never references ActiveRecord.
+    # Selects a backend: +Nexo.config.run_store+ when a host set one, else the
+    # ActiveRecord store when both ::ActiveRecord::Base and Nexo::WorkflowRun are
+    # defined (the Rails path), otherwise the in-memory store. With no Rails loaded
+    # the AR check short-circuits, so the plain-Ruby path never references
+    # ActiveRecord.
+    #
+    # The configured store wins over both, which is the only way a non-Rails host
+    # gets durability: everything that survives a process — checkpoint, suspend,
+    # resume, a run's recorded artifacts — is read back from the store, and Memory
+    # dies with the process. See Disk.
     def self.default
+      return Nexo.config.run_store if Nexo.config.run_store
+
       if defined?(::ActiveRecord::Base) && defined?(Nexo::WorkflowRun)
         ActiveRecord.new
       else
@@ -158,5 +169,137 @@ module Nexo
           .update_all(status: "running") == 1
       end
     end
+
+    # File-backed backend for a host with no database: one JSON document per run
+    # under +dir+, rewritten whenever the run changes. This is what makes durability
+    # available outside Rails — checkpoint, suspend/resume and a run's recorded
+    # artifacts all read state back from the store, and Memory dies with the process.
+    #
+    #   Nexo.config.run_store = Nexo::RunStore::Disk.new(dir: "~/.local/state/myapp/runs")
+    #
+    # The Run is Memory's, subclassed: the shape and every read helper are shared, so
+    # a host written against one store behaves identically on the other. Only the
+    # +save_*+ hooks differ — they write the document. +push_event+/+push_artifact+
+    # deliberately do NOT, because Workflow always calls the matching +save_*+ right
+    # after, and persisting twice would double the writes for nothing.
+    #
+    # Scope, honestly: rewriting the whole document per change is fine for the run
+    # sizes this is meant for (a CLI's own history) and wrong for a busy multi-worker
+    # queue — that is what the ActiveRecord backend is for. +claim_for_resume!+ is
+    # atomic within a process but NOT across processes; two machines resuming the
+    # same run concurrently is out of scope. Runs are never pruned here: retention is
+    # the host's policy, and +dir+ is a plain directory it can manage.
+    class Disk
+      # A Memory::Run that writes itself to +path+ whenever Workflow saves it.
+      class Run < Memory::Run
+        # Absolute path of this run's JSON document. Assigned by the store.
+        attr_accessor :path
+
+        # The three save hooks Workflow calls after mutating a run. Memory's are
+        # no-ops because the Struct already holds everything; here they are the
+        # whole point.
+        def save_events! = persist!
+
+        # Writes the run after Workflow appended an artifact.
+        def save_artifacts! = persist!
+
+        # Writes the run after Workflow stored checkpoint/suspend state.
+        def save_state! = persist!
+
+        # Assigns attributes (Memory's behaviour) and writes the run.
+        def update!(attrs)
+          super
+          persist!
+        end
+
+        # Writes the document atomically — a temp file in the same directory, then
+        # a rename — so a crash mid-write cannot leave a truncated run behind.
+        def persist!
+          return if path.nil?
+
+          tmp = "#{path}.#{Process.pid}.tmp"
+          ::File.write(tmp, JSON.generate(to_h.except(:path)))
+          ::File.rename(tmp, path)
+        end
+      end
+
+      # Serializes writes within the process, mirroring Memory's store-wide lock.
+      MUTEX = Mutex.new
+
+      # +dir+ is created on demand; +~+ is expanded.
+      def initialize(dir:)
+        @dir = ::File.expand_path(dir)
+      end
+
+      # The directory runs are written to.
+      attr_reader :dir
+
+      # Builds a fresh +"pending"+ Run, writes it, and returns it.
+      def create(workflow_class:, payload:)
+        run = Run.new(
+          id: Nexo.generate_run_id, workflow_class: workflow_class, status: "pending",
+          payload: payload, result: nil, error: nil, events: [], artifacts: [], state: {}
+        )
+        ::FileUtils.mkdir_p(@dir)
+        run.path = path_for(run.id)
+        run.persist!
+        run
+      end
+
+      # Reads a run back by id. A miss raises KeyError, matching Memory.
+      def find(id)
+        path = path_for(id)
+        raise KeyError, "run not found: #{id}" unless ::File.exist?(path)
+
+        hydrate(JSON.parse(::File.read(path)), path)
+      end
+
+      # Every run in the directory, newest-written first. Not part of the store
+      # contract Workflow calls — it is here because a host with a run directory
+      # inevitably wants to list it ("what did the last run produce?").
+      def all
+        return [] unless ::File.directory?(@dir)
+
+        Dir.glob(::File.join(@dir, "*.json"))
+          .sort_by { |p| -::File.mtime(p).to_f }
+          .filter_map do |p|
+            hydrate(JSON.parse(::File.read(p)), p)
+          rescue JSON::ParserError, SystemCallError
+            # A half-written or hand-edited document must not break the listing.
+            nil
+          end
+      end
+
+      # Atomically claims a +"suspended"+ run for resume, re-reading from disk so a
+      # stale in-memory copy cannot win. Within one process only — see the class
+      # note.
+      def claim_for_resume!(run)
+        MUTEX.synchronize do
+          current = find(run.id)
+          return false unless current.status == "suspended"
+
+          run.status = "running"
+          run.path ||= path_for(run.id)
+          run.persist!
+          true
+        end
+      end
+
+      private
+
+      def path_for(id) = ::File.join(@dir, "#{id}.json")
+
+      # Rebuilds a Run from its document. Missing members read as nil/empty rather
+      # than raising, so a document written by an older version still loads.
+      def hydrate(data, path)
+        run = Run.new(
+          id: data["id"], workflow_class: data["workflow_class"], status: data["status"],
+          payload: data["payload"], result: data["result"], error: data["error"],
+          events: data["events"] || [], artifacts: data["artifacts"] || [], state: data["state"] || {}
+        )
+        run.path = path
+        run
+      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/version.rb

@@ -2,5 +2,5 @@
 
 module Nexo
   # The gem version (also used as +spec.version+ in the gemspec).
-  VERSION = "0.8.1"
+  VERSION = "0.10.0"
 end

data/lib/nexo/workflow.rb

@@ -628,6 +628,9 @@ module Nexo
       pairs.size
     end
 
+    # Where #artifact drops its in-sandbox copy, relative to the sandbox root.
+    ARTIFACTS_DIR = "artifacts"
+
     # Records a named deliverable on the run (Spec 7 R3). The body comes from
     # either +content:+ (used verbatim) or +from:+ (a **trusted, developer-authored**
     # ERB template — a real disk file when +File.exist?(from)+, else a staged
@@ -637,27 +640,131 @@ module Nexo
     # file you control — NEVER model output or user-uploaded content. Templates are
     # code, not data (see README).
     #
-    # The body is written to the sandbox at +/artifacts/<name>+ (so scripts/agents
-    # can read it during the run) and recorded on the run as a string-keyed hash
+    # +path:+ is the third mode and the one for **agent output**: it copies a
+    # sandbox path VERBATIM, with no ERB and no rendering of any kind.
+    # +from:+ cannot be used for this — it evaluates the file as ERB, which is
+    # exactly what the security note above forbids for model-written content, and
+    # would corrupt any file containing +<%+ regardless. Use +path:+ for anything
+    # an agent produced; +from:+ only for templates you wrote.
+    #
+    # The body is written to the sandbox at the workspace-relative
+    # +artifacts/<name>+ (so scripts/agents can read it during the run) and
+    # recorded on the run as a string-keyed hash
     # +{"name" =>, "content" =>, "at" =>}+, matching how #emit string-keys events
-    # so Memory and the AR json column round-trip identically. Artifacts persist
-    # immediately (never buffered). Raises Nexo::Error when neither +content:+ nor
-    # +from:+ produces a body. Returns the artifact hash.
-    def artifact(name, content: nil, from: nil, locals: {})
+    # so Memory and the AR json column round-trip identically. Bytes that are not
+    # valid UTF-8 are Base64-encoded and marked +"encoding" => "base64"+, because
+    # an AR json column cannot hold arbitrary binary — see .artifact_body for the
+    # decode side. Artifacts persist immediately (never buffered). Raises
+    # Nexo::Error when no mode produces a body. Returns the artifact hash.
+    def artifact(name, content: nil, from: nil, path: nil, locals: {})
       body = content
       if from
         template = File.exist?(from) ? File.read(from) : sandbox.read(from)
         body = ERB.new(template, trim_mode: "-").result_with_hash(locals)
       end
-      raise Nexo::Error, "artifact #{name} needs content: or from:" if body.nil?
-
-      sandbox.write("/artifacts/#{name}", body)
-      art = {"name" => name.to_s, "content" => body, "at" => Time.now.utc.iso8601}
+      body = sandbox.read(path) if path
+      raise Nexo::Error, "artifact #{name} needs content:, from: or path:" if body.nil?
+
+      # Workspace-relative on purpose. This was an ABSOLUTE "/artifacts/#{name}",
+      # which every real sandbox rejects — Local#absolute and Container#guard_path
+      # both raise SecurityError ("path escapes sandbox") for a path outside the
+      # single root. #artifact therefore only ever worked on :virtual, whose
+      # in-memory paths are unguarded; on :local and :container it raised. Relative
+      # resolves under the sandbox root on all four tiers.
+      sandbox.write(File.join(ARTIFACTS_DIR, name.to_s), body)
+      art = {"name" => name.to_s, "at" => Time.now.utc.iso8601}.merge(encoded_body(body))
       @run.push_artifact(art)
       @run.save_artifacts! if @run.respond_to?(:save_artifacts!)
       art
     end
 
+    # The bytes of a recorded artifact, decoding the Base64 form when present.
+    # The counterpart to the encoding #artifact applies; use it rather than
+    # reading +art["content"]+ directly, which is Base64 text for binary.
+    def self.artifact_body(art)
+      body = art["content"].to_s
+      (art["encoding"] == "base64") ? body.unpack1("m") : body
+    end
+
+    # Copies every artifact an agent DECLARED into the run, immediately after that
+    # agent runs and before anything can tear its sandbox down.
+    #
+    # This is the missing half of Skills.materialize. That gets a skill's files
+    # INTO a sandbox; nothing got results back OUT, and on an ephemeral tier there
+    # is nowhere else for them to live: Container#close is +rm -f+, and
+    # Workflow.execute releases the run's sandbox on EVERY terminal path — done,
+    # failed, and **suspended**. So a durable-approval pause (the whole point of
+    # Spec 16) destroyed everything the run had produced up to the approval, while
+    # the identical code on +:local+ kept it, because there the sandbox is just a
+    # directory. Same workflow, durable on one tier and lossy on another, with no
+    # error either way.
+    #
+    # Declared, never inferred: a sweep of the sandbox would collect staged skill
+    # scripts, templates and scratch files, and an agent naming its outputs is also
+    # the only honest way to say "this run produced nothing". A name may be a glob
+    # (+"out/*.json"+), and an agent may declare as many as it likes. A declared
+    # artifact that does not exist is skipped rather than fatal — a run can
+    # legitimately not produce one, and this must never be what fails a run.
+    # Returns the artifacts recorded.
+    def collect_artifacts(agent)
+      # Guarded like #run_agent's +agent.close+: an injected test double or a
+      # non-Nexo::Agent duck simply declares nothing.
+      return [] unless agent.class.respond_to?(:produces)
+
+      names = agent.class.produces
+      return [] if names.empty?
+
+      names.flat_map { |name| artifact_paths(name) }.uniq.filter_map do |path|
+        artifact(File.basename(path), path: path)
+      rescue => e
+        emit(:artifact_skipped, {"path" => path.to_s, "error" => e.message})
+        nil
+      end
+    end
+
+    # Materializes previously collected artifacts back into the run's sandbox, so
+    # a later stage can read what an earlier one produced. The hand-off half: on a
+    # persistent tier stage N+1 just reads the path stage N wrote, and this makes
+    # that true on an ephemeral tier too — including across a suspend/resume, where
+    # the sandbox that held them no longer exists. Names nothing by default (every
+    # recorded artifact); pass +only:+ to restore a subset. Returns the paths written.
+    def restore_artifacts(only: nil, into: ".")
+      wanted = only && Array(only).map(&:to_s)
+      @run.artifacts.filter_map do |art|
+        name = art["name"].to_s
+        next if wanted && !wanted.include?(name)
+
+        path = File.join(into, name)
+        sandbox.write(path, self.class.artifact_body(art))
+        path
+      end
+    end
+
+    private
+
+    # Expands one declared name against the sandbox, so +produces "out/*.json"+
+    # works. A name with no glob character is taken literally and checked for
+    # existence, which keeps the common case off the glob path entirely.
+    def artifact_paths(name)
+      return sandbox.glob(name.to_s) if name.to_s.match?(/[*?\[]/)
+
+      sandbox.read(name.to_s)
+      [name.to_s]
+    rescue
+      []
+    end
+
+    # An artifact body plus, when the bytes are not valid UTF-8, the Base64
+    # envelope that lets them survive a JSON column round trip.
+    def encoded_body(body)
+      text = body.to_s
+      return {"content" => text} if text.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+
+      {"content" => [text].pack("m0"), "encoding" => "base64"}
+    end
+
+    public
+
     # Drives the workflow's declared ::agent (Spec 8), bound to *this* run's
     # sandbox (Spec 7), forwarding every +(type, payload)+ event the agent's loop
     # yields into the run log as an +agent_*+ event, and ensuring the agent is
@@ -708,6 +815,14 @@ module Nexo
       @run.save_state! if @run.respond_to?(:save_state!)
       suspend!(reason: "approval: #{a.detail}", resume_key: a.detail.to_s)
     ensure
+      # Collect BEFORE teardown, and in the ensure so it also runs when the agent
+      # suspended for approval or raised — those are the paths where the sandbox
+      # dies with results still in it. Never allowed to mask the original outcome.
+      begin
+        collect_artifacts(agent) if agent
+      rescue => e
+        emit(:artifact_skipped, {"error" => e.message})
+      end
       # Guarded so it's safe if Spec 6 (Agent#close) isn't present in the agent,
       # or if agent construction itself raised (agent is nil).
       agent.close if agent.respond_to?(:close)

data/lib/nexo.rb

@@ -30,6 +30,12 @@ module Nexo
   # no model and no configured default).
   class ConfigurationError < Error; end
 
+  # Raised when an agent's declared +requires+ are not met by the sandbox it is
+  # about to run in — no interpreter on +PATH+, or no UTF-8 locale. A
+  # configuration error in spirit, but named separately because the fix is in the
+  # image or the sandbox wiring rather than in the Ruby.
+  class EnvironmentError < ConfigurationError; end
+
   # Control-flow signal raised by the +:approve+ permission gate (Spec 16) when a
   # capability needs a human decision and none has been threaded in yet. Unlike
   # Permissions::Denied ("no, adapt" — tools rescue it into +{error:}+),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexo_ai
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Mario Alberto Chávez