nexo_ai 0.1.0 → 0.7.0

data/lib/generators/nexo/install/install_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Nexo
+  # Namespace for Nexo's Rails generators (+rails g nexo:install+,
+  # +nexo:workflows+, +nexo:artifacts+, +nexo:state+, +nexo:skill+). Each is
+  # Rails-coupled and never autoloaded by the plain-Ruby core.
+  module Generators
+    # Sets up the conventional Nexo layout in a host Rails app:
+    #
+    #   rails g nexo:install
+    #
+    # creates the app/agents, app/workflows and app/skills directories (each
+    # with a committable .keep) and a provider-neutral config/initializers/nexo.rb.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      # Generation step: create the app/agents, app/workflows, and app/skills
+      # directories, each with a committable +.keep+.
+      def create_directories
+        %w[app/agents app/workflows app/skills].each do |dir|
+          empty_directory dir
+          create_file "#{dir}/.keep" unless File.exist?("#{dir}/.keep")
+        end
+      end
+
+      # Generation step: copy the provider-neutral
+      # +config/initializers/nexo.rb+ into the host app.
+      def copy_initializer
+        copy_file "nexo.rb", "config/initializers/nexo.rb"
+      end
+    end
+  end
+end

data/lib/generators/nexo/install/templates/nexo.rb

@@ -0,0 +1,19 @@
+Nexo.configure do |config|
+  # Provider-neutral: any ruby_llm-supported model. There is intentionally no default.
+  config.default_model = ENV["NEXO_MODEL"]
+  config.default_sandbox = :virtual      # :virtual | :local  (:remote in Spec 4)
+  config.default_permissions = :read_only # :read_only | :auto | :ask
+  config.skills_path = Rails.root.join("app/skills")
+
+  # Background execution (Spec 11): MyWorkflow.run_later(payload) enqueues on your
+  # existing ActiveJob adapter. Route workflow jobs to a dedicated queue (nil uses
+  # ActiveJob's default queue):
+  # config.job_queue = :nexo
+
+  # Live progress over Turbo Streams (opt-in; requires turbo-rails). Runs broadcast
+  # their events as `nexo.workflow.event` notifications regardless; set this to true
+  # to also mirror them over Turbo (override app/views/nexo/_event.html.erb to style
+  # them). Without Turbo this is a no-op — subscribe to the notifications yourself
+  # for logging/metrics.
+  # config.broadcast_events = true
+end

data/lib/generators/nexo/skill/skill_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/named_base"
+
+module Nexo
+  module Generators
+    # Scaffolds an Agent Skills package in a host Rails app:
+    #
+    #   rails g nexo:skill triage
+    #
+    # creates +app/skills/triage/SKILL.md+ (valid frontmatter + placeholder
+    # process steps, per agentskills.io/specification) and a kept
+    # +app/skills/triage/references/+ directory for supporting docs the skill can
+    # cite. Reference it from an agent with the +skills :triage+ macro.
+    #
+    # Rails-coupled, like Nexo's other generators: it requires +rails/generators+
+    # at load time and is never autoloaded by the plain-Ruby core, so
+    # +require "nexo"+ with no Rails present neither defines nor fails on it.
+    class SkillGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      # Generation step: scaffold +app/skills/<name>/+ with a kept +references/+
+      # directory and a valid +SKILL.md+ rendered from the template.
+      def create_skill_package
+        empty_directory File.join(skill_root, "references")
+        # An empty references/ would not survive git; .keep keeps it tracked.
+        create_file File.join(skill_root, "references", ".keep")
+        template "SKILL.md.tt", File.join(skill_root, "SKILL.md")
+      end
+
+      private
+
+      def skill_root
+        File.join("app", "skills", file_name)
+      end
+
+      # A human-readable heading from the skill name ("issue_triage" / "issue-triage"
+      # -> "Issue Triage").
+      def skill_title
+        file_name.split(/[_-]/).reject(&:empty?).map(&:capitalize).join(" ")
+      end
+    end
+  end
+end

