nexo_ai 0.1.0 → 0.7.0

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

data/lib/nexo/loops/agent_sdk.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Nexo
+  module Loops
+    # An opt-in, Anthropic-oriented loop that delegates to +ruby_llm-agent_sdk+'s
+    # own engine: native +max_turns+, permission modes, and the SDK's built-in
+    # tools. It is NOT the default and is not provider-neutral — choose it
+    # explicitly with +loop: Nexo::Loops::AgentSDK.new+ when you are on Anthropic
+    # and want the Claude fast path.
+    #
+    # The trade vs. Loops::RubyLLM: this leans on the SDK's own built-in tools
+    # and runs in the host process, so it does NOT execute through Nexo's
+    # pluggable sandbox. That is the documented cost of the native +max_turns+
+    # hard cap (see the turn-cap caveat in the README).
+    #
+    # +ruby_llm-agent_sdk+ is a SOFT dependency: it is required lazily inside
+    # +#run+ and, when absent, surfaces as a Nexo::MissingDependencyError with
+    # install guidance — +require "nexo"+ without the gem never raises.
+    #
+    # VERIFY-on-install: the gem is not installed in this environment, so
+    # +RubyLLM::AgentSDK.query+'s exact signature and the +:result+ terminal
+    # message shape below remain provisional (per references.md). Confirm them
+    # against the +ruby_llm-agent_sdk+ README the moment the gem is added and
+    # record the result under "Verified APIs".
+    class AgentSDK < Nexo::Loop
+      def run(agent:, prompt:, max_turns: 25, chat: nil, &on_event)
+        unless chat.nil?
+          raise Nexo::ConfigurationError,
+            "Loops::AgentSDK runs its own in-process loop and cannot continue a persisted Nexo::Session chat — use the default Loops::RubyLLM for sessions."
+        end
+
+        load_sdk!
+
+        result = nil
+        ::RubyLLM::AgentSDK.query(
+          prompt,
+          model: agent.model,
+          max_turns: max_turns,
+          permission_mode: agent.permission_mode, # Nexo mode mapped by the agent
+          allowed_tools: agent.allowed_tools # %w[Read Write Edit Bash Glob Grep]
+        ) do |message|
+          on_event&.call(message.type, message)
+          result = message if message.type == :result
+        end
+        # Emit the contract's terminal :done event (the base Loop advertises
+        # :tool_call/:tool_result/:done) so a Workflow#run_agent driving THIS
+        # backend records an `agent_done` just like the default loop does. The
+        # SDK's INTERMEDIATE event types stay backend-native (:assistant/:result/…)
+        # — this loop is opt-in and its per-message vocabulary is the SDK's.
+        on_event&.call(:done, result)
+        result
+      end
+
+      private
+
+      # Lazily loads the opt-in +ruby_llm-agent_sdk+ gem. The rescue wraps ONLY the
+      # require (mirroring Skills.load!/MCP.load!), so a LoadError raised from
+      # inside the SDK's own +query+ or the caller's block is NOT mislabeled as a
+      # missing-gem error.
+      def load_sdk!
+        require "ruby_llm/agent_sdk" # VERIFY exact require path on install
+      rescue LoadError
+        raise Nexo::MissingDependencyError,
+          "Loops::AgentSDK requires the `ruby_llm-agent_sdk` gem. Add `gem \"ruby_llm-agent_sdk\"` to your Gemfile and run `bundle install`."
+      end
+    end
+  end
+end

