nexo_ai 0.1.0 → 0.8.0

data/lib/nexo/agent.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+module Nexo
+  # The DSL that composes a model, a sandbox, permissions, and instructions into
+  # a working tool-using agent. Subclass it and declare the pieces with class
+  # macros, then call +#prompt+:
+  #
+  #   class CodeReviewer < Nexo::Agent
+  #     model       ENV.fetch("NEXO_MODEL")
+  #     sandbox     :local
+  #     permissions :read_only
+  #     instructions "You are a careful code reviewer."
+  #   end
+  #
+  #   CodeReviewer.new(cwd: "/path/to/repo").prompt("Review the auth module")
+  #
+  # No sandbox, permission, or tool object is instantiated by hand. Defaults are
+  # safe: +:virtual+ sandbox + +:read_only+ permissions unless overridden.
+  class Agent
+    # The class-level ivars every macro reads/writes. Copied to a subclass in
+    # .inherited so `class Child < ConfiguredAgent; end` keeps the parent's
+    # configuration instead of silently resetting to defaults.
+    CONFIG_IVARS = %i[
+      @model @assume_model_exists @provider @sandbox @permissions @instructions
+      @skills @mcp @mcp_allow @fetch_allow @search_backend
+    ].freeze
+
+    class << self
+      # Carries the parent's macro configuration onto a subclass. Arrays/Hashes are
+      # duped so a subclass extending an accumulating macro (e.g. a second +mcp+
+      # line) never mutates the parent's collection; scalars and shared config
+      # instances (a class-level Permissions) are copied by reference.
+      def inherited(subclass)
+        super
+        CONFIG_IVARS.each do |ivar|
+          next unless instance_variable_defined?(ivar)
+
+          value = instance_variable_get(ivar)
+          value = value.dup if value.is_a?(Array) || value.is_a?(Hash)
+          subclass.instance_variable_set(ivar, value)
+        end
+      end
+
+      # Each macro is a reader with no argument and a writer with one. Unset
+      # +sandbox+/+permissions+ fall back to the harness-wide config defaults.
+      def model(value = nil)
+        value.nil? ? @model : (@model = value)
+      end
+
+      # Opt out of ruby_llm's models.json registry validation for this agent so
+      # it can run unregistered models (Ollama tags, self-hosted, brand-new
+      # releases). Boolean opt-in: because +nil?+ still distinguishes read from
+      # write, +assume_model_exists false+ is an explicit write (sets +false+),
+      # not a read. Unset reads as +false+, keeping registry validation on.
+      def assume_model_exists(value = nil)
+        value.nil? ? (@assume_model_exists || false) : (@assume_model_exists = value)
+      end
+
+      # The provider symbol/string (e.g. +:ollama+) passed straight through to
+      # +RubyLLM.chat+. Required whenever +assume_model_exists+ is set, since
+      # ruby_llm cannot infer a provider once the registry lookup is skipped.
+      # Unset resolves to +nil+.
+      def provider(value = nil)
+        value.nil? ? @provider : (@provider = value)
+      end
+
+      # The sandbox macro. With no argument it reads the configured value
+      # (falling back to the harness-wide default). With a bare value it stores a
+      # symbol/instance as before; with keywords it stores an options Hash
+      # (+{ type: value, **opts }+) resolved by Nexo::Sandboxes.resolve — e.g.
+      # +sandbox :docker, image: "node:22-slim", binds: {...}+.
+      def sandbox(value = nil, **opts)
+        return @sandbox || Nexo.config.default_sandbox if value.nil? && opts.empty?
+
+        @sandbox = opts.empty? ? value : {type: value, **opts}
+      end
+
+      # The permissions macro. With no argument it reads the configured value
+      # (falling back to the harness-wide default, +:read_only+); with a value it
+      # records the mode symbol or a pre-built Permissions instance.
+      def permissions(value = nil)
+        value.nil? ? (@permissions || Nexo.config.default_permissions) : (@permissions = value)
+      end
+
+      # The instructions macro. With no argument it reads the stored system
+      # prompt (default +nil+); with a value it records it.
+      def instructions(value = nil)
+        value.nil? ? @instructions : (@instructions = value)
+      end
+
+      # Declares the skills attached to this agent. With no args it returns the
+      # configured list (default +[]+); with args it ACCUMULATES the names
+      # (deduped), so multiple +skills+ lines add up instead of the last one
+      # silently replacing the earlier ones — consistent with +mcp+.
+      #
+      #   class TriageAgent < Nexo::Agent
+      #     model ENV.fetch("NEXO_MODEL")
+      #     skills :triage          # one macro, no loader setup
+      #     skills :formatting      # adds to :triage, does not replace it
+      #   end
+      def skills(*names)
+        names.empty? ? (@skills || []) : (@skills = ((@skills || []) + names).uniq)
+      end
+
+      # Declares an MCP server for this agent (Spec 6). Accumulating: multiple
+      # +mcp+ lines are collected. With no args (+name+ nil and +opts+ empty) it
+      # reads the list (default +[]+); otherwise it appends the friendly,
+      # transport-shaped config consumed by Nexo::MCP.build.
+      #
+      #   class InboxDigest < Nexo::Agent
+      #     model ENV.fetch("NEXO_MODEL")
+      #     mcp :gmail, transport: :stdio, command: "npx", args: %w[-y srv-gmail]
+      #     mcp :fetch, transport: :sse,   url: "http://localhost:8080/sse"
+      #   end
+      def mcp(name = nil, **opts)
+        return @mcp || [] if name.nil? && opts.empty?
+
+        (@mcp ||= []) << opts.merge(name: name)
+      end
+
+      # The MCP tool-name allow-list threaded into this agent's Permissions (see
+      # +mcp_allow:+ in #resolve_permissions). Exact tool-name match only — no
+      # globs. Like +skills+, with args it ACCUMULATES the flattened names as
+      # strings (deduped); with none it reads the list (default +[]+).
+      def mcp_allow(*names)
+        names.empty? ? (@mcp_allow || []) : (@mcp_allow = ((@mcp_allow || []) + names.flatten.map(&:to_s)).uniq)
+      end
+
+      # The host allow-list scoping this agent's Nexo::Tools::Fetch (Spec 9).
+      # Subdomain-aware, exact-host-suffix matching only — no globs. Like
+      # +skills+/+mcp_allow+, with args it ACCUMULATES the flattened hosts as
+      # strings (deduped); with none it reads the list (default +[]+).
+      #
+      # Declaring +fetch_allow+ only SCOPES hosts — it does not grant the +:fetch+
+      # capability, which is default-denied like +:shell+. An agent that wants
+      # egress must also run under +:auto+ or carry an explicit
+      # +Permissions.new(mode: :read_only, allow: %i[read glob fetch])+. Both locks
+      # must open before a fetch happens.
+      def fetch_allow(*hosts)
+        hosts.empty? ? (@fetch_allow || []) : (@fetch_allow = ((@fetch_allow || []) + hosts.flatten.map(&:to_s)).uniq)
+      end
+
+      # The host-injected search backend for this agent's Nexo::Tools::WebSearch
+      # (Spec 19). Reader/writer by nil-check, matching the +model+ macro
+      # convention. Any object responding to +search(query, **opts)+ that
+      # returns an Enumerable of +{title:, url:, snippet:}+ rows works — Nexo ships
+      # no backend. Unset reads as +nil+, in which case no search tool is attached.
+      #
+      # Declaring +search_backend+ does not grant the +:search+ capability, which is
+      # default-denied like +:fetch+/+:shell+. An agent that wants web discovery must
+      # also run under +:auto+ or carry an explicit +allow: [..., :search]+.
+      def search_backend(obj = nil)
+        obj.nil? ? @search_backend : (@search_backend = obj)
+      end
+    end
+
+    # The set of tool names handed to an opt-in backend that ships its own tools
+    # (e.g. Loops::AgentSDK). The default Loops::RubyLLM ignores this — it
+    # uses the agent's own sandbox-backed tools instead.
+    ALLOWED_TOOLS = %w[Read Write Edit Bash Glob Grep].freeze
+
+    # Maps Nexo's permission modes onto AgentSDK's own permission vocabulary,
+    # consumed by Loops::AgentSDK. +:ask+ maps to +:default+ on purpose: human
+    # gating stays in Nexo's own +on_ask+ path and is not delegated to the SDK.
+    PERMISSION_MODE_MAP = {
+      read_only: :default,
+      auto: :bypass_permissions,
+      ask: :default
+    }.freeze
+
+    # The resolved per-instance configuration (arg → class macro → config): the
+    # working directory, model, provider, +assume_model_exists+ flag, the resolved
+    # Sandbox and Permissions, the system instructions, and the injected Loop.
+    attr_reader :cwd, :model, :provider, :assume_model_exists, :sandbox, :permissions, :instructions, :loop
+
+    # Every argument is optional; each resolves arg -> class macro -> config.
+    # Symbol shorthands (:virtual/:local, :read_only/:auto/:ask/:approve) and
+    # pre-built Sandbox/Permissions instances are both accepted. +loop:+ injects
+    # the engine that drives a prompt — the provider-neutral Loops::RubyLLM by
+    # default, or an opt-in backend like Loops::AgentSDK.
+    #
+    # +decision:+ (Spec 16, default +nil+) is a per-run approval answer
+    # (+{approved: true|false}+) threaded into the resolved Permissions so an
+    # +:approve+ gate allows/denies instead of raising Nexo::ApprovalRequired.
+    # It only supplies the *answer* to an already-+:approve+ gate — it never
+    # widens capability. Workflow#run_agent passes it on the resume pass.
+    def initialize(cwd: Dir.pwd, model: nil, sandbox: nil, permissions: nil, decision: nil, loop: Loops::RubyLLM.new)
+      @cwd = cwd
+      @model = model || self.class.model || Nexo.config.default_model
+      if @model.nil?
+        raise ConfigurationError,
+          "no model set — use the `model` macro, pass model:, or set Nexo.config.default_model"
+      end
+
+      @assume_model_exists = self.class.assume_model_exists
+      @provider = self.class.provider
+      if @assume_model_exists && @provider.nil?
+        raise ConfigurationError,
+          "assume_model_exists is set but no provider given — add the `provider` macro (e.g. `provider :ollama`)"
+      end
+
+      # The agent owns (and so closes) its sandbox only when it resolved one from
+      # its own config. A sandbox injected via +sandbox:+ (e.g. Workflow#run_agent
+      # sharing the run's sandbox) is BORROWED — closing it would strand the owner.
+      @owns_sandbox = sandbox.nil?
+      @sandbox = resolve_sandbox(sandbox || self.class.sandbox)
+      @permissions = resolve_permissions(permissions || self.class.permissions, decision: decision)
+      @instructions = self.class.instructions
+      @loop = loop
+    end
+
+    # Builds a configured chat with the four sandbox-backed tools attached as
+    # instances bound to this agent's sandbox and permissions, then layers on the
+    # instructions of every declared skill.
+    #
+    # +base:+ lets a Nexo::Session pass a persisted +acts_as_chat+ record
+    # (hydrated via ruby_llm's +#to_llm+ delegation) so the very same wiring —
+    # instructions, the four sandbox tools, skills, MCP, fetch — is applied onto
+    # the continuing thread instead of a fresh chat. When +base+ is nil the path
+    # is byte-for-byte the standalone-agent build: a fresh +RubyLLM.chat+. A
+    # session therefore changes only *memory/persistence*, never authority or
+    # execution — the record supplies the thread, the agent supplies the wiring.
+    #
+    # Re-applying +@instructions+ on every resume stays idempotent because the
+    # persisted-chat +#with_instructions+ (default +append: false+) *replaces* the
+    # stored +role: :system+ messages rather than appending, so the thread keeps
+    # exactly one copy across resumes (VERIFIED, ruby_llm 1.16.0).
+    def chat(base: nil)
+      c = base || RubyLLM.chat(**chat_model_options)
+      c = apply_instructions(c)
+
+      # One ReadTracker per chat, shared by ReadFile (records) and WriteFile
+      # (enforces the read-before-write + stale guard) — R4.
+      tracker = ReadTracker.new
+      tools = [
+        Tools::ReadFile.new(sandbox: @sandbox, permissions: @permissions, tracker: tracker),
+        Tools::WriteFile.new(sandbox: @sandbox, permissions: @permissions, tracker: tracker),
+        Tools::Glob.new(sandbox: @sandbox, permissions: @permissions)
+      ]
+      # Attach Shell only when the sandbox can actually run one (R2), so a
+      # :virtual agent stops advertising a tool it can never run.
+      if @sandbox.supports?(:shell)
+        tools << Tools::Shell.new(sandbox: @sandbox, permissions: @permissions)
+      end
+      c.with_tools(*tools)
+      apply_mcp(c)
+      apply_fetch(c)
+      apply_search(c)
+      c
+    end
+
+    # Runs one prompt through the agent by delegating to the injected loop. The
+    # loop body that used to live here is now in Loops::RubyLLM (the default),
+    # so swapping +loop:+ swaps the engine without touching this class. The
+    # optional +&on_event+ block receives +(type, payload)+ progress events.
+    def prompt(text, max_turns: 25, &on_event)
+      @loop.run(agent: self, prompt: text, max_turns: max_turns, &on_event)
+    end
+
+    # The agent's Nexo permission mode mapped onto an opt-in backend's own
+    # permission vocabulary (see PERMISSION_MODE_MAP). Consumed by
+    # Loops::AgentSDK; the default Loops::RubyLLM does its gating inside the
+    # sandbox-backed tools and ignores this.
+    def permission_mode
+      PERMISSION_MODE_MAP.fetch(@permissions.mode, :default)
+    end
+
+    # The tool names handed to an opt-in backend that ships its own tools.
+    def allowed_tools
+      ALLOWED_TOOLS
+    end
+
+    # Releases any MCP server connections held by this agent instance. Clients are
+    # memoized on the instance and reused across prompts (Spec 6 lifecycle default),
+    # so a long-lived agent holding stdio/SSE servers should call +#close+ when
+    # done. Idempotent: safe to call with no MCP servers attached or more than once.
+    #
+    # VERIFY (Group 0, ruby_llm-mcp 1.0.0): the client teardown method is +#stop+
+    # (guarded by +respond_to?+, falling back to +#close+ for other client shapes).
+    def close
+      @mcp_clients&.each do |client|
+        if client.respond_to?(:stop)
+          client.stop
+        elsif client.respond_to?(:close)
+          client.close
+        end
+      rescue
+        # Best-effort teardown: a failing stop on one client must not strand the
+        # remaining clients or leave @mcp_clients set (breaking idempotency).
+        # Swallow and continue to the next.
+      end
+      @mcp_clients = nil
+
+      # Release the sandbox too, so a container/remote-backed agent doesn't leak
+      # its container/connection when the caller only remembers +close+. Only close
+      # a sandbox this agent OWNS (resolved from its own config) — a borrowed one
+      # (injected via +sandbox:+, e.g. Workflow#run_agent's shared run sandbox) is
+      # the injector's to close. The base Sandbox#close is a no-op, so this is safe
+      # and idempotent for :virtual/:local. Best-effort: never raise out of close.
+      if @owns_sandbox
+        begin
+          @sandbox&.close
+        rescue
+          # Swallow: close must stay idempotent and non-raising.
+        end
+      end
+    end
+
+    private
+
+    # Builds the +RubyLLM.chat+ options conditionally so the default agent's
+    # call is byte-for-byte what it was before this feature: +{model: @model}+.
+    # +provider+ is added only when resolved; +assume_model_exists: true+ only
+    # when opted in (never passed as +false+).
+    def chat_model_options
+      opts = {model: @model}
+      opts[:provider] = @provider if @provider
+      opts[:assume_model_exists] = true if @assume_model_exists
+      opts
+    end
+
+    # Applies the full system-prompt stack to +chat+ in deterministic order: the
+    # agent's own instructions, then the self-describing sandbox instructions (R1),
+    # then each declared skill's body. A skill contributes instructions only — it
+    # ships no independent tools (its scripts/references are reached through the
+    # already-gated sandbox tools), so attaching one never widens the agent.
+    #
+    # The FIRST contribution is applied with +append: false+ and the rest with
+    # +append: true+. On a fresh chat that is byte-for-byte the prior behavior; on
+    # a Nexo::Session's persisted, re-hydrated chat the leading +append: false+
+    # collapses all prior +role: :system+ messages to one before the rest
+    # re-append, so N resumes keep exactly ONE copy of the stack — even when the
+    # agent declares no +instructions+ (the case that previously let skills/sandbox
+    # instructions accumulate a fresh copy per resume).
+    def apply_instructions(chat)
+      texts = []
+      texts << @instructions if @instructions
+      texts << @sandbox.instructions if @sandbox.instructions
+      self.class.skills.each { |name| texts << Skills.find(name).content }
+
+      texts.each_with_index do |text, i|
+        chat = chat.with_instructions(text, append: i.positive?)
+      end
+      chat
+    end
+
+    # Lazily connects the declared MCP servers and attaches their tools, each
+    # wrapped in a MCP::GatedTool so every invocation is authorized through this
+    # agent's Permissions first. Attached after the four sandbox tools and the
+    # skills, so MCP tools fire the chat's +before_tool_call+/+after_tool_result+
+    # callbacks (wired in Loops::RubyLLM) and appear in the run's event log with
+    # no extra wiring. Returns early when no server is declared.
+    #
+    # Clients are built once and memoized on the instance (Spec 6 lifecycle
+    # default): the +ruby_llm-mcp+ client connects on construction and is reusable
+    # across prompts, so subsequent +#chat+ calls reuse the live connections until
+    # #close. VERIFY (Group 0): tools accessor is +client.tools+ (an Array).
+    def apply_mcp(chat)
+      return if self.class.mcp.empty?
+
+      @mcp_clients ||= self.class.mcp.map { |cfg| Nexo::MCP.build(**cfg) }
+      gated = @mcp_clients.flat_map(&:tools).map do |tool|
+        Nexo::MCP::GatedTool.new(tool: tool, permissions: @permissions)
+      end
+      chat.with_tools(*gated) unless gated.empty?
+    end
+
+    # Attaches a single Nexo::Tools::Fetch scoped to the agent's +fetch_allow+
+    # hosts (Spec 9). Returns early when no host is declared, so an agent that never
+    # calls +fetch_allow+ gets no fetch tool. Attached right after +apply_mcp+ so
+    # the tool participates in the chat's +before_tool_call+/+after_tool_result+
+    # event stream (wired in Loops::RubyLLM) with no extra wiring. The +:fetch+
+    # capability itself is gated through Permissions#authorize! at call time — the
+    # allow-list only scopes hosts, it is not the capability grant.
+    def apply_fetch(chat)
+      return if self.class.fetch_allow.empty?
+
+      chat.with_tools(
+        Tools::Fetch.new(sandbox: @sandbox, permissions: @permissions, allow_hosts: self.class.fetch_allow)
+      )
+    end
+
+    # Attaches a single Nexo::Tools::WebSearch bound to the agent's injected
+    # +search_backend+ (Spec 19). Returns early when no backend is declared, so an
+    # agent that never calls +search_backend+ gets no search tool — existing agents
+    # are byte-for-byte unchanged. Attached right after +apply_fetch+ so the tool
+    # rides the same +before_tool_call+/+after_tool_result+ event stream (wired in
+    # Loops::RubyLLM) with no extra wiring. The +:search+ capability itself is gated
+    # through Permissions#authorize! at call time.
+    def apply_search(chat)
+      backend = self.class.search_backend or return
+
+      chat.with_tools(
+        Tools::WebSearch.new(sandbox: @sandbox, permissions: @permissions, backend: backend)
+      )
+    end
+
+    # Resolves this agent's sandbox declaration via the shared resolver (Spec 15),
+    # passing the agent's instance +@cwd+ as the host working directory (used only
+    # by +:local+; container tiers keep their own +/workspace+ default).
+    def resolve_sandbox(value) = Sandboxes.resolve(value, cwd: @cwd)
+
+    def resolve_permissions(value, decision: nil)
+      # A user-supplied Permissions sets its own mcp_allow: — leave it untouched.
+      # Thread a per-run approval decision through a non-mutating copy (Spec 16)
+      # so a shared, class-level :approve instance is never clobbered.
+      if value.is_a?(Permissions)
+        return decision ? value.with_decision(decision) : value
+      end
+
+      # Thread the class-level mcp_allow into each symbol branch (Spec 6) so the
+      # MCP capability axis is populated alongside the sandbox axis.
+      allow = self.class.mcp_allow
+      case value
+      when :read_only then Permissions.new(mode: :read_only, mcp_allow: allow)
+      when :auto then Permissions.new(mode: :auto, allow: %i[read glob write shell fetch search], mcp_allow: allow)
+      when :ask then Permissions.new(mode: :ask, mcp_allow: allow) # pass a Permissions with on_ask for a real gate
+      when :approve then Permissions.new(mode: :approve, mcp_allow: allow, decision: decision)
+      else raise ConfigurationError, "unknown permissions: #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/nexo/concurrent.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Nexo
+  # Bounded fan-out driver for running many agent/workflow calls concurrently on
+  # Ruby's fiber scheduler (Spec 5). It is the value Nexo adds over a raw
+  # +Async {}+ block: *rate-bounded* concurrency (so you stay under provider rate
+  # limits) with proper error propagation (the first task failure is re-raised,
+  # never swallowed) and results returned in **submission order**.
+  #
+  #   results = Nexo.concurrent(max_in_flight: 8) do |c|
+  #     docs.each { |d| c.add { SummarizeDocument.run(text: d.body).result } }
+  #   end
+  #   # => one result per doc, in doc order, never more than 8 calls in flight
+  #
+  # +async+ is a SOFT (optional) dependency: it is required lazily the moment a
+  # fan-out actually runs. With the gem absent, +require "nexo"+ still loads
+  # cleanly; only calling Nexo.concurrent raises MissingDependencyError.
+  class Concurrent
+    # A submitted unit of work. Wrapping the block in a Struct keeps submission
+    # order explicit (the index into +@tasks+ is the index into the results).
+    Task = Struct.new(:block)
+
+    # +max_in_flight+ bounds how many submitted blocks run concurrently once the
+    # collector is run inside an +async+ reactor.
+    def initialize(max_in_flight:)
+      @max_in_flight = max_in_flight
+      @tasks = []
+    end
+
+    # Registers a block to run. Called via the yielded collector inside
+    # Nexo.concurrent. Order of +add+ calls is the order of the results array.
+    def add(&block)
+      @tasks << Task.new(block)
+    end
+
+    # Runs every added block inside ONE reactor, bounding in-flight work with an
+    # +Async::Semaphore+ and coordinating with an +Async::Barrier+. Results are
+    # index-assigned, so the returned Array is in submission order regardless of
+    # completion order. On the first task that raises, the error propagates out
+    # of +barrier.wait+ and the +ensure+ stops the remaining in-flight tasks —
+    # errors are never swallowed.
+    def run
+      require_async!
+      results = Array.new(@tasks.size)
+
+      Async do |task|
+        semaphore = Async::Semaphore.new(@max_in_flight, parent: task)
+        barrier = Async::Barrier.new(parent: semaphore)
+
+        @tasks.each_with_index do |t, i|
+          barrier.async { results[i] = t.block.call }
+        end
+
+        # barrier.wait re-raises the first task failure (no silent swallowing).
+        barrier.wait
+      ensure
+        barrier&.stop
+      end.wait
+
+      results
+    end
+
+    private
+
+    # Lazily loads +async+ and its coordination primitives, mirroring the
+    # soft-dependency precedent in Skills.load! / Loops::AgentSDK: a bare
+    # +require+ (so tests can stub it on the instance) rescuing stdlib +LoadError+
+    # into a MissingDependencyError that names the gem and the exact remedy.
+    def require_async!
+      require "async"
+      require "async/barrier"
+      require "async/semaphore"
+    rescue LoadError
+      raise Nexo::MissingDependencyError,
+        'Concurrency requires the `async` gem. Add `gem "async", "~> 2.0"` to your Gemfile.'
+    end
+  end
+end

