nexo_ai 0.1.0 → 0.8.0

data/docs/durable-workflows.md

@@ -0,0 +1,230 @@
+# 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`).
+
+## Parallel checkpoints — `checkpoint_all`
+
+When several checkpoints are **independent** (no step depends on another's
+result), run them concurrently with `checkpoint_all(name => callable, …)` instead
+of a sequence of `checkpoint` calls. It fans the pending steps out through
+[`Nexo.concurrent`](concurrency.md) — all in flight at once — and persists **each
+step as it completes** (not the batch as a whole), so a resume after a partial
+failure only re-runs the steps that never landed:
+
+```ruby
+class BuildDashboard < Nexo::Workflow
+  def call(payload)
+    data = checkpoint_all(
+      account: -> { fetch_account(payload[:id]) },   # these two run
+      usage:   -> { fetch_usage(payload[:id]) }      # concurrently
+    )
+    { report: render(data[:account], data[:usage]) }
+  end
+end
+```
+
+`checkpoint_all` returns a Hash keyed by the **original** names you passed
+(`data[:account]`), with values read back from `state` — the same shape whether a
+value came from this pass or a prior one. Each newly-completed step also surfaces a
+`"checkpoint"`-typed event on the run's event log and the `nexo.workflow.event`
+notification (data is the step **name** only, never the value — so a dashboard can
+show batch progress without the event log carrying large or sensitive results).
+Steps already present in `state` are skipped silently and emit nothing.
+
+Bound the batch by how many keys you pass — there is no separate rate knob; every
+pending step goes in flight. Because it drives `Nexo.concurrent`, `checkpoint_all`
+needs the `async` gem **only when something is actually pending** — an
+all-persisted pass (every step already done) returns the prior values directly
+without touching concurrency. The same restrictions as `checkpoint` apply: values
+must be json-serializable, a step must **not** be named after a reserved state key
+(`__suspend__`/`__approval__`/`__buffer_events__` — raises `Nexo::Error` before any
+step runs), and do **not** call `suspend!` inside a step (undefined — unsupported).
+
+> **⚠️ Known trade-off: per-step persistence, not an atomic batch.** `checkpoint_all`
+> is **not** transactional. If step B raises after step A persisted, A stays in
+> `state`, B is absent, the run goes `"failed"`, and the exception propagates through
+> the workflow's normal failure path (`Nexo.concurrent`'s "first failure re-raises,
+> the rest stop" — it is not rescued away). A subsequent `execute` of the **same** run
+> re-submits only the still-missing names — A is skipped, B re-runs. Do **not** treat
+> a batch as all-or-nothing.
+
+## 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)

data/docs/getting-started.md