data/lib/nexo/loops/ruby_llm.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Nexo
+  # Namespace for the pluggable loop backends that drive one prompt to
+  # completion: Loops::RubyLLM (the default, provider-neutral) and
+  # Loops::AgentSDK (opt-in, Anthropic-oriented). Selected per agent via the
+  # +loop:+ constructor injection; the base contract is Nexo::Loop.
+  module Loops
+    # The default, provider-neutral loop. It is the Spec 1 +Agent#prompt+ body
+    # extracted verbatim: build the agent's chat (with its four sandbox-backed
+    # tools) and let +ruby_llm+ run the whole tool loop inside +#ask+. It works
+    # identically on any +ruby_llm+-supported model — Anthropic, OpenAI, Gemini,
+    # Ollama/Gemma — because file/shell capability comes entirely from the
+    # agent's own sandbox-backed tools, not from anything vendor-specific here.
+    #
+    # Tool-call *observability* (not a hard cap — see the turn-cap caveat in the
+    # README) is wired through +ruby_llm+'s +before_tool_call+/+after_tool_result+
+    # callbacks when the installed version exposes them, and is silently omitted
+    # otherwise so an older/newer +ruby_llm+ degrades to no observability rather
+    # than crashing.
+    class RubyLLM < Nexo::Loop
+      # +chat:+ lets a Nexo::Session inject the hydrated, continuing chat so the
+      # loop runs over the persisted thread; left nil it builds the agent's own
+      # fresh chat exactly as before — the default (no-session) path is unchanged.
+      def run(agent:, prompt:, max_turns: 25, chat: nil, &on_event)
+        chat ||= agent.chat
+
+        wire_observability(chat, &on_event)
+
+        response = chat.ask(prompt)
+        on_event&.call(:done, response)
+        response
+      end
+
+      private
+
+      # Tool-call OBSERVABILITY only: ruby_llm runs the whole tool loop inside
+      # #ask, so these callbacks report tool activity but cannot halt the loop.
+      # BOTH callbacks must be present to wire — confirmed on ruby_llm 1.16.0
+      # (legacy aliases of #on_tool_call/#on_tool_result); a chat missing either
+      # degrades to no observability rather than crashing on the one it has.
+      #
+      # A continuing Nexo::Session runs the loop repeatedly over the SAME chat, so
+      # the wiring is done once per chat (flagged with an ivar) — otherwise ruby_llm
+      # (which *appends* callbacks) would stack a fresh pair every prompt and fire
+      # each event N times. The current +on_event+ is stashed on the chat so a later
+      # prompt observes with its own block rather than the first one. A fresh chat
+      # (the default per-prompt path) simply wires once — byte-for-byte the prior
+      # behavior.
+      def wire_observability(chat, &on_event)
+        return unless chat.respond_to?(:before_tool_call) && chat.respond_to?(:after_tool_result)
+
+        chat.instance_variable_set(:@nexo_on_event, on_event)
+        return if chat.instance_variable_get(:@nexo_observed)
+
+        chat.instance_variable_set(:@nexo_observed, true)
+        chat.before_tool_call do |tc|
+          chat.instance_variable_get(:@nexo_on_event)&.call(:tool_call, tc)
+        end
+        chat.after_tool_result do |r|
+          chat.instance_variable_get(:@nexo_on_event)&.call(:tool_result, r)
+        end
+      end
+    end
+  end
+end

