nexo_ai 0.1.0 → 0.8.0

data/docs/rails.md

@@ -0,0 +1,162 @@
+# Rails
+Rails wiring: background execution with `run_later`, live progress broadcasting, and run-query helpers for a host UI.
+
+The install generator (`rails g nexo:install`) is covered in [Getting started](getting-started.md);
+the per-feature generators (`rails g nexo:workflows`, `nexo:artifacts`, `nexo:state`, `nexo:skill`)
+live with their topics in [Workflows](workflows.md), [Durable workflows](durable-workflows.md), and
+[Skills](skills.md).
+
+## Background execution — `run_later`
+
+`MyWorkflow.run_later(payload)` enqueues the run on your **existing ActiveJob
+adapter** and hands back the run **immediately** (status `"queued"`), so a
+controller can return while the work happens in the background. The job carries
+**only the run id** — the payload lives on the run record, so no arguments (and
+no secrets) travel through the queue. When the worker picks it up, it reconstitutes
+the workflow and calls the same `execute` the sync path uses, so an async run
+reaches the identical `done`/`failed` lifecycle, event log, and status
+notifications:
+
+```ruby
+class GenerateReport < Nexo::Workflow
+  def call(payload) = { url: build_report(payload[:account_id]) }
+end
+
+run = GenerateReport.run_later(account_id: 42)   # returns at once
+run.status                                        # => "queued"
+# ...the worker runs it in the background; later:
+Nexo::RunStore.default.find(run.id).status        # => "done"
+```
+
+Route jobs to a dedicated queue per call or globally:
+
+```ruby
+GenerateReport.run_later(account_id: 42, queue: :nexo)  # per-call
+Nexo.configure { |c| c.job_queue = :nexo }              # or a global default
+```
+
+### Scheduling a future run or resume
+
+`run_later` and `resume_later` accept `wait:` (a duration) or `wait_until:` (an
+absolute time), forwarded straight to **the installed ActiveJob's own**
+`.set(...)` scheduler — Nexo adds no scheduler of its own. Use them to defer an
+initial enqueue ("send this digest at 9am") or to let a suspended run wake itself
+on a timer, symmetrically:
+
+```ruby
+# Defer the initial enqueue until tomorrow morning.
+DailyDigest.run_later({account_id: 42}, wait_until: Date.tomorrow.noon)
+
+# Let a suspended run wake itself up in an hour (no separate scheduled job).
+MyWorkflow.resume_later(run.id, {reminder: true}, wait: 1.hour)
+```
+
+The run's status is unchanged — a scheduled `run_later` is still `"queued"` (no
+`"scheduled"` status is invented), and a scheduled `resume_later` leaves the run
+`"suspended"` until the job fires. Passing **both** `wait:` and `wait_until:` in
+one call raises `ArgumentError` (checked before any run is created or job
+enqueued) — the installed ActiveJob would otherwise silently keep just one. With
+neither given, the enqueue is byte-for-byte the immediate one above.
+
+> **⚠️ `wait:`/`wait_until:`/`queue:` are scheduling options, not payload.** Like
+> `queue:` already was, a bare-keyword call consumes them as options: `run_later(wait:
+> 60)` schedules the job **60 seconds out** and leaves the payload `{}` — it does
+> **not** store `"wait" => 60` as data. A payload that legitimately needs a key named
+> `"wait"` must be passed as an explicit positional Hash: `run_later({wait: "value"})`.
+
+This is still "no scheduler, no cron" — `wait:`/`wait_until:` schedule a **single**
+future run/resume via ActiveJob; recurring schedules stay the host's (see the "no
+queue and no scheduler" note below).
+
+Nexo ships **no queue and no scheduler** — ActiveJob uses whatever adapter your
+app configured (Sidekiq, GoodJob, Solid Queue, …), and scheduling (cron / GoodJob
+/ `whenever`) stays the host's. Without ActiveJob, `run_later` raises
+`Nexo::MissingDependencyError` — use `run` for synchronous execution.
+
+> **⚠️ Needs a shared store.** For a worker in **another process** to find the run,
+> use the ActiveRecord store (`rails g nexo:workflows`) with a real adapter — the
+> run must live in the database, not in a per-process memory store. The in-memory
+> store only works under the `:inline`/`:test` adapters, where the job runs
+> in-process on enqueue.
+>
+> **⚠️ No automatic crash recovery / no automatic retries.** A crashed or retried
+> job re-runs `#call` **from scratch** — Nexo adds no `retry_on` (configure retries
+> in your host job if you want them). Pair with `reconcile_interrupted!` (above) to
+> sweep runs orphaned in `"running"`. For an *intentional* pause-and-continue (a
+> human approval, an external callback), see **[Durable workflows](durable-workflows.md)** —
+> `checkpoint` skips already-paid-for work when a run resumes.
+
+## Live progress — notifications and opt-in Turbo
+
+Every run **broadcasts as it happens** over `ActiveSupport::Notifications`,
+decoupled from persistence (events still buffer/persist separately). Two
+notifications fire (a no-op with no ActiveSupport, so the plain-Ruby core stays
+Rails-free):
+
+- `nexo.workflow.event` — one per `emit`, payload `{ run_id:, event: }` (the event
+  is the string-keyed `{"type" =>, "data" =>, "at" =>}` hash). Fires **live**, even
+  when event *persistence* is buffered.
+- `nexo.workflow.status` — on each status transition, payload `{ run_id:, status: }`.
+
+The payloads carry only what `emit`/the run already hold — **no payload or
+credential dumps**. Subscribe for logging, metrics, or your own UI:
+
+```ruby
+ActiveSupport::Notifications.subscribe("nexo.workflow.event") do |*, payload|
+  Rails.logger.info("[run #{payload[:run_id]}] #{payload[:event]["type"]}")
+end
+```
+
+**Opt-in Turbo mirror.** Set `config.broadcast_events = true` (and have turbo-rails
+present) and the engine subscribes `Nexo::TurboBroadcaster`, which appends each
+event to a per-run Turbo stream, rendering the overridable partial
+`app/views/nexo/_event.html.erb`. To show live progress, add to your own page (Nexo
+ships **no** controllers, routes, or dashboard — the host owns all HTTP + UI):
+
+```erb
+<%= turbo_stream_from "nexo_run_#{@run.id}" %>
+<div id="nexo_run_<%= @run.id %>_events">
+  <%# appended events land here %>
+</div>
+```
+
+Override the appearance by defining your own `app/views/nexo/_event.html.erb` in
+the host app — it takes precedence over the engine's default (which renders
+`<div class="nexo-event">type: {data.inspect}</div>`).
+
+```ruby
+Nexo.configure { |c| c.broadcast_events = true }   # opt in; requires turbo-rails
+```
+
+> **⚠️ Broadcast reachability.** Broadcasts fire from **wherever the run executes**
+> — under `run_later`, that's the worker process. The cable backend (AnyCable,
+> Solid Cable, Redis) must therefore be reachable from your workers, not just your
+> web dynos. Nexo ships **no cable backend** — broadcasting composes whatever the
+> host configured. Without turbo-rails, `broadcast_events` is a harmless no-op:
+> the notifications still fire, so you can subscribe to them yourself.
+
+## Run helpers for a host UI
+
+`Nexo::WorkflowRun` exposes query helpers so a host can build its own runs UI
+without Nexo dictating controllers or views:
+
+```ruby
+Nexo::WorkflowRun::STATUSES  # => %w[pending queued running done failed interrupted suspended]
+
+Nexo::WorkflowRun.queued     # scope: status "queued"
+Nexo::WorkflowRun.running    # scope: status "running"
+Nexo::WorkflowRun.finished   # scope: status "done" or "failed"
+Nexo::WorkflowRun.suspended  # scope: status "suspended" (paused, awaiting resume)
+
+run.queued?  run.running?  run.done?  run.failed?  run.suspended?   # predicates
+
+# Artifact access — content only; serving files stays your
+# controller's job (Nexo ships no artifact routes/controllers):
+run.artifact("digest.md")          # => {"name" =>, "content" =>, "at" =>} or nil
+run.artifact_content("digest.md")  # => "…the body…" or nil
+```
+
+See [`examples/rails_usage.md`](../examples/rails_usage.md) for a controller +
+Turbo-page walkthrough.
+
+← Back to the [README](../README.md)

