nexo_ai 0.1.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f882444cb236ed835107b086528a0411da8e0ef5e8772816b895a074b3be3046
-  data.tar.gz: f2bf5a3b073b40ddbdb4b76bc9e798caeaa9ead072042a6580e79010a3022ba2
+  metadata.gz: 34123b61080f43662220abb5a92686ac3123ef5ae1255a1318f311985a08e304
+  data.tar.gz: 46fdf315414f80c500cc7fa33794c5a576839c6b67fcbb0e282d2ad327d354fd
 SHA512:
-  metadata.gz: f2c213194e4cdf220cec97d6807d060ef82187163bb2256c802c8545550817892488309df51a91a40b18c5e7411fb7c81afedcf2a297653def6056169f6a80f8
-  data.tar.gz: b17d7f23f163402c9b0b2f3c119dc87370dc09831daa007054483fd3deda365813234d5879ab2dab126bff0c14c7a0f67f583eda0133f3064c8b55e5a78d469b
+  metadata.gz: 6df53f1442c2332977b40a2c3d1024699b2fc7ec9f464714e8dd0f0364dfa906c13c423af438523e7c054f93b61391c2810e44e4bab97a5a087361a82635f993
+  data.tar.gz: 961b1ce3a8975f2127a2d0a207d93742e674ea233cb549942fe18c39b3cc4b742f61bf7b41fe6eadca815ee863cae956362a18acf9731450089e55bcfbf57204

data/.document

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

data/CHANGELOG.md

@@ -1,5 +1,237 @@
 ## [Unreleased]
 
+## [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,94 @@
+# 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.
+
+## `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)

data/docs/durable-workflows.md