data/lib/nexo/mcp/gated_tool.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Nexo
+  module MCP
+    # Wraps a +ruby_llm-mcp+ tool so the chat sees an identical tool but every
+    # invocation is authorized through Nexo::Permissions#authorize_mcp! first. A
+    # denied call returns +{ error: ... }+ (recoverable) and never raises into the
+    # loop — matching the sandbox-backed tools' authorize→act→rescue-+Denied+→
+    # +{error:}+ shape (see +lib/nexo/tools/write_file.rb+).
+    #
+    # Everything except the execution method is delegated to the wrapped tool, so
+    # the chat cannot tell the wrapper apart from the raw MCP tool: it reports the
+    # same +name+/+description+/+params_schema+ and serializes identically.
+    #
+    # VERIFY (Group 0, ruby_llm-mcp 1.0.0 + ruby_llm 1.16.0): +RubyLLM::Chat#with_tool+
+    # does not type-check — it accepts any object responding to +#name+ — and the tool
+    # loop invokes +tool.call(args)+ with a positional Hash. So a duck-typed wrapper
+    # is accepted; no +RubyLLM::Tool+ subclass is required. +#call+ here mirrors that
+    # entry point (a +RubyLLM::MCP::Tool+'s own +#call+ normalizes and dispatches to
+    # +#execute+), and +method_missing+ forwards +description+/+params_schema+/+to_h+/
+    # etc. to the wrapped tool.
+    class GatedTool
+      # Wraps +tool+ (a +ruby_llm-mcp+ tool) so every call is authorized through
+      # +permissions+ (the MCP axis) before delegating.
+      def initialize(tool:, permissions:)
+        @tool = tool
+        @permissions = permissions
+      end
+
+      # Authorizes the call by tool name, then delegates to the wrapped tool. A
+      # denial is returned as +{ error: ... }+ so the model can recover — never
+      # raised into the loop.
+      def call(args = {})
+        @permissions.authorize_mcp!(name, args)
+        @tool.call(args)
+      rescue Nexo::Permissions::Denied => e
+        {error: e.message}
+      end
+
+      # The wrapped tool's name — what the chat and the gate key on.
+      def name = @tool.name
+
+      # The gate lives on #call: #execute (the UNGATED tool body) must never be
+      # reachable through the wrapper, or a caller invoking #execute directly would
+      # skip authorization entirely. Route it back to the gated #call.
+      def execute(*args, **kwargs)
+        call(kwargs.empty? ? (args.first || {}) : kwargs)
+      end
+
+      # Forward description/params_schema/to_h/etc. to the wrapped tool so the chat
+      # serializes it exactly like the raw MCP tool — but never +execute+ (see above).
+      def respond_to_missing?(method_name, include_private = false)
+        return true if method_name == :execute
+
+        @tool.respond_to?(method_name, include_private) || super
+      end
+
+      # Delegates any unknown method to the wrapped tool (description,
+      # params_schema, to_h, ...), so the wrapper serializes identically. +execute+
+      # is handled explicitly above and never falls through here.
+      def method_missing(method_name, *args, **kwargs, &block)
+        if @tool.respond_to?(method_name)
+          @tool.public_send(method_name, *args, **kwargs, &block)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/nexo/mcp.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Nexo
+  # Composes the +ruby_llm-mcp+ gem so an agent can attach one or more MCP servers
+  # with a single +mcp+ class macro — no MCP client wiring by hand. A loaded server
+  # contributes tools that are gated by Nexo::Permissions#authorize_mcp! before
+  # the model can invoke them (see MCP::GatedTool).
+  #
+  # +ruby_llm-mcp+ is a SOFT (optional) dependency: it is required lazily by load!
+  # the first time an MCP server is built. With the gem absent, +require "nexo"+
+  # still loads cleanly; only building a client raises MissingDependencyError
+  # with install guidance.
+  #
+  # Provider-neutral by construction: MCP servers are reached through a server (not
+  # a vendor SDK), so behavior is identical on Anthropic, a local model, or anything
+  # else +ruby_llm+ supports.
+  module MCP
+    class << self
+      # Lazily loads the +ruby_llm-mcp+ gem. Idempotent (a second call is a cheap
+      # no-op once the gem is loaded). Raises MissingDependencyError — naming the
+      # gem and the exact remedy — when the gem is not installed. Mirrors
+      # Nexo::Skills.load!.
+      def load!
+        require "ruby_llm/mcp"
+      rescue LoadError
+        raise MissingDependencyError,
+          'MCP requires the `ruby_llm-mcp` gem. Add `gem "ruby_llm-mcp"` to your Gemfile.'
+      end
+
+      # Builds a +ruby_llm-mcp+ client from Nexo's friendly, transport-shaped macro
+      # opts. +name+ and +transport+ map onto the client's +name:+/+transport_type:+;
+      # **every other kwarg** is collected into the client's +config:+ hash verbatim
+      # (no key renaming) — e.g. +command:+/+args:+ for +:stdio+, +url:+ for +:sse+.
+      #
+      # +token:+ (Spec 18) is Nexo's own option — a static bearer String or a
+      # callable (+#call+) that yields one — for an OAuth-authenticated HTTP-family
+      # server (+:http+/+:sse+/+:streamable+). When present, Nexo resolves it and
+      # injects an +Authorization: Bearer+ header (see #inject_auth). +token:+ is a
+      # dedicated keyword, so it never enters +config:+ (nothing to strip — the
+      # handoff config carries no +token+ key by construction). When absent,
+      # +config:+ passes through byte-for-byte (no +headers+ key added) — +:stdio+ is
+      # untouched. Nexo runs no OAuth flow, refresh, or token store: it injects a
+      # header, the host owns the credential (see docs/mcp.md).
+      #
+      # VERIFY (Group 0, ruby_llm-mcp 1.0.0): the constructor is
+      # +RubyLLM::MCP.client(name:, transport_type:, config: {})+ and the client
+      # connects on construction (+start: true+ default), so it is reusable across
+      # prompts until torn down with +#stop+. The HTTP-family transports read auth
+      # headers from +config[:headers]+ (a Hash) and SNAPSHOT them at construction
+      # (+@headers = headers || {}+, dup'd per request) — there is no per-request
+      # header callback for a plain +headers+ Hash. So a callable +token:+ is
+      # resolved ONCE per client build; a rotated token needs the documented
+      # +Agent#close+ + fresh-prompt reconnect (Spec 6 memoizes the client).
+      def build(name:, transport:, token: nil, **config)
+        load!
+        config = inject_auth(config, token) unless token.nil?
+        client_factory.client(name: name.to_s, transport_type: transport, config: config)
+      end
+
+      # Resolves a static-or-callable token and returns +config+ with an
+      # +Authorization: Bearer+ header merged under +:headers+ (the Group-0-verified
+      # key). A caller's other headers are preserved; Nexo's +Authorization+ wins.
+      #
+      # SECURITY: the token is a live credential. It must stay out of logs, events,
+      # persisted +WorkflowRun+ records, and URLs/query strings — it lives only in
+      # this in-memory header Hash handed to +ruby_llm-mcp+. The event path
+      # (Workflow#serializable) carries only tool +name+/+args+ and return values,
+      # never connection config, so the token never reaches +emit+ (see the no-leak
+      # test). Nexo does not police +ruby_llm-mcp+'s own internal logging.
+      private def inject_auth(config, token)
+        value = token.respond_to?(:call) ? token.call : token
+        headers = (config[:headers] || {}).merge("Authorization" => "Bearer #{value}")
+        config.merge(headers: headers)
+      end
+
+      # The object whose +#client+ builds the MCP client — +::RubyLLM::MCP+ in
+      # production. Overridable via #stub_client_factory so an offline test can
+      # inspect the exact +config:+ Nexo hands off without a live server or stubbing
+      # a constant.
+      def client_factory
+        @client_factory || ::RubyLLM::MCP
+      end
+
+      # Swaps #client_factory to +factory+ for the duration of the block, then
+      # restores it. Test-only seam (Spec 18) — keeps the +token:+ transform
+      # unit-testable at the +ruby_llm-mcp+ boundary.
+      def stub_client_factory(factory)
+        previous = @client_factory
+        @client_factory = factory
+        yield
+      ensure
+        @client_factory = previous
+      end
+    end
+  end
+end