data/docs/sandboxes.md

@@ -0,0 +1,290 @@
+# Sandboxes
+The sandbox is *where* an agent's tools act — pick in-memory Virtual, host-backed Local, a throwaway Container, or a Remote you inject.
+
+Two seams compose the execution environment. The **sandbox** is *where* tools act; the
+**permission mode** is *what* they may do. A denied capability returns `{ error: ... }`
+and the agent loop continues — it does not raise. A path that escapes the workspace raises
+`SecurityError`; an agent built with no resolvable model raises `Nexo::ConfigurationError`.
+
+|                          | `:read` | `:glob` | `:write`            | `:shell`                          | `:fetch`   | `:search`  |
+| ------------------------ | ------- | ------- | ------------------- | --------------------------------- | ---------- | ---------- |
+| `:read_only` (default)   | ✅      | ✅      | ❌ `{error}`        | ❌ `{error}`                      | ❌ `{error}` | ❌ `{error}` |
+| `:auto`                  | ✅      | ✅      | ✅                  | ✅                                | ✅         | ✅         |
+| `:ask`                   | ✅      | ✅      | per `on_ask`        | per `on_ask`                      | per `on_ask` | per `on_ask` |
+| `:approve`               | ✅      | ✅      | per `decision`      | per `decision`                    | per `decision` | per `decision` |
+| `Virtual` sandbox        | ✅      | ✅      | ✅ (in-memory)      | ❌ `NotImplementedError`→`{error}` | ✅ †       | ✅ †       |
+| `Local` sandbox          | ✅ (guarded) | ✅ | ✅ (guarded)        | ✅ (narrowed ENV)                 | ✅ †       | ✅ †       |
+| `Container` sandbox      | ✅ (guarded) | ✅ | ✅ (guarded, scratch) | ✅ (in container)               | ✅ †       | ✅ †       |
+
+`:read`/`:glob` are auto-allowed under **every** mode (they sit in the default
+`allow` list), so `:ask`/`:approve` never prompt for them — only
+`:write`/`:shell`/`:fetch`/`:search` reach the gate. **†** `:fetch` and `:search`
+run in the **host process** (stdlib `net/http` / a host-injected backend), so **no
+sandbox constrains them** — not even a `--network none` container. They are bounded
+only by the capability gate above plus `fetch_allow` / the injected backend.
+
+- **`Virtual`** (default) — in-memory, zero host access. `#shell` raises
+  `NotImplementedError` on purpose: in-memory means no command execution. That is the
+  safety property, not a gap.
+- **`Local`** — host filesystem + shell, for trusted dev/CI. Two guards: every path is
+  expanded against `cwd` and must stay inside it (else `SecurityError`), and the shell sees
+  only `PATH`, `HOME`, `LANG` (plus explicit `env:` additions) — never the full process
+  environment.
+- **`Container`** — run the tools inside a throwaway local container via the `docker`
+  (default) or Apple `container` CLI. Shell-out only, no client gem. **Hardened by default**
+  (no network, dropped caps, read-only rootfs + ephemeral scratch, read-only host binds);
+  every hardening is an explicit opt-out. See [Container sandbox](#container-sandbox--docker--apple-container) below.
+- **`Remote`** — run the tools inside a remote container (E2B / Daytona / Modal / Docker /
+  your own) by injecting a client. Escalating to `:remote` is always an explicit choice in
+  your code — the default stays `:virtual`.
+
+## Safety refinements — safer, more legible real-FS sandboxes
+
+Five small refinements tighten the real-filesystem sandboxes (`Local`, `Container`) and make
+the execution environment more legible to the model. Each wires into an existing seam — no new
+sandbox tier, no new capability, no new dependency. Every one *tightens* a default or *narrows*
+scope; none widens authority silently.
+
+- **Self-describing sandbox (`Sandbox#instructions`).** A real-FS sandbox appends one plain-text
+  system message describing where the agent runs, so a weak local tool-caller (e.g. Ollama/Gemma)
+  knows its environment. `Local` → *"You run on the host machine, cwd /path/to/repo. The real host
+  filesystem and shell are reachable; file access is guarded to /path/to/repo."*; `Container` →
+  *"You run inside a docker container (image node:22-slim), cwd /workspace, network none…"*.
+  `Virtual` says nothing (`#instructions` is `nil`). Ordering in the system messages: **agent
+  instructions → sandbox instructions → skill instructions**. Provider-neutral, injected through
+  the existing `with_instructions` path.
+
+- **Capability-gated tool attach (`Sandbox#supports?`).** A `:virtual` agent no longer advertises
+  a `Shell` tool it can never run — `Agent#chat` attaches `Shell` only when
+  `@sandbox.supports?(:shell)`. `Local`/`Container` support all four capabilities; `Virtual`
+  supports everything but `:shell`. `ReadFile`/`WriteFile`/`Glob` are always attached.
+
+- **Shell output truncation (`Nexo::OutputTruncator`).** Unbounded command output (`npm install`,
+  `git log`) is truncated before it reaches the model, so a single command can't blow a small
+  context window. `Tools::Shell` wraps `stdout`/`stderr` through
+  `OutputTruncator.call(text, max_lines: 200, max_chars: 16_000)` — strips ANSI escapes, keeps the
+  **last** `max_lines` lines, appends a `…[truncated N lines]` marker, then caps at `max_chars`.
+  The integer `status` passes through untouched. Pure line/char truncation — **no tokenizer**;
+  configurable via the kwargs only (no global config, no per-agent macro).
+
+- **Read-before-write + stale guard (real-FS only).** Within a session, the agent is blocked from
+  overwriting a file it never read, or one that changed underneath it. `Agent#chat` builds one
+  `Nexo::ReadTracker` per chat and threads it into `ReadFile` (records `(path, mtime)` on a
+  successful read) and `WriteFile` (enforces): overwriting an existing, un-read file returns
+  `{error: "read <path> before overwriting it"}`; a file whose mtime changed since the read returns
+  `{error: "stale: <path> changed since you read it"}`; a new file writes freely. The guard is
+  **real-FS only** — skipped entirely on `Virtual` (nil `mtime`) and when no tracker is passed
+  (direct tool construction). Best-effort: mtime-based, so a sub-second external edit may slip past
+  the stale check (read-before-write is the primary guard). Clobber-safety within a session only —
+  no versioning, locking, or VCS semantics.
+
+- **Scoped `:ask` predicate (`ask_when`).** Under `:ask`, `Permissions.new(ask_when: ->(cap, detail)
+  { … })` scopes *which* actions actually prompt a human. When the predicate returns falsey the
+  action is auto-allowed **without** calling `on_ask`; truthy (or when `ask_when` is unset) falls
+  through to `on_ask` exactly as before. Unset = ask for everything (backward-compatible). It only
+  ever *narrows* what is auto-allowed from the "ask for everything" baseline — it never widens
+  authority, and it applies to `authorize!` only (the separate MCP ask axis is unchanged).
+
+  ```ruby
+  # Only prompt for writes under /protected; auto-allow everything else.
+  perms = Nexo::Permissions.new(
+    mode: :ask,
+    on_ask:   ->(cap, detail) { ask_the_human(cap, detail) },
+    ask_when: ->(cap, detail) { cap == :write && detail.to_s.start_with?("/protected") }
+  )
+  ```
+
+## Remote sandbox — bring your own container
+
+`Sandboxes::Remote` contains **zero vendor code**. It wraps any object that satisfies a
+four-method contract — `read`, `write`, `exec`, `close` — and delegates the `Sandbox`
+interface to it. Switching providers is swapping the injected object, nothing else:
+
+```ruby
+sandbox = Nexo::Sandboxes::Remote.new(client: my_container_client)
+# read(path)  -> client.read(path)
+# write(path, content) -> client.write(path, content)
+# shell(cmd, timeout:) -> client.exec(cmd, timeout:)
+# glob(pattern)        -> client.exec(<pattern as a positional $1, never interpolated>)
+# close                -> client.close
+```
+
+Vendor SDKs rarely expose exactly `read/write/exec/close`, so adapt them with a tiny shim
+object. Keep the vendor gem a **soft** dependency behind a lazy `require` that raises
+`Nexo::MissingDependencyError` when it's absent:
+
+```ruby
+# A ~10-line adapter wrapping a hypothetical vendor client to the four-method contract.
+class E2BAdapter
+  def initialize(api_key:)
+    require "e2b"            # soft dep — lazy, only when you actually use it
+    @sbx = E2B::Sandbox.create(api_key: api_key)
+  rescue LoadError
+    raise Nexo::MissingDependencyError, "E2BAdapter needs `gem \"e2b\"` in your Gemfile."
+  end
+
+  def read(path)            = @sbx.files.read(path)
+  def write(path, content)  = @sbx.files.write(path, content)
+  def exec(cmd, timeout: 30) = (r = @sbx.commands.run(cmd, timeout: timeout)
+                                {stdout: r.stdout, stderr: r.stderr, status: r.exit_code})
+  def close                 = @sbx.kill
+end
+
+agent = Nexo::Agent.new(model: ENV.fetch("NEXO_MODEL"),
+                        sandbox: Nexo::Sandboxes::Remote.new(client: E2BAdapter.new(api_key: ENV["E2B_API_KEY"])))
+```
+
+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.
+
+## Container sandbox — Docker / Apple Container
+
+`Sandboxes::Container` runs an agent's tools inside a **throwaway OCI container** via the
+`docker` (default) or Apple `container` CLI — shell-out only through `Open3`, **no client
+gem**, no Compose, no image builder. A model-driven agent never touches your host filesystem
+or shell directly. Declare it with the `sandbox` macro (`image:` is required — there is no
+default image):
+
+```ruby
+class ContainerReviewer < Nexo::Agent
+  model   ENV.fetch("NEXO_MODEL")
+  sandbox :docker, image: "node:22-slim",
+          binds: { Dir.pwd => { to: "/workspace/repo", mode: :ro } }
+end
+```
+
+The container `cwd` defaults to `/workspace` (a container path, **not** your host directory);
+the host dir enters only through a `binds:` entry.
+
+### `runtime:` — one class, two CLIs
+
+`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
+runtime raises `Nexo::ConfigurationError`.
+
+### Hardened by default — every knob an explicit opt-out
+
+All of the following are applied to the `run` argv by default and individually invertible:
+
+| Concern | Default | Loosen with |
+|---|---|---|
+| Network | `--network none` (no egress) | `network: :bridge` / `:host` / a network name |
+| Capabilities | `--cap-drop ALL` | `cap_add: %w[NET_BIND_SERVICE ...]` |
+| Rootfs | `--read-only` | `readonly_rootfs: false` |
+| Writable scratch | `--tmpfs <cwd>:rw` (ephemeral), only when `readonly_rootfs` | a `:rw` host bind for persistence |
+| Privilege escalation | `--security-opt no-new-privileges` | (not exposed) |
+| PIDs | `--pids-limit 512` (fork-bomb guard) | `pids_limit:` (`nil` omits the flag) |
+| Memory / CPU | unset (host decides) | `memory:` / `cpus:` |
+| User / uid | left to the image | `user:` (opt-in defense-in-depth) |
+| Host binds | **read-only** (`:ro`) | per-bind `{ to:, mode: :rw }` |
+| Env vars | none | `env: { "KEY" => "val" }` → one `-e KEY=val` per entry |
+
+Bind spec forms:
+
+```ruby
+binds: { "/host/proj" => "/workspace/proj" }                       # -> :ro
+binds: { "/host/proj" => { to: "/workspace/proj", mode: :rw } }    # -> :rw
+```
+
+**Non-root is not forced.** The image's own uid is respected; `user:` is an opt-in. The other
+hardening (`--cap-drop ALL`, `--security-opt no-new-privileges`, `--read-only`,
+`--network none`) applies **regardless of uid**.
+
+Every argument is passed to `Open3` as an **array**, never string-interpolated, so file
+contents and commands can't break out of the argv. Paths are expanded against the container
+`cwd` and a path that escapes raises `SecurityError`. A denied/failed **tool** op surfaces as
+`{ error: ... }` through the gated tool layer; the **sandbox** itself raises only on misuse —
+a missing binary (`Nexo::ConfigurationError` naming the binary), a path escape (`SecurityError`),
+or a container start failure (`Nexo::Error`).
+
+### Lifecycle — ephemeral by default, opt-in reconnect
+
+The container starts **lazily** on first tool use and its id is memoized.
+
+- **Ephemeral (default, `reconnect: false`):** `close` force-removes the container
+  (`<bin> rm -f <id>`) and clears the memo. Idempotent — safe with nothing started or called
+  twice. A standalone container-backed agent tears its container down on `Agent#close` (the
+  agent owns the sandbox it resolved). A workflow driving one through `run_agent` shares the
+  run's sandbox — `run_agent` borrows it, so teardown happens once at the end of the run in
+  `Workflow.execute`'s `ensure` (on done, suspended, or failed), never per `run_agent` call.
+- **Reconnect (`name:` + `reconnect: true`):** every container is tagged at `run` with an
+  **exact identity label** — `--label nexo.sandbox.id=<name>`. On start the sandbox looks up
+  that container by the **exact label filter** (`docker ps -aqf label=nexo.sandbox.id=<name>`),
+  **not** a name substring, and reuses/restarts it instead of creating a new one; `close`
+  leaves it running/stopped so a later sandbox with the same name reattaches. The default
+  container name is `nexo-<run-id>`.
+  - **Exact match, never a substring.** A container merely *named* `<name>x` is never
+    reattached — the label filter is exact. This closes the substring-reattach safety hole:
+    a long-lived session can never silently bind to the wrong environment.
+  - **Ambiguity raises, never guesses.** If more than one container carries the same identity
+    label, reconnect raises `Nexo::Error` (`ambiguous reconnect: <n> containers labeled
+    <name>`) rather than pick one. Zero matches falls through to a fresh `run`; a
+    daemon/CLI failure fails open to the create path.
+  - **Reconnect never crosses runtimes.** The lookup shells the runtime-specific binary and
+    each runtime keeps its own id namespace, so a `:docker` container is never reattached by an
+    `:apple` sandbox or vice versa.
+
+### Honest caveats
+
+- **Network-none breaks installs.** `npm install` / `bundle install` need egress; with the
+  default `network: :none` they fail. Pass `network: :bridge` or bake dependencies into the
+  image.
+- **Read-only rootfs needs the scratch.** With `--read-only`, only the tmpfs at `cwd` (and any
+  `:rw` bind) is writable, and the tmpfs is **ephemeral** — lost on `close`. Persist via a
+  `: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.
+- **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
+  the wrong container), so reconnect refuses rather than risk it. Use `runtime: :docker` for
+  reconnect, or run an ephemeral `:apple` sandbox (`reconnect: false`). If a future Group 0 run
+  confirms an exact-identity mechanism on Apple, wire that verified mechanism instead of raising.
+
+#### 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`.
+
+| 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.
+
+← Back to the [README](../README.md)

data/docs/sessions.md

@@ -0,0 +1,99 @@
+# Sessions — continuing, addressable memory
+A session is a remembering instance of an agent, addressed by `(agent_name, instance_id)`, that accumulates context across invocations.
+
+A `Workflow` is fire-and-finish. A **`Nexo::Session`** is the other half: a
+*remembering* instance of an agent, addressed by `(agent_name, instance_id)`, that
+accumulates context across separate invocations.
+
+```ruby
+Nexo::Session.resume(Assistant, "user-42").prompt("My name is Mac.")
+# ... a later request, job, or process ...
+Nexo::Session.resume(Assistant, "user-42").prompt("What is my name?")
+# => "...Mac..." — the persisted thread carried the earlier turn
+```
+
+`resume` finds-or-creates the one thread for that pair (the pair is unique — one
+thread per pair) and returns a session whose `#prompt` appends to it. `#prompt`
+takes the same `max_turns:` and `&on_event` block as `Agent#prompt`, yielding the
+same `(:tool_call | :tool_result | :done, payload)` events. Extra keywords are
+forwarded to the agent constructor (e.g. `Nexo::Session.resume(Assistant, "u1", cwd: repo)`).
+
+**A session adds only memory + addressability — never authority.** Its sandbox,
+permissions (default `:read_only`), skills, MCP servers, and `fetch_allow` are
+exactly the agent's; opening or resuming a session never widens what the agent can
+do. The persisted record supplies the *thread*; the agent supplies the
+*tools/skills/instructions* onto it.
+
+## Composition — `acts_as_chat`, owned by the host
+
+Message persistence is **RubyLLM's `acts_as_chat`** — Nexo defines no message table
+and serializes nothing. The host Rails app owns all four persistence models (`Chat`,
+`Message`, `ToolCall`, `Model`), generated by ruby_llm's own installer:
+
+```bash
+rails g ruby_llm:install      # generates the Chat/Message/ToolCall/Model models + migrations
+```
+
+**One setup step beyond the installer:** the session chat model must be addressable,
+so add two columns and a **unique composite index** to the generated `chats` table:
+
+```ruby
+class AddNexoAddressingToChats < ActiveRecord::Migration[8.0]
+  def change
+    add_column :chats, :agent_name,  :string
+    add_column :chats, :instance_id, :string
+    add_index  :chats, [:agent_name, :instance_id], unique: true
+  end
+end
+```
+
+Tell Nexo which model hosts sessions (only if it isn't ruby_llm's default `Chat`):
+
+```ruby
+Nexo.configure { |c| c.session_chat_model = "Chat" } # default; a String class name,
+                                                     # constantized lazily at resume time
+```
+
+## Rails-only durability — plain Ruby is in-memory
+
+Durable sessions require ActiveRecord. Backend selection guards on
+`defined?(::ActiveRecord::Base)` **and** the host chat model being defined (mirroring
+how `RunStore` only uses the AR store when `Nexo::WorkflowRun` is present):
+
+- **Rails (durable):** the thread is a `chats` row; `acts_as_chat`'s callbacks persist
+  every message. It survives across requests, jobs, and process restarts.
+- **Plain Ruby (in-memory):** a process-wide store holds a live `RubyLLM::Chat` per
+  pair. The thread lives only for the process — a fresh process starts empty. This is
+  documented, non-durable behavior, not a bug.
+
+Re-applying the agent's instructions on every resume is **idempotent**: `acts_as_chat`
+stores instructions as `role: :system` messages, and Nexo re-applies them with
+`with_instructions` (replace semantics) so the stored thread keeps exactly one copy
+across resumes rather than accumulating duplicate system messages. The runtime tools
+(the four sandbox tools + MCP + fetch) are re-attached each resume — they are not
+persisted, and that is correct.
+
+## Retention, PII, and `#close` — the honest trade-off
+
+A continuing session is a persistence surface, and that has real costs:
+
+- **Stored messages persist until you delete them, and may contain sensitive data.**
+  A long-lived thread accumulates whatever the user and tools put into it. Nexo does
+  **not** redact, expire, or GC anything — retention is your responsibility. Treat the
+  `chats`/`messages` tables as PII stores and apply your own retention policy.
+- **Close sessions that hold resources.** If the agent declares MCP servers (stdio/SSE)
+  or fetch, a session holds live subprocesses/sockets. Call `#close` when done — it
+  delegates to `Agent#close`, tearing those down (idempotent, safe with nothing held):
+
+  ```ruby
+  session = Nexo::Session.resume(InboxAssistant, "user-42")
+  begin
+    session.prompt("Summarize my unread threads.")
+  ensure
+    session.close   # releases the agent's MCP/stdio/SSE connections
+  end
+  ```
+
+See `examples/chat_session.rb` for a runnable, env-gated two-prompt resume.
+
+← Back to the [README](../README.md)

data/docs/skills.md

@@ -0,0 +1,68 @@
+# Skills
+A skill is a `SKILL.md` package that teaches the model *how you want a task done* — reasoning, layered on with one macro.
+
+A **skill** is a `SKILL.md` package — frontmatter plus instructions — that teaches the
+model *how you want a task done*. Skills guide **reasoning**; the sandbox-backed tools
+above perform **execution**. Nexo does not implement skill loading; it composes the
+[`ruby_llm-skills`](https://github.com/kieranklaassen/ruby_llm-skills) gem so you attach a
+skill with one macro and no loader setup.
+
+Drop a package under `app/skills/` (or scaffold one — see below):
+
+```
+app/skills/
+└── triage/
+    ├── SKILL.md          # frontmatter (name, description) + process steps
+    └── references/       # supporting docs the skill can cite
+```
+
+```markdown
+---
+name: triage
+description: Triage incoming issues by severity and route them to the right owner.
+---
+
+# Triage
+
+## Process
+1. Classify the issue severity.
+2. Route to the right owner.
+```
+
+Reference it with the `skills` macro — its instructions are layered on top of the agent's
+own, in declaration order:
+
+```ruby
+require "nexo"
+
+class TriageAgent < Nexo::Agent
+  model ENV.fetch("NEXO_MODEL")   # any ruby_llm model — never a hardcoded vendor default
+  skills :triage                  # one macro, no loader wiring
+end
+
+TriageAgent.new.chat   # chat built with the base sandbox tools + the skill's instructions
+```
+
+Scaffold a new skill package with the generator (creates a valid `SKILL.md` plus a
+`references/` directory):
+
+```sh
+rails g nexo:skill triage
+#   create  app/skills/triage/references/.keep
+#   create  app/skills/triage/SKILL.md
+```
+
+`ruby_llm-skills` is an **optional** dependency — required lazily only when you use a skill.
+Without it installed, `require "nexo"` still loads; touching a skill raises a clear
+`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.
+
+## 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.
+
+← Back to the [README](../README.md)

data/docs/tools.md

@@ -0,0 +1,38 @@
+# Tools
+Nexo attaches four sandbox-backed tools — `ReadFile`, `WriteFile`, `Shell`, and `Glob` — each gated by the [sandbox](sandboxes.md) and [permission](permissions.md) seams.
+
+Which tools attach depends on what the sandbox supports:
+
+- **Capability-gated tool attach (`Sandbox#supports?`).** A `:virtual` agent no longer advertises
+  a `Shell` tool it can never run — `Agent#chat` attaches `Shell` only when
+  `@sandbox.supports?(:shell)`. `Local`/`Container` support all four capabilities; `Virtual`
+  supports everything but `:shell`. `ReadFile`/`WriteFile`/`Glob` are always attached.
+
+`Shell` truncates unbounded command output before it reaches the model:
+
+- **Shell output truncation (`Nexo::OutputTruncator`).** Unbounded command output (`npm install`,
+  `git log`) is truncated before it reaches the model, so a single command can't blow a small
+  context window. `Tools::Shell` wraps `stdout`/`stderr` through
+  `OutputTruncator.call(text, max_lines: 200, max_chars: 16_000)` — strips ANSI escapes, keeps the
+  **last** `max_lines` lines, appends a `…[truncated N lines]` marker, then caps at `max_chars`.
+  The integer `status` passes through untouched. Pure line/char truncation — **no tokenizer**;
+  configurable via the kwargs only (no global config, no per-agent macro).
+
+`WriteFile` enforces a read-before-write guard so the agent can't clobber files blindly:
+
+- **Read-before-write + stale guard (real-FS only).** Within a session, the agent is blocked from
+  overwriting a file it never read, or one that changed underneath it. `Agent#chat` builds one
+  `Nexo::ReadTracker` per chat and threads it into `ReadFile` (records `(path, mtime)` on a
+  successful read) and `WriteFile` (enforces): overwriting an existing, un-read file returns
+  `{error: "read <path> before overwriting it"}`; a file whose mtime changed since the read returns
+  `{error: "stale: <path> changed since you read it"}`; a new file writes freely. The guard is
+  **real-FS only** — skipped entirely on `Virtual` (nil `mtime`) and when no tracker is passed
+  (direct tool construction). Best-effort: mtime-based, so a sub-second external edit may slip past
+  the stale check (read-before-write is the primary guard). Clobber-safety within a session only —
+  no versioning, locking, or VCS semantics.
+
+These are sandbox refinements as much as tool behavior — see [Sandboxes](sandboxes.md) for the
+guard details behind each capability. The `fetch` tool for reading the web lives in
+[Web](web.md), gated by its own `:fetch` capability plus a host allow-list.
+
+← Back to the [README](../README.md)