nexo_ai 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e3ef801100c09633b3bc0eba7f1c5444abc3a28d39b093b3f556a6e6a193304
-  data.tar.gz: 770aa194ebef30adc05049890df4611914d9af49ce5bc37460d142dce0a5277d
+  metadata.gz: 6c12fe51de0643c44b5ede5f140d45a2c2c50b15b8f357ad0e40132bcd40034c
+  data.tar.gz: 6c98b8a0adab754ba7ea290ca2227df8f464f9a71407ad4956b6a985b5a40346
 SHA512:
-  metadata.gz: 201531d77a85255355cf77d34d0dd676843f20dee2149627226a1f9068c5b6dfcc7e9e4d92e33b357536326f35e861d9fc1d1d6230bac1e5eac5db9314e3ec75
-  data.tar.gz: aff13284d24b6465a10a34b60847d6ceece755b8d8791b688777a6ec7538d7506db82922a9e83d4382a66d3045ee45ee3a4c9eede4d2b8a37e4021e9e134a934
+  metadata.gz: 221c754bcd1d4d46bf8550c5411c95e194840b5c9de42dbf66a4035a7b5d95bdccb2fb8c5a5ade8eccf88e238e763cb59b9e97d2b40d7d92fc9aee273dfe8376
+  data.tar.gz: 337b96d65dcbfcb2d879ed2e6dc62867d1a27a768f0693e007db8a0f562de0a6e5d3d129f0092d804eb531cbac0b375b7b97731016e1551cd9d1c164bae94e05

data/CHANGELOG.md

@@ -1,5 +1,150 @@
 ## [Unreleased]
 
