nexo_ai 0.1.0 → 0.7.0

data/lib/nexo/permissions.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Nexo
+  # The authorization gate for a sandbox's capabilities. Each tool asks
+  # +authorize!+ before it touches the sandbox, so gating is provider-independent
+  # and does not rely on any framework callback.
+  #
+  # Modes:
+  # * +:auto+      — allow everything.
+  # * +:read_only+ — allow +:read+/+:glob+, deny +:write+/+:shell+/+:fetch+/+:search+ (the default).
+  # * +:ask+       — defer to +on_ask+; a truthy return allows, anything else denies.
+  # * +:approve+   — durable, cross-process sibling of +:ask+ (Spec 16): with no
+  #   +decision+ it raises Nexo::ApprovalRequired (→ Workflow#run_agent
+  #   suspends the run); with +{approved: true}+ it allows, with
+  #   +{approved: false}+ it Denied denies.
+  #
+  # Capabilities are +:read+, +:glob+, +:write+, +:shell+, +:fetch+, +:search+.
+  # Anything listed in +allow:+ is permitted regardless of mode.
+  class Permissions
+    # The recognized permission modes: +:auto+, +:read_only+, +:ask+, +:approve+.
+    MODES = %i[auto read_only ask approve].freeze
+
+    # Raised when a capability is not authorized. Tools rescue this and return
+    # +{ error: ... }+ so the agent loop continues.
+    class Denied < StandardError; end
+
+    # The configured Nexo permission mode (one of MODES). Read by the agent to
+    # map onto an opt-in backend's own permission vocabulary (see
+    # +Agent#permission_mode+).
+    attr_reader :mode
+
+    # The approval decision under +:approve+ (Spec 16): +nil+ (undecided ⇒
+    # suspend) or a +{approved: true|false}+ Hash. Writable after construction so
+    # Workflow#run_agent can thread a resume decision into an
+    # already-resolved +:approve+ gate without rebuilding it. Ignored by every
+    # other mode.
+    attr_accessor :decision
+
+    # +ask_when:+ is an optional +->(capability, detail)+ predicate that scopes
+    # *which* actions actually prompt under +:ask+ (and, unchanged, under
+    # +:approve+): when it returns falsey the action is auto-allowed without
+    # calling +on_ask+ / requiring a decision; truthy (or when unset) falls
+    # through to +on_ask+ / the approval gate exactly as before. It only ever
+    # *narrows* what is auto-allowed from the "ask/approve for everything"
+    # baseline — it never widens authority. Applies to #authorize! only, not
+    # #authorize_mcp!. +approve_when:+ is an alias that maps onto the same
+    # predicate (there is one predicate, not two — Spec 16 Q4).
+    #
+    # +decision:+ (default +nil+) seeds the +:approve+ decision (see #decision).
+    def initialize(mode: :read_only, allow: %i[read glob], mcp_allow: [], on_ask: nil, ask_when: nil,
+      approve_when: nil, decision: nil)
+      raise ArgumentError, "unknown mode #{mode}" unless MODES.include?(mode)
+
+      @mode = mode
+      @allow = allow
+      @mcp_allow = mcp_allow.map(&:to_s)
+      @on_ask = on_ask
+      @ask_when = ask_when || approve_when
+      @decision = decision
+    end
+
+    # Returns a copy of this gate carrying +decision+ (a +{approved: …}+ Hash or
+    # +nil+), leaving the receiver untouched (Spec 16). Used to thread a per-run
+    # resume decision into a user-supplied, class-level +:approve+ +Permissions+
+    # without mutating the shared instance.
+    def with_decision(decision)
+      dup.tap { |copy| copy.decision = decision }
+    end
+
+    # Authorizes +capability+ (with optional +detail+ passed to an +:ask+ hook).
+    # Returns +true+ when allowed; raises Denied otherwise.
+    def authorize!(capability, detail = nil)
+      return true if @allow.include?(capability)
+
+      case @mode
+      when :auto
+        true
+      when :read_only
+        if %i[write shell fetch search].include?(capability)
+          raise Denied, "#{capability} denied in read_only mode"
+        end
+        true
+      when :ask
+        # Scoped-ask: when ask_when says this action doesn't need a prompt,
+        # auto-allow without calling on_ask. Unset ask_when = ask for everything.
+        return true if @ask_when && !@ask_when.call(capability, detail)
+
+        unless @on_ask&.call(capability, detail)
+          raise Denied, "#{capability} (#{detail}) denied by user"
+        end
+        true
+      when :approve
+        # Durable approval (Spec 16). Scoped-approve: when ask_when says this
+        # action doesn't need approval, auto-allow without a decision. Unset
+        # ask_when = approve for everything.
+        return true if @ask_when && !@ask_when.call(capability, detail)
+
+        if @decision.nil?
+          # Undecided ⇒ pause the run for a human (Branch A): the signal
+          # propagates out of the tool loop; run_agent turns it into a suspend.
+          raise Nexo::ApprovalRequired.new(capability, detail)
+        elsif @decision[:approved]
+          true
+        else
+          # Explicitly denied on resume ⇒ never auto-allow; the tool rescues
+          # Denied into {error:} and the model adapts.
+          raise Denied, "#{capability} (#{detail}) not approved"
+        end
+      end
+    end
+
+    # Authorizes an MCP tool *call* by name. A deliberate sibling of #authorize!
+    # on a separate capability axis: an MCP tool runs inside the MCP server,
+    # outside the sandbox, so this gates the authority to *invoke* it — a different
+    # guarantee than sandbox capability. Fails closed under +:read_only+ (nothing
+    # allowed unless the exact +tool_name+ is listed in +mcp_allow+).
+    #
+    # * +:auto+      — allow every MCP tool.
+    # * +:read_only+ — allow only names in +mcp_allow+ (default +[]+ ⇒ deny all).
+    # * +:ask+       — defer to +on_ask+ with +(:mcp, {tool:, args:})+; a truthy
+    #   return allows, anything else denies.
+    # * +:approve+   — durable sibling of +:ask+ on the MCP axis: names in
+    #   +mcp_allow+ are pre-approved, anything else needs a decision — undecided
+    #   raises Nexo::ApprovalRequired (→ Workflow#run_agent suspends), +approved+
+    #   allows, +approved: false+ Denies.
+    #
+    # Returns +true+ when allowed; raises Denied otherwise. The +else+ is a
+    # fail-closed backstop: a future mode that forgets to extend this gate denies
+    # by default rather than silently allowing (the bug this replaced).
+    def authorize_mcp!(tool_name, args = {})
+      name = tool_name.to_s
+
+      case @mode
+      when :auto
+        true
+      when :read_only
+        return true if @mcp_allow.include?(name)
+
+        raise Denied, "mcp tool #{name} denied in read_only mode (not in mcp_allow)"
+      when :ask
+        unless @on_ask&.call(:mcp, {tool: name, args: args})
+          raise Denied, "mcp tool #{name} denied by user"
+        end
+        true
+      when :approve
+        # Pre-approved read tools pass; everything else routes through the same
+        # decision gate as #authorize!'s :approve branch.
+        return true if @mcp_allow.include?(name)
+
+        if @decision.nil?
+          raise Nexo::ApprovalRequired.new(:mcp, name, args)
+        elsif @decision[:approved]
+          true
+        else
+          raise Denied, "mcp tool #{name} not approved"
+        end
+      else
+        raise Denied, "mcp tool #{name} denied (unhandled mode #{@mode})"
+      end
+    end
+  end
+end