data/lib/generators/nexo/skill/templates/SKILL.md.tt

@@ -0,0 +1,10 @@
+---
+name: <%= file_name %>
+description: One-line summary of when the model should use this skill.
+---
+
+# <%= skill_title %>
+
+## Process
+1. <first step>
+2. <second step>

data/lib/generators/nexo/state/state_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Nexo
+  module Generators
+    # Adds the +state+ column to an already-installed +nexo_workflow_runs+ table
+    # (Spec 13):
+    #
+    #   rails g nexo:state
+    #
+    # copies a timestamped, additive migration adding a +json+ +state+ column
+    # (default +{}+), after which +rails db:migrate+ lets Nexo::Workflow runs
+    # store checkpoint results and suspend metadata (durable suspend/resume).
+    # Fresh installs get the column from +nexo:workflows+ directly; this generator
+    # is for apps installed before Spec 13. Modeled on ArtifactsGenerator.
+    class StateGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Required by Rails::Generators::Migration to produce the migration's
+      # timestamp prefix.
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ::ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      # Generation step: copy the timestamped +state+-column migration into
+      # +db/migrate+.
+      def create_migration_file
+        migration_template "add_state_to_nexo_workflow_runs.rb", "db/migrate/add_state_to_nexo_workflow_runs.rb"
+      end
+    end
+  end
+end

data/lib/generators/nexo/state/templates/add_state_to_nexo_workflow_runs.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Additive migration for apps installed before Spec 13 (fresh installs get the
+# column from create_nexo_workflow_runs directly). Portable json object column,
+# default {} — it holds one entry per completed checkpoint plus the reserved
+# "__suspend__" suspend metadata. The migration version is resolved from the host
+# app's ActiveRecord rather than hardcoded, so it tracks whatever Rails is installed.
+class AddStateToNexoWorkflowRuns < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  # Adds the +state+ json object column (default +{}+) to +nexo_workflow_runs+.
+  def change
+    add_column :nexo_workflow_runs, :state, :json, null: false, default: {}
+  end
+end

data/lib/generators/nexo/workflows/templates/create_nexo_workflow_runs.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# json columns are used everywhere (not jsonb) so the schema is portable across
+# SQLite and PostgreSQL without an adapter-aware path. The primary key is the
+# UUID string id assigned by Nexo::WorkflowRun before_create.
+class CreateNexoWorkflowRuns < ActiveRecord::Migration[8.0]
+  # Creates the +nexo_workflow_runs+ table (UUID string primary key, portable
+  # +json+ columns for payload/result/events/artifacts/state) plus indexes on
+  # +workflow_class+ and +status+.
+  def change
+    create_table :nexo_workflow_runs, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :workflow_class, null: false
+      t.string :status, null: false, default: "pending" # pending|running|done|failed|suspended
+      t.json :payload, null: false, default: {}
+      t.json :result
+      t.text :error
+      t.json :events, null: false, default: []
+      t.json :artifacts, null: false, default: []
+      t.json :state, null: false, default: {} # checkpoints + suspend metadata (Spec 13)
+      t.timestamps
+    end
+    add_index :nexo_workflow_runs, :workflow_class
+    add_index :nexo_workflow_runs, :status
+  end
+end

data/lib/generators/nexo/workflows/workflows_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Nexo
+  module Generators
+    # Installs the WorkflowRun persistence schema into a host Rails app:
+    #
+    #   rails g nexo:workflows
+    #
+    # copies a timestamped migration that creates the +nexo_workflow_runs+
+    # table, after which +rails db:migrate+ makes Nexo::Workflow runs persist
+    # to ActiveRecord instead of the in-memory store.
+    class WorkflowsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Required by Rails::Generators::Migration to produce the migration's
+      # timestamp prefix.
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ::ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      # Generation step: copy the timestamped +create_nexo_workflow_runs+
+      # migration into +db/migrate+.
+      def create_migration_file
+        migration_template "create_nexo_workflow_runs.rb", "db/migrate/create_nexo_workflow_runs.rb"
+      end
+    end
+  end
+end

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