+## [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
+`assets/` live outside every sandbox, so an agent could not reach them; `Skills.materialize`
+stages them in through the sandbox's own `#write`, which is the one route that works on
+`:local`, `:container` and `:remote` alike. Along the way the `:apple` runtime turned out
+to be unable to start a container at all, and `Container#write` was reporting success
+while writing nothing. Verified end to end against Apple `container` 1.2.2 and Docker
+29.4.0.
+
+### Fixed
+
+- **`Container#write` creates parent directories and raises on failure.** It ran
+  `sh -c 'cat > "$0"'` and discarded the exit status, so writing a nested path into a
+  fresh workspace failed with `Directory nonexistent` while reporting success to the
+  caller. `Local#write` has always done `mkdir_p` and raised; the two now match. Staging
+  anything with a directory in its path — a skill's `scripts/render.rb` — silently
+  produced nothing on a container before this.
+- **The `:apple` runtime can start a container.** `#run_argv` passed
+  `--security-opt no-new-privileges` and `--pids-limit`, which Apple's `container` CLI
+  rejects with `Unknown option`, so `runtime: :apple` failed before any tool ran. Both
+  come from defaults, so no configuration avoided it. They are now omitted for `:apple`
+  and reported through `#hardening_gaps`.
+
+### Added
+
+- **`Nexo::Skills.materialize(name, into:)`** — copies a skill's `scripts/`, `assets/`
+  and `references/` into a sandbox so an agent can actually reach them, through the
+  sandbox's own `#write`. Returns **sandbox-relative** paths so callers can build a
+  command without knowing which tier they are on. `kinds:` narrows the copy;
+  `overwrite: false` skips files already present, for images that bake the skill in.
+- **`Container#hardening_gaps`** — hardening the caller asked for that the runtime
+  cannot honor, as human-readable strings; empty on `:docker`. Running with weaker
+  isolation than requested is now visible rather than silent. It also reports that
+  Apple's `--tmpfs` is not writable under `--read-only`, which makes the default
+  `readonly_rootfs: true` leave an `:apple` sandbox with no writable workspace.
+- **`Agent#wrap_mcp_tool(tool)`** — a hook called once per MCP tool, after gating and
+  before attachment, for decorating every MCP tool an agent gets (capping an oversized
+  reply, timings, redaction). Default returns the tool unchanged; previously the only
+  way in was overriding the private `#apply_mcp`. Gating happens underneath, so a
+  wrapper cannot widen what the agent may do.
+- **`Nexo.config.tool_concurrency`** — surfaces RubyLLM's concurrent execution of
+  multiple tool calls from one assistant turn (`:fibers` / `:threads` / `false`).
+  Defaults to `nil`, leaving RubyLLM's own setting alone, so behaviour is unchanged
+  until you opt in. Applied after every tool is attached, since each `with_tools`
+  resets it.
+- **`Sandboxes::Remote#instructions`**, with an optional `instructions:` on the
+  constructor. `Local` and `Container` describe their environment to the agent;
+  `Remote` returned `nil`, leaving the tier most likely to surprise a tool-caller the
+  one it knew least about.
+
+### Changed
+
+- **`max_turns` is now counted and reported** on `Loops::RubyLLM` instead of being
+  accepted and ignored. It still cannot halt a run — ruby_llm executes the whole tool
+  loop inside `Chat#ask` and its callbacks are observation-only — but exceeding the
+  budget now emits `:turn_limit_exceeded` with `{turns:, max_turns:}`, once per prompt.
+  Previously the parameter read as a safety bound it has never been.
+
+### Documentation
+
+- **`docs/skills.md`: bundled files are not reachable until staged.** The docs stated
+  that a skill's `scripts/`/`references/` are reached through Nexo's sandbox-backed
+  tools. They are not — a skill lives under `skills_path`, outside every sandbox, and
+  nothing bridged the two. Now documents `Skills.materialize`, the relative-path rule,
+  the ambient-environment pitfall, and the writable-space tradeoff.
+- **Apple `container` parity table filled from live runs**, replacing the previous
+  all-`unverified` placeholder. Records that `--network none` *does* work on Apple,
+  that `ps -aqf` does not exist there (Apple has `list`), and the
+  `--tmpfs`-under-`--read-only` divergence.
+- **`docs/sandboxes.md`: path confinement on `:remote` is the client's job.** `Local`
+  and `Container` raise `SecurityError` on escape; `Remote` passes paths through
+  untouched. Deliberate, but it moves a guarantee callers may rely on.
+- `docs/mcp.md` documents `wrap_mcp_tool`; `docs/concurrency.md` documents
+  `tool_concurrency` and that tools must be concurrency-safe before enabling it;
+  `docs/loops.md` documents what `max_turns` does and does not do.
+
 ## [0.8.0] - 2026-07-16
 
 Durability enhancements for workflows: a suspended run can now wake itself on a

data/docs/concurrency.md