data/lib/nexo/read_tracker.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Nexo
+  # A tiny per-chat memory of which files an agent has read and at what
+  # last-modified time, so Tools::WriteFile can refuse to overwrite a file the
+  # model never read — or one that changed underneath it — within a session.
+  #
+  # Built once per chat in Agent#chat and threaded into both Tools::ReadFile
+  # (which records) and Tools::WriteFile (which enforces). Scope is clobber
+  # safety *within a session* only: no versioning, no locking, no VCS semantics.
+  class ReadTracker
+    # Starts an empty tracker (an internal +path => mtime+ map).
+    def initialize
+      @mtimes = {}
+    end
+
+    # Records that +path+ was read when it had modification time +mtime+.
+    def record(path, mtime)
+      @mtimes[path] = mtime
+    end
+
+    # Whether +path+ has been read in this session.
+    def read?(path)
+      @mtimes.key?(path)
+    end
+
+    # The mtime recorded when +path+ was read, or +nil+ if it was never read.
+    def recorded_mtime(path)
+      @mtimes[path]
+    end
+  end
+end

data/lib/nexo/run_store.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Nexo
+  # Storage seam for Workflow runs. Two interchangeable backends expose an
+  # identical create/find interface and return run objects responding to the
+  # same shape, which is what lets one Workflow implementation drive either
+  # the in-memory store (plain Ruby) or the ActiveRecord store (Rails).
+  #
+  # A run object responds to: +id+, +workflow_class+, +status+, +payload+,
+  # +result+, +error+, +events+, +artifacts+, +state+, plus +update!(attrs)+,
+  # +push_event(event)+, +save_events!+, +push_artifact(artifact)+,
+  # +save_artifacts!+, and +save_state!+ (Spec 13).
+  module RunStore
+    # Selects a backend: the ActiveRecord store when both ::ActiveRecord::Base
+    # and Nexo::WorkflowRun are defined (the Rails path), otherwise the in-memory
+    # store. With no Rails loaded the AR check short-circuits, so the plain-Ruby
+    # path never references ActiveRecord.
+    def self.default
+      if defined?(::ActiveRecord::Base) && defined?(Nexo::WorkflowRun)
+        ActiveRecord.new
+      else
+        Memory.new
+      end
+    end
+
+    # In-memory backend used by the plain-Ruby path and the offline test suite.
+    # Runs are held in a process-wide Hash keyed by their UUID id so that a run
+    # created by Workflow.run is still findable through a *later*
+    # RunStore.default call (e.g. Workflow.logs) — each call builds a fresh
+    # Memory instance, but they all share the same underlying store, mirroring
+    # how the ActiveRecord backend shares one database. Nothing is persisted to
+    # disk; the store lives only for the process.
+    class Memory
+      # A run record with the shared store shape. +update!+ assigns attributes,
+      # +push_event+ appends to the event log, and +save_events!+ is a no-op
+      # (the AR backend persists; Memory keeps everything in the Struct).
+      # Built with keyword arguments; a Struct defined without +keyword_init:+
+      # accepts them on Ruby 3.2+, so (well within the 3.3 floor) +keyword_init:
+      # true+ is unnecessary.
+      # Mutations serialize on the store-wide mutex (see Memory.mutex): the
+      # process-wide store can be driven from multiple threads (Local#offload
+      # workers, run_later under a threaded adapter, a multithreaded Puma host
+      # without ActiveRecord), and on Rubies without a GVL a bare +<<+/+[]=+ can
+      # lose events or corrupt the table.
+      Run = Struct.new(:id, :workflow_class, :status, :payload, :result, :error, :events, :artifacts, :state) do
+        def update!(attrs) = Memory.mutex.synchronize { attrs.each { |k, v| self[k] = v } }
+
+        def push_event(ev) = Memory.mutex.synchronize { events << ev }
+
+        def save_events! = nil
+
+        def push_artifact(a) = Memory.mutex.synchronize { artifacts << a }
+
+        def save_artifacts! = nil
+
+        # No-op counterpart to the AR model's save_state! — the Struct member
+        # already holds the checkpoint/suspend state in memory (Spec 13).
+        def save_state! = nil
+
+        # Read helpers mirroring Nexo::WorkflowRun so host code written against a
+        # finished run behaves identically in plain Ruby and under Rails (the
+        # "same run shape" contract covered only the write side before).
+        def done? = status == "done"
+
+        def failed? = status == "failed"
+
+        def running? = status == "running"
+
+        def queued? = status == "queued"
+
+        def suspended? = status == "suspended"
+
+        # The reason recorded when the run was suspended, or nil if it never was.
+        def suspend_reason = state&.dig("__suspend__", "reason")
+
+        # The stored result of a completed checkpoint(name), or nil.
+        def checkpoint_result(name) = state&.[](name.to_s)
+
+        # A recorded artifact by name (string/symbol tolerant), or nil.
+        def artifact(name) = (artifacts || []).find { |a| (a["name"] || a[:name]) == name.to_s }
+
+        # Just the stored body of a named artifact, or nil.
+        def artifact_content(name) = artifact(name)&.then { |a| a["content"] || a[:content] }
+      end
+
+      @runs = {}
+      @mutex = Mutex.new
+
+      class << self
+        # The shared run table. Ids are UUIDs, so runs from independent callers
+        # never collide.
+        attr_reader :runs
+
+        # The store-wide lock guarding +runs+ and every run mutation. Not
+        # reentrant, so no method that holds it calls another that grabs it.
+        attr_reader :mutex
+
+        # Clears the shared table. Intended for test isolation.
+        def reset!
+          @mutex.synchronize { @runs = {} }
+        end
+      end
+
+      # Builds a fresh +"pending"+ Run (UUID id, empty events/artifacts/state) and
+      # stores it in the process-wide table, returning it.
+      def create(workflow_class:, payload:)
+        run = Run.new(
+          id: Nexo.generate_run_id,
+          workflow_class: workflow_class,
+          status: "pending",
+          payload: payload,
+          result: nil,
+          error: nil,
+          events: [],
+          artifacts: [],
+          state: {}
+        )
+        self.class.mutex.synchronize { self.class.runs[run.id] = run }
+      end
+
+      # Fetches a run by its UUID string id. A miss raises KeyError, which is
+      # acceptable for v1.
+      def find(id) = self.class.mutex.synchronize { self.class.runs.fetch(id) }
+
+      # Atomically claims a +"suspended"+ run for resume: flips it to +"running"+
+      # and returns true only if it was still suspended, so two concurrent resumes
+      # can't both re-enter #call (Spec 13 double-execution guard). The status
+      # flip is direct (not via #update!) to avoid re-entering the non-reentrant
+      # mutex.
+      def claim_for_resume!(run)
+        self.class.mutex.synchronize do
+          return false unless run.status == "suspended"
+
+          run.status = "running"
+          true
+        end
+      end
+    end
+
+    # ActiveRecord backend used by the Rails path. Delegates to the
+    # Nexo::WorkflowRun model, which carries the same run shape.
+    class ActiveRecord
+      # Creates and persists a +"pending"+ Nexo::WorkflowRun row, returning it.
+      def create(workflow_class:, payload:)
+        Nexo::WorkflowRun.create!(workflow_class: workflow_class, payload: payload, status: "pending")
+      end
+
+      # Fetches a persisted run by id (raises +ActiveRecord::RecordNotFound+ on a miss).
+      def find(id) = Nexo::WorkflowRun.find(id)
+
+      # Atomically claims a +"suspended"+ run for resume with a single conditional
+      # UPDATE, returning true only for the worker that won the row. This closes
+      # the cross-process double-resume race the plain +find+-then-check couldn't:
+      # a queued resume_later and a concurrent sync resume can't both re-enter.
+      def claim_for_resume!(run)
+        Nexo::WorkflowRun
+          .where(id: run.id, status: "suspended")
+          .update_all(status: "running") == 1
+      end
+    end
+  end
+end

