nexo_ai 0.1.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f882444cb236ed835107b086528a0411da8e0ef5e8772816b895a074b3be3046
-  data.tar.gz: f2bf5a3b073b40ddbdb4b76bc9e798caeaa9ead072042a6580e79010a3022ba2
+  metadata.gz: 7e3ef801100c09633b3bc0eba7f1c5444abc3a28d39b093b3f556a6e6a193304
+  data.tar.gz: 770aa194ebef30adc05049890df4611914d9af49ce5bc37460d142dce0a5277d
 SHA512:
-  metadata.gz: f2c213194e4cdf220cec97d6807d060ef82187163bb2256c802c8545550817892488309df51a91a40b18c5e7411fb7c81afedcf2a297653def6056169f6a80f8
-  data.tar.gz: b17d7f23f163402c9b0b2f3c119dc87370dc09831daa007054483fd3deda365813234d5879ab2dab126bff0c14c7a0f67f583eda0133f3064c8b55e5a78d469b
+  metadata.gz: 201531d77a85255355cf77d34d0dd676843f20dee2149627226a1f9068c5b6dfcc7e9e4d92e33b357536326f35e861d9fc1d1d6230bac1e5eac5db9314e3ec75
+  data.tar.gz: aff13284d24b6465a10a34b60847d6ceece755b8d8791b688777a6ec7538d7506db82922a9e83d4382a66d3045ee45ee3a4c9eede4d2b8a37e4021e9e134a934

data/.document

@@ -0,0 +1,3 @@
+README.md
+docs
+lib

data/CHANGELOG.md