@@ -97,4 +97,32 @@ Note that DB work under a reactor is *offloaded/pooled*, not truly fiber-async
 Nexo does not ship a fiber-native DB driver. For server setup (Falcon, the fiber
 scheduler), see the [`async` guide](https://socketry.github.io/async/).
 
+
+## Tool concurrency — several tool calls in one turn
+
+`Nexo.config.concurrency` governs how **Nexo** runs blocking work. A separate setting
+governs how **RubyLLM** executes multiple tool calls returned in a *single* assistant
+turn:
+
+```ruby
+Nexo.configure { |c| c.tool_concurrency = :fibers }   # :fibers | :threads | false | nil
+```
+
+- `:fibers` — via `async`, the same driver `Nexo.concurrent` uses.
+- `:threads` — OS threads.
+- `false` — one at a time.
+- `nil` (**default**) — leave RubyLLM's own setting alone, so behaviour is unchanged
+  until you opt in.
+
+It is applied to the chat after every tool is attached, because each `with_tools` call
+resets the chat's concurrency.
+
+This only matters when a model returns several tool calls in one turn. Tools that batch
+their own work — one call that reads twenty messages rather than twenty calls — make it
+largely moot, and are the better optimization where you control the tool.
+
+**Your tools must be safe to run concurrently before you turn this on.** Anything sharing
+a process-wide resource — a CLI that serializes on a keychain, a single connection, a
+non-reentrant client — needs its own lock regardless of this setting.
+
 ← Back to the [README](../README.md)

data/docs/loops.md

@@ -90,4 +90,31 @@ NEXO_LIVE=1 NEXO_MODEL=gemma3:12b bundle exec rake test TEST=test/live_smoke_tes
 If Gemma's tool-calling proves too weak, point `NEXO_MODEL` at a stronger model — the gem
 stays provider-neutral; only the smoke target changes.
 
+
+## `max_turns` is a budget, not a hard stop
+
+`Agent#prompt`, `Session#prompt` and `Workflow#run_agent` all take `max_turns:`. On the
+default `Loops::RubyLLM` it **cannot halt a run**: ruby_llm executes the entire tool loop
+inside `Chat#ask`, and the callbacks Nexo wires are observation-only.
+
+What it does do is count tool calls and tell you when the budget is passed:
+
+```ruby
+agent.prompt("Triage the inbox", max_turns: 10) do |type, payload|
+  warn "over budget: #{payload}" if type == :turn_limit_exceeded
+end
+# => :turn_limit_exceeded, { turns: 11, max_turns: 10 }
+```
+
+Emitted once per prompt, not per call.
+
+If you need a **hard** ceiling, the options are:
+
+- bound the work inside your own tools (a read tool that accepts at most N ids);
+- use `Loops::AgentSDK`, whose engine enforces `max_turns` natively;
+- stop the run yourself from the event block.
+
+Treat `max_turns` on the default loop as telemetry. It was previously accepted and never
+read, which made it look like a safety bound it has never been.
+
 ← Back to the [README](../README.md)

data/docs/mcp.md

@@ -141,4 +141,30 @@ deny-all). Attaching an authenticated server adds no permission surface.
 server. Without it installed, `require "nexo"` still loads; building a server raises a clear
 `Nexo::MissingDependencyError` telling you to add `gem "ruby_llm-mcp"`.
 