@@ -0,0 +1,184 @@
+# Durable workflows — suspend · checkpoint · resume
+A long-running or human-in-the-loop workflow can pause durably and continue later without re-running already-paid-for work.
+
+A long-running or human-in-the-loop workflow can **pause durably** and **continue
+later** — possibly in another process — without re-running completed,
+already-paid-for work. Three small primitives compose over the existing run
+persistence (no step-graph engine, no replay log, no scheduler):
+
+- **`checkpoint(name) { … }`** runs its block **once** and stores the
+  json-serializable result under `name` in the run's `state`. On a later run/resume
+  of the *same* run, a present checkpoint returns the stored value **without**
+  re-running the block. This is the tool that makes resume cheap and side-effect-safe.
+- **`suspend!(reason:, resume_key: nil)`** pauses the run: it marks the run
+  `"suspended"` (a **non-failure** outcome, distinct from `"failed"`) and returns it
+  to the caller — `Workflow.run` does **not** raise. Call it *outside* a checkpoint.
+- **`Workflow.resume(run_id, input = {})`** (sync) and
+  **`Workflow.resume_later(run_id, input = {})`** (enqueued) continue a suspended
+  run, feeding `input` in as `#resume_input`.
+
+```ruby
+class DocumentApproval < Nexo::Workflow
+  def call(payload)
+    document = checkpoint(:fetch) { fetch_expensive(payload[:id]) } # paid for once
+
+    # `resume_input` is {} on the first pass, so we pause; on resume the host
+    # feeds { approved: true }, so we fall through and publish.
+    suspend!(reason: "awaiting approval") unless resume_input[:approved]
+
+    checkpoint(:publish) { publish!(document) }
+    { done: true }
+  end
+end
+
+run = DocumentApproval.run(id: 42)   # reaches suspend!, returns
+run.status                            # => "suspended"
+run.suspend_reason                    # => "awaiting approval"  (AR store)
+run.state["fetch"]                    # => the fetched document (checkpoint persisted)
+
+# ...later, once a human approves — possibly in another process:
+resumed = DocumentApproval.resume(run.id, approved: true)
+resumed.status                        # => "done"  (the :fetch block did NOT re-run)
+```
+
+A host UI lists paused runs with the `suspended` scope and inspects them with the
+readers (Nexo ships no controllers/views — the UI is your app's job):
+
+```ruby
+Nexo::WorkflowRun.suspended            # scope: all paused runs
+run.suspended?                          # => true
+run.suspend_reason                      # => "awaiting approval"
+run.checkpoint_result(:fetch)           # => the stored :fetch value, or nil
+```
+
+For a **durable, cross-process** resume from a background job, enqueue it — the job
+carries the run id plus the (json-safe) resume input; the payload still lives on the
+run:
+
+```ruby
+# The resume input is a positional Hash (queue: is the only keyword), so pass it
+# as `{ approved: true }` — bare `approved: true` would bind as an unknown keyword.
+DocumentApproval.resume_later(run.id, { approved: true }, queue: :nexo)
+```
+
+See [`examples/approval_workflow.rb`](../examples/approval_workflow.rb) for the full
+offline flow (`ruby -Ilib examples/approval_workflow.rb`).
+
+## Durable **agent** approval — `:approve` (bridge a mid-run gate to a suspend)
+
+The example above suspends at an **explicit** `suspend!` the workflow author placed.
+The `:approve` mode adds the durable, cross-process sibling of `:ask` for the case where a
+`run_agent`-driven agent hits a permission gate **mid-loop** and you want that to
+**pause the run for a human**, not run unchecked and not block a worker. Declare the
+agent under the `:approve` mode:
+
+```ruby
+class Scribe < Nexo::Agent
+  model   ENV.fetch("NEXO_MODEL")
+  sandbox :local
+  permissions :approve        # every gated capability needs a human decision
+end
+
+class ApprovedWrite < Nexo::Workflow
+  sandbox :local
+  agent   Scribe
+  def call(_p) = { content: run_agent("Write 'hi' to notes.txt").content }
+end
+```
+
+The loop is: **`:approve` gate with no decision → `Nexo::ApprovalRequired` → `run_agent`
+suspends → host renders the pending call → `resume(approved:)` threads the decision back
+through the gate.**
+
+```ruby
+run = ApprovedWrite.run                       # agent reaches the write gate, run suspends
+run.status                                     # => "suspended"
+run.state["__suspend__"]["reason"]             # => "approval: notes.txt"
+run.state["__approval__"]                      # => { "capability" => "write",
+                                               #      "tool" => "notes.txt", "args" => nil }
+# "args" carries the tool call arguments only for an MCP-tool approval; a sandbox
+# capability gate (write/shell/fetch/search) records "args" => nil — the pending
+# call is identified by "capability" + "tool".
+
+# ...a human approves — possibly in another process (resume_later for the AR store):
+resumed = ApprovedWrite.resume(run.id, approved: true)
+resumed.status                                 # => "done" (the gate allowed the write)
+```
+
+- **`Nexo::ApprovalRequired`** is a signal, **distinct from `Permissions::Denied`**:
+  `Denied` means "no, adapt" (tools rescue it into `{error:}`); `ApprovalRequired` means
+  "pause and ask a human", so tools must **not** rescue it — it propagates out of the
+  tool loop and out of `Agent#prompt`, where `run_agent` catches it.
+- **Undecided ⇒ suspend, `approved: false` ⇒ deny.** The default stays safe: an
+  unresolved approval never silently allows, and a denial on resume makes the tool return
+  `{error:}` (the model adapts) — the run still finishes `"done"`, **without** the gated
+  effect, never `"failed"`.
+- **Scope which actions need approval** with the same `ask_when` predicate as `:ask`
+  (aliased `approve_when:` for readability) — unset means every gated action needs a
+  decision; a falsey predicate auto-allows without one:
+
+  ```ruby
+  Nexo::Permissions.new(mode: :approve,
+    approve_when: ->(cap, detail) { cap == :write && detail.to_s.start_with?("/protected") })
+  ```
+- **Synchronous `:ask` is untouched.** `:ask` (in-process `on_ask`) is still the right
+  choice with a human at the keyboard during a synchronous `run`; `:approve` is its
+  durable, cross-process sibling for `run_later`/`resume_later`.
+
+**Caveats (read before relying on it):**
+- **Re-entry, not replay.** On resume the agent re-drives `#call` from the top; a
+  non-idempotent tool call *before* the approval gate re-runs on resume (agent tool calls
+  generally aren't checkpointable). Put approval gates **early**, or after the expensive
+  work is already `checkpoint`ed by the workflow.
+- **One approval per suspend cycle, global decision.** The `{approved:}` answers whichever
+  gate the re-driven agent hits first. A *second* gate after an approved first one simply
+  **suspends again** — the next resume decides it. There is no per-tool decision granularity
+  in v1.
+- **Cross-process approval needs the ActiveRecord store + ActiveJob** (like all durable resume).
+  In-process `resume` works with the Memory store; a Memory run does not survive the process.
+- **Branch depends on upstream `ruby_llm`.** This works because `ruby_llm`'s tool loop lets a
+  tool `execute` exception propagate out of `chat.ask` (verified, 1.16.0). If a future
+  `ruby_llm` swallows tool exceptions, tool-triggered approval would be constrained — a
+  genuine upstream dependency, stated plainly.
+
+See [`examples/approval_agent.rb`](../examples/approval_agent.rb) for the live flow
+(`NEXO_LIVE=1 NEXO_MODEL=… ruby -Ilib examples/approval_agent.rb`).
+
+The `state` column ships with fresh installs. Apps installed before this feature
+add it with an additive migration:
+
+```sh
+rails g nexo:state
+rails db:migrate
+```
+
+## Honest resume semantics — read this before relying on resume
+
+Resume **re-enters `#call` from the top** — Ruby has no transparent continuation
+capture, so this is **not** replay:
+
+- **Everything *outside* a `checkpoint` re-runs on resume.** Only checkpoint-guarded
+  work is skipped (its stored result is returned). Wrap every expensive step and
+  every side effect in a `checkpoint`; the idempotency of the non-checkpointed code
+  is **your** responsibility.
+- **A crash *inside* a checkpoint re-runs that checkpoint** on resume (at-least-once
+  for the in-flight step) — so a checkpoint's side effect should tolerate being
+  retried.
+- **Checkpoint values must be json-serializable** — they round-trip the store exactly
+  like `result`/`events`.
+- **Cross-process resume needs the ActiveRecord store.** A run suspended under the
+  in-memory store resumes only *in-process* (which is what the test suite exercises);
+  a run that must survive the process (and be resumed by a controller/job elsewhere)
+  needs the AR store with a shared database.
+- **Never `suspend!` inside a `checkpoint` block** (undefined — unsupported), and
+  never name a checkpoint `"__suspend__"` (reserved for the suspend metadata) or
+  `"__approval__"` (reserved for the pending approval call — see the durable-approval
+  section above) — both are keys Nexo stores in `state`.
+
+There is **no distinct `"resumed"` status**: resume re-enters `execute`, so a host
+sees the existing `suspended` → `running` → `done` (or `suspended` again)
+transitions over the usual `nexo.workflow.status` notifications. The boot
+`reconcile_interrupted!` sweep leaves `"suspended"` runs **untouched** — an
+intentional pause is never mistaken for an orphaned `"running"` run.
+
+← Back to the [README](../README.md)