@@ -1,5 +1,260 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-07-16
+
+Durability enhancements for workflows: a suspended run can now wake itself on a
+timer, and independent checkpoints run concurrently, each persisting as it
+completes. Both build on the existing ActiveJob and `Nexo.concurrent` seams — no
+schema, run-status, or store change.
+
+### Added
+
+- **Scheduled enqueue/resume.** `Workflow.run_later` and `Workflow.resume_later`
+  accept `wait:` (a duration) or `wait_until:` (an absolute time), forwarded to the
+  installed ActiveJob's own `.set(...)` scheduler — so a suspended run can wake
+  itself on a timer and an initial enqueue can be deferred, without Nexo adding a
+  scheduler. Passing both raises `ArgumentError`; with neither the enqueue is
+  unchanged. Status stays `"queued"`/`"suspended"` (no new status). No retry
+  semantics are added.
+- **Parallel checkpoints.** `Workflow#checkpoint_all(name => callable, …)` runs
+  independent checkpoints concurrently through the existing `Nexo.concurrent`
+  driver, persisting **each step as it completes** so a resume after a partial
+  failure re-runs only the still-missing steps. Each newly-completed step emits a
+  `"checkpoint"`-typed event (name-only) on the existing `nexo.workflow.event`
+  seam. Reuses `state`/`save_state!` — no schema, run-status, or store change.
+
+## [0.7.0] - 2026-07-10
+
+The harness fills out: MCP data sources, a web-content capability, durable
+workflows (suspend/checkpoint/resume) with an approval bridge, continuing agent
+sessions, a container sandbox, Rails runtime primitives, and a documentation
+restructure — followed by a security-and-lifecycle hardening pass over the whole
+Sandbox + Permissions seam.
+
+### Added
+
+- **MCP data sources.** `Agent.mcp` attaches Model Context Protocol servers
+  (stdio/SSE/HTTP) via `ruby_llm-mcp` (soft, optional dependency). Every MCP tool
+  call passes a second gate — `Permissions#authorize_mcp!` — scoped by the
+  `mcp_allow` exact-match allow-list (default `[]`, so `:read_only` fails closed).
+  `MCP::GatedTool` is a plain delegating wrapper; teardown is `Agent#close`.
+- **MCP over HTTP with an OAuth token provider.** `MCP.build(token:)` accepts a
+  static string or a callable and injects `Authorization: Bearer …` into the
+  HTTP-family transports. A rotated token is resolved once per client build, so
+  rotation needs `Agent#close` + a fresh prompt (documented reconnect caveat).
+- **Web-content capability (`:fetch`).** `Nexo::Tools::Fetch` (stdlib `net/http`
+  GET) is a two-lock capability: the `:fetch` permission (default-denied under
+  `:read_only`) plus a host in the subdomain-aware `fetch_allow` list. An SSRF
+  guard resolves the host once, pins the vetted IP, and denies loopback/private/
+  link-local/CGNAT/unspecified ranges. Responses are byte-capped.
+- **Web search capability (`:search`).** `Nexo::Tools::WebSearch` with an
+  injected backend (`search_backend`), gated like `:fetch`.
+- **Input staging + named artifacts.** `Workflow#stage` writes files into the
+  run's sandbox before work begins; `Workflow#artifact` records named outputs
+  (`content:` or a trusted ERB `from:` template) on the run, persisted immediately.
+  Both reuse the sandbox + WorkflowRun seams; a data-only workflow builds nothing.
+- **Workflow → agent glue.** `Workflow#run_agent(prompt, max_turns:)` runs the
+  declared `agent` inside the run's shared sandbox and forwards every loop event
+  through `emit`.
+- **Durable workflows.** `Workflow#suspend!`, `#checkpoint`, and `Workflow.resume`
+  add a `"suspended"` status and a JSON `state` column: a workflow can pause for
+  input, persist completed checkpoints, and resume (sync or via `resume_later`)
+  without re-running checkpointed work. `resume` atomically claims a suspended run
+  (no double execution); checkpoint values are JSON-normalized for Memory/AR parity.
+- **Durable approval bridge.** Under `permissions :approve`, an undecided
+  sensitive tool call raises `ApprovalRequired`, which `run_agent` records under a
+  reserved `__approval__` state key and turns into a `suspend!`; `resume(approved:)`
+  threads the human decision back into the agent's permissions.
+- **Continuing agent sessions.** `Nexo::Session` persists a chat across prompts
+  via ruby_llm's `acts_as_chat` (host-owned schema), with idempotent instruction
+  re-application on every resume and once-only observability wiring.
+- **Container sandbox.** `Sandboxes::Container` runs an agent's tools inside a
+  throwaway, hardened OCI container via the `docker` (default) or Apple `container`
+  CLI — no vendor gem, argv arrays only (no shell-string interpolation). Ephemeral
+  by default; opt-in `reconnect: true` reattaches by an exact identity label.
+- **Rails runtime primitives.** `Nexo::WorkflowJob` (ActiveJob), Turbo mirroring,
+  and `ActiveSupport::Notifications` (`nexo.workflow.status` / `nexo.workflow.event`)
+  — all Rails-optional and guarded, no-ops when their dependency is absent.
+- **Unified sandbox resolver.** `Sandboxes.resolve` is the single place a sandbox
+  declaration (symbol / Hash / pre-built instance) becomes a concrete `Sandbox`.
+- **`provider` / `assume_model_exists` agent macros** for non-registry models
+  (e.g. Ollama), now documented in the getting-started guide.
+- **Documentation restructure.** The README is a slim index; thirteen topic guides
+  live under `docs/`, and `rake doc` / `rake doc:coverage` (a 100%-or-fail gate)
+  render and enforce RDoc coverage.
+
+### Security
+
+- **MCP gate no longer fails open under `:approve`.** `authorize_mcp!` gained an
+  `:approve` branch and a fail-closed `else raise Denied` backstop, so no mode
+  falls through ungated.
+- **Closed shell/command injection in `Container#glob` and `Remote#glob`.** The
+  model-supplied pattern is passed as a positional argument, never interpolated
+  into a command line — a `:read_only` agent can no longer reach command execution
+  through the always-allowed `:glob` capability.
+- **`Local` sandbox hardening.** `glob` guards the pattern against escapes and
+  filters symlinked matches; `read`/`write` resolve symlinks via `realpath` so a
+  symlink inside `cwd` pointing outside it no longer escapes the sandbox.
+- **Fetch SSRF hardened.** Resolve-once IP pinning removes the DNS-rebinding
+  window; the deny set adds `0.0.0.0/8`, CGNAT `100.64.0.0/10`, and the IPv6
+  unspecified address.
+
+### Fixed
+
+- **Sandbox lifecycle — no container leak.** `Agent#close` now closes the sandbox
+  it owns; `Workflow.execute` releases the run's sandbox on every terminal path.
+  A borrowed sandbox (injected via `sandbox:`, e.g. `run_agent`) is left to its
+  owner, so multiple `run_agent` calls no longer tear down a shared container.
+- **Workflow lifecycle correctness.** A non-`StandardError` (path-escape
+  `SecurityError`, shell-less `NotImplementedError`) now marks a run `"failed"`
+  instead of stranding it `"running"`; `resume` claims the run atomically; a
+  non-approval resume is no longer coerced into a silent denial; reserved
+  `__suspend__` / `__approval__` state is cleared on a successful resume; status
+  notifications fire for `queued`/`interrupted`; `resume` honors the original
+  `buffer_events`.
+- **Ambiguous workflow payloads raise.** `run` / `run_later` reject a positional
+  payload combined with leftover keywords instead of silently dropping keys.
+- **Agent config is inherited.** Subclassing a configured agent copies its macros
+  instead of reverting to defaults.
+- **Session/loop fixes.** The base `Loop#run` contract includes `chat:`;
+  `Loops::AgentSDK` rejects a session chat with a clear error and emits the
+  terminal `:done` event; durable-session instruction application collapses to one
+  copy per resume even without an `instructions` macro; the Memory session path
+  adopts the agent owning the live chat so `close`/`prompt` hit live resources.
+- **Miscellaneous.** Memory `RunStore` is mutex-guarded and mirrors the AR read
+  helpers; `engine.rb` is Zeitwerk-ignored; `Agent#close` is exception-safe per
+  client; `skills`/`mcp_allow`/`fetch_allow` accumulate (deduped) like `mcp`;
+  `ReadFile` caps its output; `WebSearch` and `stage` tolerate string- or
+  symbol-keyed input; dead `save!` and `turns`-counter code removed.
+
+## [0.6.0] - 2026-07-01
+
+### Added
+
+- **Opt-in fiber concurrency (`async`).** `Nexo.concurrent(max_in_flight:) { |c| c.add { … } }`
+  runs many agent/workflow calls inside one `async` reactor, bounded by an
+  `Async::Semaphore` and coordinated by an `Async::Barrier`. Results come back in
+  **submission order**; the first task to raise is re-raised (errors are never
+  swallowed) and the remaining in-flight tasks are stopped. `max_in_flight`
+  (default `Nexo.config.max_in_flight`, i.e. `8`) keeps fan-out under provider
+  rate limits — the reason to prefer it over a hand-rolled `Async {}`.
+- **`async` is a SOFT/optional dependency** — lazily required only when a
+  concurrency feature is used. `require "nexo"` with `async` absent does not
+  raise; using `Nexo.concurrent` (or the `:async` sandbox offload) without it
+  raises `Nexo::MissingDependencyError` with install guidance
+  (`gem "async", "~> 2.0"`).
+- **`Nexo::Configuration` gains three settings:** `concurrency`
+  (`:threaded` default | `:async`), `max_in_flight` (`8`), and
+  `buffer_workflow_events` (`false`).
+- **`Sandboxes::Local` async offload.** `read`/`write`/`glob`/`shell` route
+  through a private `#offload`; when `Nexo.config.concurrency == :async` the
+  blocking file/subprocess I/O runs on a worker thread so it doesn't stall the
+  reactor, otherwise it runs inline (byte-for-byte the previous behavior, zero
+  overhead). The path-escape `SecurityError` guard, narrowed ENV, and
+  `Timeout`-wrapped `Open3.capture3` are all preserved unchanged.
+- **`Workflow.run(payload, buffer_events:)` buffered emit.** With
+  `buffer_events: true` (default `Nexo.config.buffer_workflow_events`) events are
+  buffered in memory and flushed to the store exactly once (in `run`'s `ensure`,
+  so they persist on success and failure), avoiding a blocking per-event DB write
+  under a reactor. The default (unbuffered) path is unchanged from 0.4.0.
+
+### Notes
+
+- `Loops::RubyLLM` needs **no changes** to run inside a reactor — `ruby_llm`'s
+  Faraday `net/http` adapter already yields on socket I/O under Ruby's fiber
+  scheduler. A regression test proves a prompt driven from inside `Async {}`
+  returns unchanged.
+- `Async::WorkerPool` is not present in the installed `async` (2.x), so the
+  offload primitive is `Thread.new(&block).value` (re-raises block exceptions in
+  the caller).
+
+### Changed
+
+- Raised minimum Ruby to 3.3; `Nexo.generate_run_id` now uses
+  `SecureRandom.uuid_v7` unconditionally (dropped the 3.2 UUID v4 fallback).
+
+## [0.5.0] - 2026-06-29
+
+### Added
+
+- **Pluggable loop backends.** `Nexo::Loop` is the new engine seam:
+  `#run(agent:, prompt:, max_turns:, &on_event)`. Swap the loop by constructor
+  injection (`loop:`) without changing the agent class.
+- `Nexo::Loops::RubyLLM` (DEFAULT, provider-neutral) — the Spec 1 `Agent#prompt`
+  loop logic extracted verbatim. It runs on any `ruby_llm` model and contains no
+  vendor code. Wires turn-count *observability* through `RubyLLM::Chat`'s
+  `before_tool_call`/`after_tool_result` callbacks (guarded by `respond_to?`),
+  forwarding `:tool_call`/`:tool_result`/`:done` to an optional `on_event` block.
+- `Nexo::Loops::AgentSDK` (opt-in, Anthropic-oriented) — wraps
+  `RubyLLM::AgentSDK.query` for native `max_turns`, permission modes, and the
+  SDK's built-in tools. `ruby_llm-agent_sdk` is a SOFT/optional dependency,
+  required lazily; a clear `Nexo::MissingDependencyError` is raised when it's
+  absent. Not a dependency of this release (its `.query` signature is
+  verified-on-install).
+- `Nexo::Sandboxes::Remote` — run an agent's tools inside a remote container by
+  injecting any client satisfying the four-method contract (`read`/`write`/
+  `exec`/`close`). Contains zero vendor code; switching providers is swapping the
+  injected object. Vendor SDKs are adapted with a tiny documented shim.
+- `Agent` gains a `loop:` option (default `Loops::RubyLLM.new`); `#prompt`
+  delegates to it. New readers `#permission_mode` (Nexo→AgentSDK mode mapping:
+  `:read_only`→`:default`, `:auto`→`:bypass_permissions`, `:ask`→`:default`) and
+  `#allowed_tools` support the AgentSDK backend. `Permissions#mode` is now
+  readable.
+
+### Documented
+
+- README: the loop/sandbox matrix, the two-configurations / same-agent example,
+  the Remote shim pattern, the Nexo→AgentSDK permission mapping, and the turn-cap
+  caveat (`Loops::RubyLLM` has no proven hard turn cap — observability only).
+
+## [0.4.0] - 2026-06-29
+
+### Added
+
+- **Skills.** Drop a `SKILL.md` package into `app/skills/<name>/` and attach it
+  to an agent with a single `skills :name` class macro — Nexo composes the
+  existing `ruby_llm-skills` gem to load the skill's instructions, with zero
+  loader setup. Skills guide *reasoning*; the sandbox-backed tools from Spec 1
+  still perform *execution*.
+- `Nexo::Skills.load!` lazily requires `ruby_llm-skills` (a SOFT/optional runtime
+  dependency) and raises `Nexo::MissingDependencyError` with install guidance when
+  it is absent; `require "nexo"` without the gem still loads cleanly.
+- `Nexo::Skills.find(name)` resolves a skill from `Nexo.config.skills_path`
+  (default `app/skills` under Rails), raising `Nexo::Error` that names the missing
+  `SKILL.md` path when not found.
+- `Nexo::Agent.skills(*names)` class macro; `#chat` layers each declared skill's
+  instructions on top of the agent's own, in declaration order, after the
+  sandbox-backed tools.
+- A `nexo:skill NAME` generator scaffolding `app/skills/NAME/SKILL.md` (valid
+  Agent Skills frontmatter) plus a kept `references/` directory.
+
+### Safety
+
+- Skill packages contribute **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). A skill's
+  `references/`/`scripts/` files are reached through Nexo's own permission-gated,
+  sandbox-backed tools, so attaching a skill never widens what an agent can do.
+
+## [0.3.0] - 2026-06-29
+
+### Added
+
+- **WorkflowRun lifecycle primitive.** Subclass `Nexo::Workflow`, implement
+  `#call(payload)`, and run it with `MyWorkflow.run(payload)` to get back a
+  persisted run record carrying a UUID v7 runId, `status`, `payload`, `result`,
+  `error`, and an ordered, inspectable event log.
+- `#emit(type, data)` appends ordered events (persisted incrementally) and
+  `Nexo::Workflow.logs(run_id)` / the `nexo:logs[run_id]` rake task inspect them.
+- A storage seam `Nexo::RunStore` with two interchangeable backends: an
+  in-memory store (plain Ruby, offline) and an ActiveRecord store (Rails),
+  selected automatically by `Nexo::RunStore.default`.
+- `Nexo::WorkflowRun` ActiveRecord model and a `nexo:workflows` generator that
+  installs a portable (`json` columns, UUID string primary key) migration.
+- `Nexo.generate_run_id` (time-ordered UUID v7).
+- A guarded `Nexo::Engine` wiring the generator, rake task, and model into a
+  host Rails app; the core still runs in plain Ruby with no Rails loaded.
+
 ## [0.1.0] - 2026-06-21
 
 - Initial release