data/lib/nexo/configuration.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Nexo
+  # Holds the harness-wide defaults. Accessed through Nexo.config and
+  # mutated through Nexo.configure. Every default is safe-by-default and
+  # provider-neutral — there is intentionally no hardcoded model.
+  class Configuration
+    # The default ruby_llm model id. +nil+ means none chosen — provider-neutral.
+    attr_accessor :default_model
+
+    # The default sandbox: +:virtual+ (in-memory, zero host access).
+    attr_accessor :default_sandbox
+
+    # The default permission mode: +:read_only+.
+    attr_accessor :default_permissions
+
+    # Where SKILL.md packages live. Rails-aware: +app/skills+ under the app root.
+    attr_accessor :skills_path
+
+    # Concurrency mode (Spec 5): +:threaded+ (default) | +:async+. This is the
+    # single switch that gates the Sandboxes::Local offload path — under
+    # +:async+ its blocking file/shell I/O runs on a worker thread so it does not
+    # stall a fiber reactor; under +:threaded+ it runs inline (zero overhead,
+    # byte-for-byte the Spec 1 behavior). It does NOT gate Nexo.concurrent,
+    # which always runs its own reactor when called.
+    attr_accessor :concurrency
+
+    # Max in-flight tasks for Nexo.concurrent fan-out (Spec 5), default +8+.
+    # The single most important knob for staying under provider rate limits.
+    attr_accessor :max_in_flight
+
+    # Whether Workflow buffers events in memory and flushes once at the end of
+    # a run instead of persisting per +emit+ (Spec 5), default +false+. Buffering
+    # avoids a blocking per-event DB write under a fiber reactor.
+    attr_accessor :buffer_workflow_events
+
+    # The host +acts_as_chat+ model that stores Nexo::Session threads (Spec 10),
+    # given as a **String** class name (default +"Chat"+ — ruby_llm's own default).
+    # It is constantized lazily at resume time so plain Ruby / no-ActiveRecord
+    # paths never reference an AR constant, mirroring how RunStore only touches
+    # Nexo::WorkflowRun when it is defined. The host app owns this model (columns
+    # + a unique +(agent_name, instance_id)+ index); Nexo ships no migration for it.
+    attr_accessor :session_chat_model
+
+    # Whether to mirror run event notifications over Turbo Streams (Spec 11 R2),
+    # default +false+ (safe-by-default). When true and turbo-rails is present, the
+    # engine subscribes Nexo::TurboBroadcaster at boot. The plain
+    # +nexo.workflow.event+/+nexo.workflow.status+ notifications fire regardless —
+    # this only gates the opt-in Turbo mirror.
+    attr_accessor :broadcast_events
+
+    # The ActiveJob queue Workflow.run_later enqueues onto (Spec 11 R1), default
+    # +nil+ → ActiveJob's default queue. Set to a symbol (e.g. +:nexo+) to route
+    # workflow jobs to a dedicated queue.
+    attr_accessor :job_queue
+
+    # Seeds the safe, provider-neutral defaults (no model, +:virtual+ sandbox,
+    # +:read_only+ permissions, +:threaded+ concurrency).
+    def initialize
+      @default_model = nil # provider-neutral: NO hardcoded default
+      @default_sandbox = :virtual # safe default
+      @default_permissions = :read_only # safe default
+      @skills_path = default_skills_path
+      @concurrency = :threaded # async is opt-in; :threaded stays the default
+      @max_in_flight = 8
+      @buffer_workflow_events = false
+      @session_chat_model = "Chat" # ruby_llm's own default acts_as_chat host
+      @broadcast_events = false # safe default: opt in to the Turbo mirror
+      @job_queue = nil # nil → ActiveJob's default queue
+    end
+
+    private
+
+    def default_skills_path
+      if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+        ::Rails.root.join("app/skills").to_s
+      else
+        "skills"
+      end
+    end
+  end
+end