+
+## Decorating MCP tools
+
+`wrap_mcp_tool` is called once per MCP tool, after it is wrapped in a permission-gating
+`MCP::GatedTool` and before it is attached. Override it to decorate every MCP tool an
+agent gets — a third-party server's response shape is not yours to change, and its tools
+are attached by the harness rather than by you:
+
+```ruby
+class MailAgent < Nexo::Agent
+  mcp :mail, transport: :stdio, command: "apple-mail-mcp"
+
+  # This server returns an entire message body with no cap; bound it.
+  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** the wrapper, so it only ever sees an already-authorized
+call. Wrapping cannot widen what an agent may do.
+
 ← Back to the [README](../README.md)

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
@@ -138,6 +217,30 @@ Nexo ships **only** `Remote` plus this documented pattern — purpose-built
 `Sandboxes::E2B` / `Sandboxes::Daytona` classes are a possible future addition, deliberately
 left out of v1 because their vendor client APIs aren't pinned yet.
 
+### Path confinement is the client's job
+
+`Local` and `Container` confine every `read`/`write`/`glob` to their working directory and
+raise `SecurityError` on escape. **`Remote` does not.** It passes each path to the injected
+client untouched, because only the provider knows what its own boundary is.
+
+That is deliberate — Nexo re-implementing a confinement it cannot enforce would be
+theatre — but it moves a guarantee you may be relying on. A shim is responsible for:
+
+- rejecting paths that escape the session's working directory;
+- deciding what `write` does with a missing parent directory (`Local` creates it,
+  `Container` creates it — a shim should too, or say that it does not);
+- raising on failure rather than returning a non-zero status the caller may ignore.
+
+Give the shim an `instructions:` describing the environment, too — `Remote` cannot derive
+one, and an agent told nothing about where it runs will assume it is on the host:
+
+```ruby
+Nexo::Sandboxes::Remote.new(
+  client: my_client,
+  instructions: "You run in an E2B sandbox, cwd /home/user. Ruby 3.4 is available."
+)
+```
+
 ## Container sandbox — Docker / Apple Container
 
 `Sandboxes::Container` runs an agent's tools inside a **throwaway OCI container** via the
@@ -161,12 +264,50 @@ the host dir enters only through a `binds:` entry.
 
 `sandbox :docker` (or `runtime: :docker`) shells out to `docker`; `sandbox :apple`
 (`runtime: :apple`) shells out to Apple's `container` binary. The `run`/`exec` surface is
-largely shared; where the CLIs diverge (networking especially) the class branches on the
-runtime. **Apple `container` parity is NOT yet verified** — the flags are encoded from the
-reference mapping, not confirmed against a live daemon, so every Apple flag must be verified
-before trust (the networking flag in particular; see the parity table below). An unknown
+largely shared; where the CLIs diverge the class branches on the runtime. An unknown
 runtime raises `Nexo::ConfigurationError`.
 
+**Apple `container` parity is now verified** against `container` 1.2.2 on macOS. Three
+flags docker accepts are rejected outright, so they are omitted for `:apple`:
+
+| Knob | `:docker` | `:apple` |
+|---|---|---|
+| `--security-opt no-new-privileges` | applied | **rejected** (`Unknown option`) — omitted |
+| `--pids-limit` | applied (`512`) | **rejected** (`Unknown option`) — omitted |
+| `--read-only` + `--tmpfs <cwd>:rw` | scratch is writable | flags accepted, but **the scratch is NOT writable** |
+
+Everything else — `--network` (including `none`), `--cap-drop ALL`, `--memory`,
+`--cpus`, `--user`, `-v` binds, `-e` env, `-w`, `exec -i` — is honored identically.
+
+> **`readonly_rootfs: true` is the default, and on `:apple` it leaves you with no
+> writable workspace.** Apple accepts `--tmpfs /workspace:rw` but under `--read-only`
+> the mount is still read-only, so every `write` fails. Pass `readonly_rootfs: false`,
+> or mount a `:rw` bind, when using the `:apple` runtime.
+
+Because omitting a hardening flag means *weaker isolation than you asked for*, the
+difference is reported rather than hidden:
+
+```ruby
+sandbox = Nexo::Sandboxes::Container.new(image: "…", runtime: :apple, network: :none)
+sandbox.hardening_gaps
+# => ["--security-opt no-new-privileges is not supported by apple",
+#     "--pids-limit is not supported by apple",
+#     "apple has no 'none' network; using 'default' instead"]
+```
+
+`hardening_gaps` is empty on `:docker`. If your threat model requires one of those knobs,
+check it and refuse rather than assuming every runtime honors every flag.
+
+Two practical notes for Apple `container`:
+
+- It resolves its **init image through the keychain** and fails in a non-interactive
+  shell (`errSecAuthFailed`, status `-25293`). Pinning an already-pulled tag avoids the
+  lookup: `container run --init-image ghcr.io/apple/containerization/vminit:<tag> …`.
+- Containers are **VM-backed**, so infrastructure failures surface differently — e.g.
+  `no available interface strategy for network default, plugin=container-network-vmnet`
+  when the network service needs restarting (`container system stop && container system
+  start`).
+
 ### Hardened by default — every knob an explicit opt-out
 
 All of the following are applied to the `run` argv by default and individually invertible:
@@ -239,9 +380,9 @@ The container starts **lazily** on first tool use and its id is memoized.
   `:rw` bind (this is where staged files and artifacts land).
 - **Non-root is recommended, not forced.** The default hardening holds regardless of uid; set
   `user:` for defense-in-depth.
-- **Apple `container` parity is NOT yet verified** — especially networking. Every Apple flag
-  in the parity table below is UNVERIFIED; confirm the flag/subcommand against Apple's CLI
-  before trusting the `:apple` runtime in production.
+- **Apple `container` needs `readonly_rootfs: false`.** The default read-only rootfs makes the
+  `--tmpfs` scratch unwritable on Apple, so an agent cannot write to its own workspace. The
+  parity table below records what was verified.
 - **Reconnect is Docker-only today.** `reconnect: true` combined with `runtime: :apple` raises
   `Nexo::ConfigurationError` at the point reconnect would run. Apple's `container` CLI has no
   **live-verified** exact `label=` filter, and a name-substring match is unsafe (it can attach
@@ -251,40 +392,35 @@ The container starts **lazily** on first tool use and its id is memoized.
 
 #### Apple `container` parity table (Group 0)
 
-This table is filled **only** from live Group 0 runs against a real Apple `container` runtime —
-never from assumption. Apple's runtime is macOS-only and is **not** present in CI (or in the
-environment this spec shipped from), so the divergences below are **UNVERIFIED** and marked as
-such. Until a maintainer runs Group 0 on Apple hardware and records the results here, treat the
-`:apple` runtime as **Docker-flag-shaped but unconfirmed** and reconnect as unsupported (it
-raises). Do not silently trust any Apple hardening flag until its row reads `same`.
+Filled from live Group 0 runs against **Apple `container` 1.2.2 on macOS (arm64)** and
+**Docker 29.4.0**, image `ubuntu:24.04`. Rows marked _unverified_ have not been run.
 
 | Subcommand / flag | Docker | Apple `container` | Divergence → action |
 |---|---|---|---|
-| `run -d` | ✓ | _unverified_ | verify before trust |
-| `exec -i` | ✓ | _unverified_ | verify before trust |
-| `ps -aqf` | ✓ | _unverified_ | verify before trust |
-| `start <id>` | ✓ | _unverified_ | verify before trust |
-| `rm -f <id>` | ✓ | _unverified_ | verify before trust |
-| `--label` / `label=` filter | ✓ (exact) | _unverified_ | **reconnect raises `ConfigurationError` until confirmed** |
-| `--network` | ✓ | _unverified_ | expected to diverge — verify before trust |
-| `--tmpfs` | ✓ | _unverified_ | verify before trust |
-| `--read-only` | ✓ | _unverified_ | verify before trust |
-| `--cap-drop` / `--cap-add` | ✓ | _unverified_ | verify before trust |
-| `--security-opt no-new-privileges` | ✓ | _unverified_ | verify before trust |
-| `--pids-limit` | ✓ | _unverified_ | verify before trust |
-| `-w` / `-v` / `-e` / `--user` / `--memory` / `--cpus` | ✓ | _unverified_ | verify before trust |
-
-Keep-alive (Docker, Group 0): `tail -f /dev/null` holds Alpine / Debian-slim / ruby-slim open —
-**to be confirmed on the maintainer's live daemon** (busybox-portable by construction; `sleep
-infinity` is not and was replaced for exactly this reason).
-
-> **Reduced-guarantee posture.** Where a hardening flag turns out to have no Apple equivalent,
-> the container stays functional but the guarantee is **reduced** — and that reduction is
-> documented here, never silently dropped. Until the table above is filled from a live run, a
-> maintainer must not assume any given `:apple` hardening flag is honored.
-
-Live container runs are exercised by `NEXO_LIVE`-gated smoke
-(`test/sandboxes/container_live_test.rb`); the core suite asserts argv construction with no
-daemon. See `examples/container_review.rb` for a runnable end-to-end example.
+| `run -d` | ✓ | ✓ | same |
+| `exec -i` (stdin reaches the process) | ✓ | ✓ | same — this is what `#write` uses |
+| `stop` / `start <id>` | ✓ | ✓ | same |
+| `rm -f <id>` | ✓ | ✓ | same |
+| `ps -aqf label=` | ✓ (exact) | ✗ `Plugin 'container-ps' not found` | Apple has `list`, not `ps` → **reconnect raises `ConfigurationError`** |
+| `--network` (incl. `none`) | ✓ | ✓ | same — `--network none` runs |
+| `--cap-drop ALL` | ✓ | ✓ | same |
+| `--read-only` | ✓ | ✓ | rootfs is read-only on both |
+| `--tmpfs <cwd>:rw` | ✓ writable | ✗ **not writable under `--read-only`** | → omit `--read-only` (`readonly_rootfs: false`) or use a `:rw` bind |
+| `--security-opt no-new-privileges` | ✓ | ✗ `Unknown option` | → omitted for `:apple`, reported in `#hardening_gaps` |
+| `--pids-limit` | ✓ | ✗ `Unknown option` | → omitted for `:apple`, reported in `#hardening_gaps` |
+| `-v host:ctr:ro` | ✓ | ✓ | same |
+| `-e KEY=val` | ✓ | ✓ | same |
+| `-w <dir>` | ✓ | ✓ | same |
+| `--user` | ✓ | ✓ | same |
+| `--memory` / `--cpus` | ✓ | ✓ | same |
+
+Two operational notes for Apple, both hit during verification:
+
+- It resolves its **init image via the keychain** and fails in a non-interactive shell
+  (`errSecAuthFailed`, `-25293`). Pin an already-pulled tag to skip the lookup:
+  `--init-image ghcr.io/apple/containerization/vminit:<tag>`.
+- Containers are **VM-backed**, so infrastructure failures look unfamiliar — e.g.
+  `no available interface strategy for network default, plugin=container-network-vmnet`,
+  cleared by `container system stop && container system start`.
 
 ← Back to the [README](../README.md)