data/lib/nexo/output_truncator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Nexo
+  # Bounds unbounded command output before it reaches the model, so a single
+  # +npm install+ or +git log+ can't blow a small context window. Pure and
+  # dependency-free — line/char based, no tokenizer (a token budget would be
+  # expensive to reimplement and is out of scope for v1).
+  #
+  # The transform, in order: strip ANSI SGR escapes, keep the *last*
+  # +max_lines+ lines (the tail is where errors and exit summaries live), append
+  # a +…[truncated N lines]+ marker when lines were dropped, then hard-cap the
+  # result at +max_chars+ characters. Configurable via kwargs only — there is no
+  # +Nexo.config+ global and no per-agent macro in v1.
+  module OutputTruncator
+    # Matches ANSI SGR color/style escapes (e.g. +\e[31m+, +\e[1;32m+, +\e[0m+),
+    # the escapes real command output emits. VERIFIED against real output in
+    # Group 0.
+    ANSI = /\e\[[0-9;]*m/
+
+    module_function
+
+    # Strips ANSI escapes from +text+, keeps the last +max_lines+ lines (with a
+    # +…[truncated N lines]+ marker when it trims), then caps the result at
+    # +max_chars+. Pure line/char truncation — no tokenizer.
+    def call(text, max_lines: 200, max_chars: 16_000)
+      return text if text.nil? || text.empty?
+
+      stripped = text.gsub(ANSI, "")
+      lines = stripped.split("\n", -1)
+      dropped = lines.size - max_lines
+
+      result = if dropped.positive?
+        (lines.last(max_lines) + ["…[truncated #{dropped} lines]"]).join("\n")
+      else
+        stripped
+      end
+
+      (result.length > max_chars) ? result[-max_chars..] : result
+    end
+  end
+end