@@ -0,0 +1,103 @@
+# Getting started
+Install Nexo, configure the harness, and build your first agent.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "nexo_ai"
+```
+
+Or install directly:
+
+```sh
+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
+```
+
+## Configuration
+
+Configure the harness in one place with `Nexo.configure`. Defaults are safe and
+provider-neutral — there is intentionally no hardcoded model:
+
+```ruby
+Nexo.configure do |config|
+  config.default_model       = ENV["NEXO_MODEL"] # provider-neutral: no default
+  config.default_sandbox     = :virtual          # :virtual | :local | :docker | :apple | a Hash | a Sandbox
+  config.default_permissions = :read_only        # :read_only | :auto | :ask | :approve
+  config.skills_path         = "app/skills"
+  config.concurrency         = :threaded         # :threaded | :async (opt-in fiber offload)
+  config.max_in_flight       = 8                 # Nexo.concurrent fan-out bound
+  config.buffer_workflow_events = false          # buffer + flush-once workflow events
+end
+
+Nexo.config.default_sandbox      # => :virtual
+Nexo.config.default_permissions  # => :read_only
+Nexo.config.default_model        # => nil unless set
+```
+
+`require "nexo"` works in plain Ruby with no Rails loaded.
+
+## 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.
+
+## Unregistered models — local tags, self-hosted, brand-new releases
+
+`ruby_llm` normally validates a model id against its bundled `models.json` registry
+and infers the provider from it. A local Ollama tag (`gemma3:12b`), a self-hosted
+build, or a model newer than the installed registry isn't listed there — so declare
+the `provider` explicitly and set `assume_model_exists` to skip the registry lookup:
+
+```ruby
+class LocalReviewer < Nexo::Agent
+  model               "gemma3:12b"
+  provider            :ollama         # required once the registry lookup is skipped
+  assume_model_exists true            # opt out of models.json validation
+
+  instructions "You are a careful code reviewer."
+end
+```
+
+Both are class macros with the same reader/writer convention as `model`. `provider`
+is passed straight through to `RubyLLM.chat`; `assume_model_exists` defaults to
+`false` (registry validation on). Setting `assume_model_exists` **without** a
+`provider` raises `Nexo::ConfigurationError` — `ruby_llm` can't infer a provider once
+the lookup is skipped. See [`examples/code_reviewer.rb`](../examples/code_reviewer.rb)
+for a runnable Ollama example.
+
+← Back to the [README](../README.md)

data/docs/loops.md

@@ -0,0 +1,93 @@
+# Loop backends — swap the engine, not the agent
+The loop is the engine that drives one prompt to completion; swap it by constructor injection without touching the agent class.
+
+The **loop** is the engine that drives one prompt to completion. Swapping it is constructor
+injection (`loop:`) — the agent class never changes. Two backends ship:
+
+|                    | `Loops::RubyLLM` (default)         | `Loops::AgentSDK` (opt-in)            |
+| ------------------ | ---------------------------------- | ------------------------------------- |
+| Provider neutral   | ✅ any `ruby_llm` model            | ❌ Anthropic-oriented                 |
+| Tool source        | your sandbox-backed tools          | the SDK's own built-in/host tools     |
+| Turn cap           | observability only (see caveat)    | native `max_turns` hard cap           |
+| Execution location | your sandbox (virtual/local/remote)| the host process                      |
+
+The whole point: **same agent code, swapped backends**. Both examples are model-agnostic
+(`ENV.fetch("NEXO_MODEL")` — never a hardcoded `"claude-…"`):
+
+```ruby
+# Claude fast path — AgentSDK's own loop + host tools + native max_turns
+claude = Nexo::Agent.new(
+  model: ENV.fetch("NEXO_MODEL"),
+  sandbox: Nexo::Sandboxes::Local.new(cwd: "/srv/checkout"),
+  permissions: Nexo::Permissions.new(mode: :auto),
+  loop: Nexo::Loops::AgentSDK.new
+)
+
+# Any-provider path — your sandbox, your tools, human-in-the-loop
+gpt = Nexo::Agent.new(
+  model: ENV.fetch("NEXO_MODEL"),                # gpt-5.5, gemini, gemma3:12b via Ollama…
+  sandbox: Nexo::Sandboxes::Remote.new(client: my_container_client),
+  permissions: Nexo::Permissions.new(mode: :ask, on_ask: ->(cap, detail) {
+    SlackApproval.request!(capability: cap, detail: detail)
+  }),
+  loop: Nexo::Loops::RubyLLM.new
+)
+```
+
+`Loops::AgentSDK` wraps `RubyLLM::AgentSDK.query` and requires the **optional**
+`ruby_llm-agent_sdk` gem (lazy `require`; a clear `Nexo::MissingDependencyError` if it's
+absent). It maps Nexo's permission modes onto the SDK's own vocabulary:
+
+| Nexo mode    | AgentSDK `permission_mode` |
+| ------------ | -------------------------- |
+| `:read_only` | `:default`                 |
+| `:auto`      | `:bypass_permissions`      |
+| `:ask`       | `:default` (human gating stays in Nexo's own `on_ask` path, not delegated to the SDK) |
+| `:approve`   | `:default` (durable approval stays in Nexo's own gate; any unmapped mode also falls back to `:default`) |
+
+## The turn-cap caveat (read before running untrusted/expensive workloads)
+
+`ruby_llm` runs the whole tool loop inside `ask`, so `Loops::RubyLLM` has **no clean public
+hard "stop after N turns" halt** — `before_tool_call` gives turn-count *observability*, not a
+hard stop. (Confirmed: `ruby_llm` 1.16.0's `Chat` exposes no public max-turns/max-iterations
+setting.) Your three real options:
+
+(a) use `Loops::AgentSDK` (native `max_turns`) for untrusted/expensive workloads;
+(b) have a tool return `{ error: "turn limit reached, stop and summarize" }` once a turn
+    counter trips;
+(c) check whether the installed `ruby_llm` exposes a max-iterations config (in 1.16.0 it
+    does not).
+
+Do **not** ship `Loops::RubyLLM` for untrusted workloads claiming a hard cap that isn't
+proven.
+
+## Verified vs assumed
+
+Built against **`ruby_llm` 1.16** and **`ruby_llm-test` 0.2**. The tool body method is
+`#execute`, tools attach with `chat.with_tools(*instances)`, and instructions set with
+`chat.with_instructions`. `Open3.capture3` has no `timeout:` keyword on the target Ruby, so
+`Local#shell` bounds the command with `Timeout.timeout`. These may differ on other
+`ruby_llm` versions.
+
+`Loops::RubyLLM`'s turn-count observability uses `RubyLLM::Chat#before_tool_call` /
+`#after_tool_result`, confirmed present on `ruby_llm` 1.16.0 and guarded with `respond_to?`
+so a version lacking them degrades to no observability rather than crashing.
+`Loops::AgentSDK` targets `RubyLLM::AgentSDK.query`; `ruby_llm-agent_sdk` is **not** a
+dependency of this release, so that signature is **assumed** (per the gem's README) and
+verified-on-install — confirm it the moment you add the gem.
+
+## Live smoke (optional)
+
+The core suite is fully offline and deterministic (models stubbed with `ruby_llm-test`).
+A real end-to-end check is opt-in and env-gated — small local models like Gemma have weak
+tool-calling, so it may be flaky and is never a gating test:
+
+```sh
+ollama serve &
+NEXO_LIVE=1 NEXO_MODEL=gemma3:12b bundle exec rake test TEST=test/live_smoke_test.rb
+```
+
+If Gemma's tool-calling proves too weak, point `NEXO_MODEL` at a stronger model — the gem
+stays provider-neutral; only the smoke target changes.
+
+← Back to the [README](../README.md)

data/docs/mcp.md

@@ -0,0 +1,144 @@
+# MCP data sources
+Attach one or more MCP servers with a single `mcp` macro — every call gated by a second, fail-closed permission axis.
+
+An **MCP server** exposes tools to a model over the [Model Context
+Protocol](https://modelcontextprotocol.io) — Gmail, a filesystem, a fetch endpoint,
+Drive, and so on. Nexo does not implement MCP; it composes the
+[`ruby_llm-mcp`](https://github.com/patvice/ruby_llm-mcp) gem so you attach one or more
+servers with a single `mcp` macro and no client wiring. Because a server is reached
+*through the protocol* (never a vendor SDK), the behavior is identical on Anthropic, a
+local model, or anything else `ruby_llm` supports.
+
+```ruby
+require "nexo"
+
+class InboxDigest < Nexo::Agent
+  model       ENV.fetch("NEXO_MODEL")   # any ruby_llm model — never a hardcoded vendor default
+  permissions :read_only
+  mcp :gmail, transport: :stdio, command: "npx", args: %w[-y @modelcontextprotocol/server-gmail]
+  mcp :fs,    transport: :stdio, command: "npx", args: %w[-y @modelcontextprotocol/server-filesystem /data]
+  mcp :fetch, transport: :sse,   url: "http://localhost:8080/sse"
+  mcp_allow %w[search_threads get_thread]
+end
+```
+
+Each `mcp` line accumulates a server declaration. `name` and `transport` map onto the
+client's `name:`/`transport_type:`; every other keyword is passed through verbatim as the
+server's `config:` — `command:`/`args:` for `:stdio`, `url:` for `:sse`. The server's tools
+are attached to the chat after the sandbox tools and skills, and fire the same
+`before_tool_call`/`after_tool_result` observability callbacks, so MCP calls appear in a
+run's event log automatically.
+
+## Every MCP tool call is gated — and fails closed
+
+MCP tools obey a **second permission axis**, separate from the sandbox capability axis,
+because an MCP tool executes inside the server, outside the sandbox. `mcp_allow` is the
+exact-match allow-list threaded into the agent's permissions:
+
+| Mode | MCP tool behavior |
+|---|---|
+| `:read_only` (default) | allow **only** tool names listed in `mcp_allow`; everything else is denied |
+| `:ask` | call `on_ask.call(:mcp, {tool:, args:})`; a truthy return allows, else deny |
+| `:approve` | names in `mcp_allow` are pre-approved; any other tool needs a human decision — undecided **suspends the run** (`Nexo::ApprovalRequired`), `approved: true` allows, `approved: false` denies (the durable sibling of `:ask`) |
+| `:auto` | allow every MCP tool |
+
+`mcp_allow` defaults to `[]`, so attaching a powerful server under `:read_only` with no
+allow-list denies **every** tool — a misconfigured agent fails closed, not open. A denied
+call returns `{ error: … }` to the model (recoverable) and never raises into the loop —
+identical to the sandbox tools. Escalation (`:auto`, a populated `mcp_allow`, or `:ask`
+with a real `on_ask`) is always explicit in your code. Matching is exact tool-name only —
+no globs or regexes.
+
+**Two caveats — read before attaching a server:**
+
+1. **MCP tool *effects* are not sandboxed.** The gate covers the authority to *invoke* a
+   tool; the tool then runs in the MCP server, outside Nexo's sandbox. Nexo cannot
+   constrain what that server does with a call it is authorized to make — attaching a write
+   server and allowing a write tool means real writes happen. Gate deliberately, and prefer
+   `:read_only` with a tight `mcp_allow`.
+2. **Connection lifecycle.** Clients are built once and **memoized on the agent instance**,
+   reused across prompts (the `ruby_llm-mcp` client connects on construction and stays
+   connected). A long-lived agent holding stdio/SSE servers should call `Agent#close` when
+   done to tear the connections down:
+
+   ```ruby
+   agent = InboxDigest.new
+   agent.prompt("Summarize invoices from this week")
+   agent.prompt("Any follow-ups needed?")   # reuses the same live MCP connections
+   agent.close                              # stops every attached server
+   ```
+
+## HTTP-family servers + an OAuth `token:` provider
+
+Beyond `:stdio`, Nexo attaches a server over any HTTP-family transport `ruby_llm-mcp`
+supports — `transport: :http`, `:sse`, or `:streamable`. For an OAuth-authenticated
+hosted server (Gmail, Drive, …) add a `token:` — a static bearer `String`, or a
+**callable** re-read close to connection time. Nexo resolves it and injects an
+`Authorization: Bearer <token>` header per connection:
+
+```ruby
+class InboxTriageHTTP < Nexo::Agent
+  model       ENV.fetch("NEXO_MODEL")
+  permissions :read_only
+
+  # Hosted Gmail MCP server over HTTP; the host supplies the OAuth access token.
+  mcp :gmail,
+    transport: :http,
+    url:       ENV.fetch("GMAIL_MCP_URL"),
+    token:     -> { Current.user.gmail_access_token }   # re-read at connection time
+
+  # READ tools only — the unchanged gate denies send/trash/modify.
+  mcp_allow %w[search_threads get_thread list_messages get_message list_labels]
+end
+```
+
+A static token (`token: ENV.fetch("GMAIL_TOKEN")`) is equally valid. Under the hood
+Nexo strips `token:` and hands off:
+
+```ruby
+RubyLLM::MCP.client(
+  name: "gmail", transport_type: :http,
+  config: { url: "https://…", headers: { "Authorization" => "Bearer <resolved>" } }
+)
+```
+
+Any other `headers:` you pass are preserved; Nexo's `Authorization` wins. With no
+`token:`, `config:` passes through byte-for-byte (no `headers` key) — the `:stdio` path
+is untouched.
+
+**Nexo does not own the OAuth flow.** It performs no authorization-code exchange, no
+token refresh, and keeps no token store — that is your app or an OAuth library. Nexo's
+only job is to call the provider, inject the header, and hand off. The token is never
+logged, persisted, placed in a URL/query string, or emitted in an event (the event path
+carries only tool `name`/`args` and return values — never connection config).
+
+**Refresh / reconnect caveat.** `ruby_llm-mcp`'s HTTP-family transports snapshot the
+`headers` hash **at construction** — there is no per-request header callback for a plain
+`headers` Hash. A callable `token:` is therefore resolved **once**, when the client is
+built, and the client is memoized on the agent instance across prompts. So when a token
+**rotates**, tear the connection down and reconnect to pick up the new value:
+
+```ruby
+agent.close                  # stops the memoized MCP client
+agent.prompt("…")            # a fresh prompt rebuilds the client → token: re-resolved
+```
+
+**The gate is unchanged.** An HTTP OAuth server's tools are gated exactly like `:stdio`
+tools: denied under `:read_only` until the exact name is in `mcp_allow` (default `[]` ⇒
+deny-all). Attaching an authenticated server adds no permission surface.
+
+**Two honest caveats — read before attaching a token:**
+
+1. **Refresh may require a reconnect.** Because headers are construction-only,
+   a rotated token needs `agent.close` + a fresh prompt (above), not just a new proc
+   return. A static token stays constant for the client's life.
+2. **The token is a live credential.** Even gated, an authorized MCP call runs its effect
+   server-side — a leaked bearer is a real compromise. Nexo keeps it out of logs, events,
+   persisted `WorkflowRun` records, and URLs; your host code must do the same. Nexo does
+   not police `ruby_llm-mcp`'s own internal logging of headers — that boundary is yours.
+
+`ruby_llm-mcp` is an **optional** dependency — required lazily only when you attach a
+server. Without it installed, `require "nexo"` still loads; building a server raises a clear
+`Nexo::MissingDependencyError` telling you to add `gem "ruby_llm-mcp"`.
+
+← Back to the [README](../README.md)

data/docs/permissions.md

@@ -0,0 +1,47 @@
+# Permissions
+The permission mode is *what* an agent's tools may do — read-only by default, with `:auto`, `:ask`, and `:approve` escalations; the separate MCP tool gate lives in [MCP](mcp.md).
+
+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.
+
+## Human-gated writes (`:ask`)
+
+`:ask` mode defers every write/shell action to your callback. Build a `Permissions` with
+an `on_ask` hook and pass it in:
+
+```ruby
+gate = Nexo::Permissions.new(mode: :ask, on_ask: ->(cap, detail) {
+  $stdout.print("Allow #{cap} #{detail}? [y/N] "); $stdin.gets.strip == "y"
+})
+
+class Editor < Nexo::Agent
+  model   ENV.fetch("NEXO_MODEL")
+  sandbox :local
+end
+
+Editor.new(cwd: ".", permissions: gate).prompt("Fix the typo in README.md")
+```
+
+(The bare `:ask` symbol resolves to `Permissions.new(mode: :ask)` with **no** callback, so
+writes/shell are denied — pass a pre-built `Permissions` with `on_ask` for a real gate.)
+
+← Back to the [README](../README.md)