data/README.md

@@ -4,10 +4,15 @@
 > sandboxes, skills, and runs.
 
 A model alone forgets everything the moment a response ends. The harness is everything
-else. Nexo gives the fragmented RubyLLM ecosystem one front door with safe defaults —
+else. Nexo gives the RubyLLM ecosystem one cohesive front door with safe defaults —
 build a working agent in five lines without wiring anything.
 
-**What Nexo adds (everything else it composes):**
+## Compose, don't reimplement
+
+Nexo does not rebuild skill loading, the tool-call loop, MCP, or structured output — those
+already live in the RubyLLM ecosystem (`ruby_llm` core, `ruby_llm-skills`, `ruby_llm-mcp`,
+`ruby_llm-schema`). Nexo **composes** them behind one front door and adds only the two pieces
+the ecosystem is missing:
 
 - **Sandbox + Permissions seam** — pluggable execution environment (virtual / local /
   remote) with explicit authorization gating. Default: `:virtual` + `:read_only`.
@@ -28,10 +33,76 @@ Or install directly:
 gem install nexo_ai
 ```
 
+In a Rails app, run the install generator to create the conventional layout and an initializer:
+
+```sh
+rails g nexo:install
+```
+
+```
+      create  app/agents/.keep
+      create  app/workflows/.keep
+      create  app/skills/.keep
+      create  config/initializers/nexo.rb
+```
+
+## Build an agent in five lines
+
+Subclass `Nexo::Agent`, declare the pieces with class macros, and call `#prompt`. No
+sandbox, permission, or tool object is wired by hand, and nothing is vendor-specific —
+the agent runs on any `ruby_llm`-supported model (set `NEXO_MODEL`, e.g. a local
+`gemma3:12b` via Ollama, or a hosted model):
+
+```ruby
+require "nexo"
+
+class CodeReviewer < Nexo::Agent
+  model       ENV.fetch("NEXO_MODEL")   # any ruby_llm model — never a hardcoded vendor default
+  sandbox     :local
+  permissions :read_only
+
+  instructions "You are a careful code reviewer. Read files and report issues. Do not write files."
+end
+
+CodeReviewer.new(cwd: "/path/to/repo").prompt("Review the auth module")
+```
+
+Defaults are safe: an agent with no `sandbox`/`permissions` declared gets the in-memory
+`:virtual` sandbox and `:read_only` permissions, so an untrusted model has zero host
+access until you explicitly opt in.
+
+> **Safe by default:** agents start `:virtual` + `:read_only` — an untrusted model has zero host access until you explicitly opt in.
+
+## Documentation
+
+| Guide | What's inside |
+|-------|---------------|
+| [Getting started](docs/getting-started.md) | install, configuration, first agent |
+| [Sandboxes](docs/sandboxes.md) | Virtual / Local / Remote / Container + hardened defaults |
+| [Permissions](docs/permissions.md) | modes, the gate, MCP gate, :ask |
+| [Tools](docs/tools.md) | ReadFile / WriteFile / Shell / Glob |
+| [Loop backends](docs/loops.md) | RubyLLM vs AgentSDK, turn-cap caveat |
+| [Workflows](docs/workflows.md) | lifecycle, staging, artifacts, run_agent |
+| [Durable workflows](docs/durable-workflows.md) | checkpoint / suspend / resume |
+| [Skills](docs/skills.md) | SKILL.md packages, gated tools |
+| [MCP](docs/mcp.md) | mcp macro, fail-closed gate, transports |
+| [Web](docs/web.md) | fetch tool + SSRF guard, search tool + injected backend |
+| [Sessions](docs/sessions.md) | continuing, addressable memory |
+| [Rails](docs/rails.md) | engine, run_later, broadcasting, generators |
+| [Concurrency](docs/concurrency.md) | opt-in async, buffered emit, fiber servers |
+
 ## Requirements
 