data/lib/nexo/engine.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Rails-optional: this file is required from lib/nexo.rb only when Rails is
+# present, and is additionally guarded here so requiring it directly in plain
+# Ruby never raises. The engine wires Nexo's generator and rake task into a host
+# Rails app and loads the WorkflowRun model once ActiveRecord is available.
+if defined?(::Rails::Engine)
+  module Nexo
+    # The Rails engine that wires Nexo into a host app: it loads the WorkflowRun
+    # model and WorkflowJob during boot, opt-in-subscribes the Turbo broadcaster,
+    # and (via Rails::Engine) exposes Nexo's generators and rake tasks. Defined
+    # only when +::Rails::Engine+ is present, so the plain-Ruby core stays
+    # Rails-free.
+    class Engine < ::Rails::Engine
+      isolate_namespace Nexo
+
+      # Load the WorkflowRun model during boot so RunStore.default reliably
+      # selects the ActiveRecord backend (it checks defined?(Nexo::WorkflowRun)).
+      # A plain on_load(:active_record) hook is not enough: it only fires once
+      # AR::Base is touched, which may not happen before a command runs — e.g.
+      # `rake nexo:logs` would otherwise boot, never load AR, and fall back to
+      # the Memory store. Requiring the file directly is safe: its body is
+      # guarded, so in a Rails app with no ActiveRecord it defines nothing and
+      # RunStore.default falls back to Memory.
+      initializer "nexo.workflow_run_model" do
+        require "nexo/workflow_run"
+      end
+
+      # Load the WorkflowJob once ActiveJob is available (Spec 11 R1), mirroring the
+      # workflow_run model initializer above. The require is safe with no ActiveJob:
+      # the file body is guarded, so it defines nothing and Workflow.run_later raises
+      # a MissingDependencyError instead.
+      initializer "nexo.workflow_job" do
+        require "nexo/workflow_job"
+      end
+
+      # Wire the opt-in Turbo mirror (Spec 11 R2). The require is always safe (the
+      # broadcaster's body is guarded on ActiveSupport::Notifications); subscribe! is
+      # a no-op without turbo-rails. Only subscribe when the host opted in via
+      # config.broadcast_events — safe-by-default (broadcast_events defaults false).
+      initializer "nexo.turbo_broadcaster" do
+        require "nexo/turbo_broadcaster"
+        Nexo::TurboBroadcaster.subscribe! if Nexo.config.broadcast_events
+      end
+
+      # The nexo:logs rake task ships in lib/tasks/nexo.rake, which Rails::Engine
+      # loads into the host app automatically — no explicit rake_tasks wiring
+      # (loading it a second time would run the task body twice).
+    end
+  end
+end