data/docs/skills.md

@@ -57,12 +57,91 @@ 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
 Nexo deliberately does not attach `ruby_llm-skills`' progressive-disclosure tool (which
-reads files outside the sandbox). The model reaches a skill's `references/`/`scripts/`
-files through Nexo's own permission-gated, sandbox-backed tools — so **attaching a skill
-never widens what an agent can do** beyond its configured sandbox/permission mode.
+reads files outside the sandbox) — so **attaching a skill never widens what an agent can
+do** beyond its configured sandbox/permission mode.
+
+## Bundled files are not reachable until you stage them
+
+A skill's `scripts/`, `assets/` and `references/` live under `skills_path`, which is
+**outside every sandbox**. Sandboxes confine file access to their own working directory
+(`Local` and `Container` raise `SecurityError` on escape), so an agent cannot read or run
+a skill's bundled files just because the skill is attached.
+
+`Skills.materialize` copies them in, through the sandbox's own `#write` — the only route
+that works on every tier:
+
+```ruby
+staged = Nexo::Skills.materialize(:dashboard_designer, into: agent.sandbox)
+# => { scripts: ["scripts/render_dashboard.rb"],
+#      assets:  ["assets/dashboard-template.html"] }
+```
+
+They are then ordinary workspace files, reached through the permission-gated `read`,
+`glob` and `shell` tools like anything else in the workspace — and the returned paths are
+**sandbox-relative**, so you can build a command without knowing which tier you are on:
+
+```ruby
+agent.prompt("Run: ruby #{staged[:scripts].first} digest.json #{staged[:assets].first} out.html")
+```
+
+`Local` writes to the filesystem, `Container` streams over `docker exec` / `container
+exec`, and `Remote` hands off to the injected client. The call is identical.
+
+| Option | Meaning |
+|---|---|
+| `kinds:` | which of `scripts` / `assets` / `references` to copy (default: all three) |
+| `overwrite:` | `false` skips files already present — what you want against an image that bakes the skill in |
+
+Kinds the skill ships nothing for are omitted from the result.
+
+Two things to get right:
+
+- **Use relative paths** (`"scripts/render.rb"`), in the write and in any command you
+  hand the agent. A host-absolute path is meaningless inside a container and on a remote
+  sandbox.
+- **A bundled script must not depend on ambient environment.** It runs wherever the
+  sandbox is, which may have no locale (Ruby then defaults to `US-ASCII`, and reading a
+  UTF-8 file raises `Encoding::InvalidByteSequenceError`), a different `PATH`, or no
+  interpreter at all. Be explicit — `File.read(path, encoding: "UTF-8")` — and document
+  which interpreter your skill needs.
+
+Staged files land in **writable** space. If the agent also holds `:shell` it can rewrite a
+script before running it — where the same file, left outside the sandbox, could not be
+touched at all. `materialize` overwrites by default, so re-materializing at the start of
+every run bounds tampering to a single turn. If that is not enough, keep the resource out
+of the sandbox and feed the agent its contents another way.
 
 ← Back to the [README](../README.md)