-- Ruby 3.2+
-- [ruby_llm](https://github.com/crmne/ruby_llm) ~> 1.0
+- Ruby 3.3+
+- [ruby_llm](https://github.com/crmne/ruby_llm) >= 1.16
+- [ruby_llm-skills](https://github.com/kieranklaassen/ruby_llm-skills) — optional, only
+  when you use the `skills` macro
+- [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp) — optional, only when you attach
+  an MCP server with the `mcp` macro
+- `ruby_llm-agent_sdk` — optional (not yet published), only when you choose the
+  Anthropic-oriented `Loops::AgentSDK` backend. Its exact API is verified-on-install
+  (see [Loops](docs/loops.md)); until it ships, `Loops::AgentSDK` raises a clear
+  `Nexo::MissingDependencyError`.
 
 ## Status
 

data/Rakefile

@@ -7,4 +7,33 @@ Minitest::TestTask.create
 
 require "standard/rake"
 
+# Documentation build + coverage gate (Spec 17). RDoc is a Ruby default gem, so
+# neither `rake doc` nor `rake doc:coverage` adds a runtime or dev dependency.
+require "rdoc/task"
+
+# RDoc renders the README/guides (which carry UTF-8 glyphs) by reading them with
+# Encoding.default_external; some CI environments start US-ASCII, under which the
+# HTML generation raises Encoding::InvalidByteSequenceError. Pin UTF-8 so the doc
+# build is environment-independent (the test suite pins the same in test_helper).
+Encoding.default_external = Encoding::UTF_8 if Encoding.default_external == Encoding::US_ASCII
+
+# Naming the task :doc gives us `rake doc` (generate the API site into doc/,
+# gitignored) plus, for free, `rake doc:coverage` — RDoc's own coverage report.
+# Verified against rdoc 8.0.0: the coverage run exits non-zero (SystemExit) unless
+# every public API is documented, so `rake doc:coverage` is a real CI gate with no
+# bespoke parser to maintain. The generated site includes the README landing page,
+# the docs/*.md guides, and the lib/**/*.rb API.
+RDoc::Task.new(:doc) do |rd|
+  rd.main = "README.md"
+  rd.rdoc_files.include("README.md", "docs/*.md", "lib/**/*.rb")
+  # Generator template files are boilerplate copied verbatim into a host app
+  # (migrations land in the host's db/migrate, the initializer in config/) — they
+  # are not part of the gem's Ruby API, so they belong in neither the generated
+  # API site nor the coverage denominator.
+  rd.rdoc_files.exclude("lib/generators/**/templates/*.rb")
+  rd.rdoc_dir = "doc"
+end
+
+# NOTE: `default` intentionally stays test + standard — `rake doc`/`doc:coverage`
+# are not part of the default run, so `bundle exec rake test` is untouched.
 task default: %i[test standard]

data/app/views/nexo/_event.html.erb

@@ -0,0 +1 @@
+<div class="nexo-event"><%= event["type"] %>: <%= event["data"].inspect %></div>

data/docs/concurrency.md

@@ -0,0 +1,100 @@
+# Concurrency (opt-in async)
+Async is entirely optional — Nexo runs synchronously by default and only needs the `async` gem when you use a fan-out feature.
+
+Async is **entirely optional**. Nexo installs and runs synchronously with no
+`async` gem present, and only complains if you actually use a concurrency
+feature. The `async` gem is a soft dependency — add it yourself when you want
+fan-out:
+
+```ruby
+gem "async", "~> 2.0"
+```
+
+Two facts make this cheap:
+
+- **LLM calls are already async-compatible.** `ruby_llm` speaks HTTP over
+  Faraday's `net/http` adapter, which yields on socket I/O under Ruby's fiber
+  scheduler. `Loops::RubyLLM` therefore runs unchanged inside a reactor — no API
+  change, no rewrite. Wrapping a *single* `agent.prompt` in `Async {}` gains
+  nothing; async only pays off under fan-out.
+- **The value Nexo adds is rate-bounded fan-out.** `Nexo.concurrent` bounds
+  in-flight work so you don't trip provider rate limits, and propagates the first
+  error instead of swallowing it.
+
+## `Nexo.concurrent` — bounded fan-out
+
+```ruby
+# 100 docs, but never more than 8 provider calls in flight; results in doc order.
+results = Nexo.concurrent(max_in_flight: 8) do |c|
+  Document.find_each { |d| c.add { SummarizeDocument.run(doc_id: d.id, text: d.body).result } }
+end
+```
+
+Every block added with `c.add { … }` runs inside **one** `async` reactor,
+capped at `max_in_flight` in flight (an `Async::Semaphore`) and coordinated by an
+`Async::Barrier`. Results come back as an Array in **submission order** (not
+completion order). On the first task that raises, that error is **re-raised** and
+the remaining in-flight tasks are stopped — errors are never swallowed.
+`max_in_flight` defaults to `Nexo.config.max_in_flight` (`8`) and is the single
+most important knob for staying under provider rate limits.
+
+Using `Nexo.concurrent` with `async` not installed raises
+`Nexo::MissingDependencyError` with install guidance.
+
+Inside a durable workflow, `Workflow#checkpoint_all` is the workflow-durability
+flavored sibling of `Nexo.concurrent`: it drives this same bounded fan-out but
+persists each step to the run's `state` as it lands, so a resume only re-runs what
+never completed. See [Parallel checkpoints](durable-workflows.md#parallel-checkpoints--checkpoint_all)
+in the durable-workflows guide.
+
+## `Sandboxes::Local` offload
+
+Under a reactor, blocking file/subprocess I/O would stall every other fiber. Flip
+the switch and `Sandboxes::Local` offloads its `read`/`write`/`glob`/`shell` to a
+worker thread:
+
+```ruby
+Nexo.configure { |c| c.concurrency = :async }   # default is :threaded
+```
+
+The decision is driven by config, not by scheduler detection: under `:async` the
+blocking block runs on a worker thread so the reactor keeps serving other fibers;
+under `:threaded` (the default) it runs inline with zero overhead — byte-for-byte
+the synchronous behavior. Offloading changes neither return values nor the
+security properties: the path-escape guard, narrowed ENV, and `Timeout`-wrapped
+subprocess are all preserved. (`Sandboxes::Virtual` is pure memory and
+`Sandboxes::Remote` is already HTTP/fiber-friendly — neither needs offload.)
+
+## `Workflow` buffered emit
+
+Each `emit` normally persists immediately. Under a reactor that per-event DB write
+blocks the whole loop, so `Workflow.run` takes a `buffer_events:` flag (default
+`Nexo.config.buffer_workflow_events`, `false`):
+
+```ruby
+run = SummarizeDocument.run({doc_id: 1, text: body}, buffer_events: true)
+# events buffer in memory and flush to the store exactly once, on completion
+```
+
+With buffering on, events accumulate in memory and flush in a single
+`save_events!` at the end of the run (on both success and failure). The default
+(unbuffered) behavior is unchanged.
+
+## Running under Rails / a fiber server
+
+Async DB work is the sharp edge. Under a fiber server such as
+[Falcon](https://github.com/socketry/falcon), many concurrent queries can exhaust
+the ActiveRecord connection pool, so:
+
+- **Raise `DB_POOL`** (the connection-pool size) to cover your in-flight
+  concurrency.
+- On **Rails 7.1+**, consider
+  `config.active_record.async_query_executor`.
+- Prefer `buffer_events: true` for workflows so each run writes its event log
+  once instead of per event.
+
+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/).
+
+← Back to the [README](../README.md)