data/lib/nexo/loop.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Nexo
+  # The loop seam: the engine that drives one prompt to completion. Swapping the
+  # loop swaps *how* the agent's turns are run — the plain provider-neutral
+  # +ruby_llm+ tool loop, or an opt-in vendor-tuned backend — by constructor
+  # injection, with no change to the agent class.
+  #
+  # A loop implements the contract below. The base class raises so an incomplete
+  # subclass fails loudly. The optional +&on_event+ block, when given, is called
+  # with +(type, payload)+ as the run progresses (e.g. +:tool_call+,
+  # +:tool_result+, +:done+) — observability only; it never steers the run.
+  #
+  # See Loops::RubyLLM (default, provider-neutral) and Loops::AgentSDK
+  # (opt-in, Anthropic-oriented).
+  class Loop
+    # Runs +prompt+ through +agent+ and returns the final response. +max_turns+
+    # is a hint a backend may enforce as a hard cap (AgentSDK) or expose only as
+    # observability (RubyLLM — see the turn-cap caveat in the README).
+    #
+    # +chat:+ (default +nil+) lets a Nexo::Session inject a hydrated, continuing
+    # chat so the loop runs over the persisted thread. It is part of the base
+    # contract so every backend accepts it: Loops::RubyLLM uses it; a backend
+    # that runs its own in-process loop (Loops::AgentSDK) rejects a non-nil chat
+    # rather than silently dropping the session's memory.
+    def run(agent:, prompt:, max_turns: 25, chat: nil, &on_event)
+      raise NotImplementedError
+    end
+  end
+end