data/lib/nexo/sandbox.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Nexo
+  # The execution-environment seam. A sandbox is where an agent's tools actually
+  # touch files and run commands; swapping the sandbox swaps the whole execution
+  # context (in-memory, host, or — later — remote) by constructor injection.
+  #
+  # Concrete sandboxes implement the four-method contract below. The base class
+  # raises +NotImplementedError+ for each so an incomplete subclass fails loudly.
+  #
+  # See Sandboxes::Virtual (default, zero host access) and Sandboxes::Local
+  # (host filesystem + shell, guarded).
+  class Sandbox
+    # Returns the contents of +path+ as a String.
+    def read(path)
+      raise NotImplementedError
+    end
+
+    # Writes +content+ to +path+.
+    def write(path, content)
+      raise NotImplementedError
+    end
+
+    # Runs +command+ and returns +{ stdout:, stderr:, status: }+ (status is the
+    # integer exit code). +timeout+ is in seconds.
+    def shell(command, timeout: 30)
+      raise NotImplementedError
+    end
+
+    # Returns the paths matching the glob +pattern+.
+    def glob(pattern)
+      raise NotImplementedError
+    end
+
+    # Releases any resources the sandbox holds. No-op by default.
+    def close
+      nil
+    end
+
+    # A short, plain-text description of the execution environment (cwd, host
+    # access, network) for the agent to inject into the system prompt. Base
+    # returns +nil+ — inject nothing. Real-filesystem sandboxes (Local,
+    # Container) override this so a weak tool-caller knows where it runs.
+    def instructions
+      nil
+    end
+
+    # Whether the sandbox supports +capability+ (one of +:read+, +:write+,
+    # +:glob+, +:shell+). The base supports everything but +:shell+ (an
+    # in-memory sandbox has no process to run a command in), so an agent only
+    # attaches the +Shell+ tool when the sandbox reports it. Real-process
+    # sandboxes (Local, Container) override to add +:shell+.
+    def supports?(capability)
+      capability != :shell
+    end
+
+    # The last-modified time of +path+, used by the read-before-write + stale
+    # guard for real-filesystem sandboxes. Base returns +nil+ (no external
+    # mutation to guard against, e.g. Virtual), which disables the guard.
+    def mtime(path)
+      nil
+    end
+  end
+end