Add experimental agent mode for binding.agent

Author: st0012

doc/Index.md

@@ -93,6 +93,37 @@ You can use IRB as a debugging console with `debug.gem` with these options:
 
 To learn more about debugging with IRB, see [Debugging with IRB](#label-Debugging+with+IRB).
 
+### Agent Mode (Experimental)
+
+`binding.agent` starts a non-interactive IRB session designed for AI agents and scripts. Instead of opening a REPL, it exposes an IRB session over a Unix socket using a simple request/response protocol. It is available on platforms where Ruby supports Unix sockets.
+
+The behavior depends on the `IRB_SOCK_PATH` environment variable:
+
+- **Not set**: prints instructions explaining the workflow, then exits. This lets the agent discover the breakpoint and learn the protocol.
+- **Set**: starts a Unix socket server at the given path. Each connection accepts one command, evaluates it, returns the result, and closes. The IRB session state persists across connections. Send `exit` to end the session and resume app execution.
+
+```console
+# app.rb
+require "irb"
+binding.agent
+```
+
+```console
+# 1. First run: discover the breakpoint.
+$ ruby app.rb
+IRB agent breakpoint hit at app.rb:14 in `cook!`
+...
+
+# 2. Re-run in background with a socket path.
+$ IRB_SOCK_PATH=/tmp/irb-debug.sock ruby app.rb &
+
+# 3. Send commands.
+$ ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-debug.sock"); s.puts "ls"; s.close_write; puts s.read; s.close'
+$ ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-debug.sock"); s.puts "exit"; s.close_write; puts s.read; s.close'
+```
+
+See IRB::RemoteServer for more details.
+
 ## Startup
 
 At startup, IRB:
@@ -681,7 +712,7 @@ This integration offers several benefits over `debug.gem`'s native console:
 However, there are some limitations to be aware of:
 
 1. `binding.irb` doesn't support `pre` and `do` arguments like [binding.break](https://github.com/ruby/debug#bindingbreak-method).
-2. As IRB [doesn't currently support remote-connection](https://github.com/ruby/irb/issues/672), it can't be used with `debug.gem`'s remote debugging feature.
+2. The regular `binding.irb` console does not support `debug.gem`'s remote debugging feature. For agent-oriented remote evaluation, use the separate `binding.agent` Unix-socket workflow.
 3. Access to the previous return value via the underscore `_` is not supported.
 
 ## Encodings

lib/irb.rb

@@ -745,9 +745,11 @@ class Binding
   #     Cooked potato: true
   #
   # See IRB for more information.
+  #
   def irb(show_code: true)
     # Setup IRB with the current file's path and no command line arguments
     IRB.setup(source_location[0], argv: []) unless IRB.initialized?
+
     # Create a new workspace using the current binding
     workspace = IRB::WorkSpace.new(self)
     # Print the code around the binding if show_code is true
@@ -775,4 +777,87 @@ def irb(show_code: true)
       binding_irb.debug_break
     end
   end
+
+  # Opens a non-interactive IRB session designed for AI agents and scripts
+  # (experimental). Instead of opening a REPL, it exposes an IRB session over a
+  # Unix socket using a simple request/response protocol.
+  #
+  # The behavior depends on the +IRB_SOCK_PATH+ environment variable:
+  #
+  # - *Not set* (Phase 1 - discovery): prints instructions explaining the
+  #   workflow, then exits. This lets the agent discover the breakpoint and
+  #   learn the protocol.
+  # - *Set* (Phase 2 - debug session): starts a Unix socket server at the
+  #   given path. Each connection accepts one command, evaluates it, returns
+  #   the result, and closes. The IRB session state persists across
+  #   connections. Send +exit+ to end the session and resume app execution.
+  #
+  # See IRB::RemoteServer for the full protocol and workflow.
+  def agent
+    sock_path = ENV["IRB_SOCK_PATH"]
+
+    # Phase 1 (discovery): no socket path set, so print instructions
+    # teaching the agent how to connect, then exit immediately.
+    # No IRB.setup needed since we're not starting a session.
+    if sock_path.nil? || sock_path.empty?
+      print_agent_instructions
+      Kernel.exit(0)
+    end
+
+    # Phase 2 (debug session): socket path set, start a request/response
+    # server that the agent can send commands to.
+    require_relative "irb/remote_server"
+    IRB.setup(source_location[0], argv: []) unless IRB.initialized?
+    server = IRB::RemoteServer.new(self, sock_path: sock_path)
+    server.run
+  end
+
+  private
+
+  def print_agent_instructions
+    file, line = source_location
+    method_name = begin
+      eval("__method__")
+    rescue NameError
+      nil
+    end
+    location = method_name ? "#{file}:#{line} in `#{method_name}`" : "#{file}:#{line}"
+
+    $stdout.puts <<~MSG
+      ==========================================================
+      IRB agent breakpoint hit at #{location}
+
+      No IRB_SOCK_PATH set - exiting without starting a debug session.
+
+      Add breakpoints with: require "irb"; binding.agent
+
+      To debug this breakpoint:
+
+        1. Run the app in the BACKGROUND with a socket path:
+
+             IRB_SOCK_PATH=/tmp/irb-UNIQUE_ID.sock <your command> &
+
+           The process will block waiting for a connection.
+
+        2. Wait for the socket file to appear:
+
+             ls /tmp/irb-UNIQUE_ID.sock
+
+        3. Send commands to the socket with FOREGROUND commands:
+
+             ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-UNIQUE_ID.sock"); s.puts "help"; s.close_write; puts s.read; s.close'
+
+           Each invocation sends one command and prints the result.
+           The IRB session persists between invocations.
+
+           Examples:
+             ... s.puts "ls"; s.close_write              # list methods and variables
+             ... s.puts "show_source foo"; s.close_write  # see source of a method
+             ... s.puts "@name"; s.close_write            # inspect a variable
+             ... s.puts "exit"; s.close_write             # end session, resume app
+
+      ==========================================================
+    MSG
+    $stdout.flush
+  end
 end

lib/irb/remote_server.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "socket"
+require "stringio"
+
+module IRB
+  # A request/response server for agent-driven IRB sessions over a Unix socket
+  # (experimental).
+  #
+  # When <tt>binding.agent</tt> is called, the behavior depends on
+  # the +IRB_SOCK_PATH+ environment variable:
+  #
+  # - *Not set* (Phase 1 - discovery): prints instructions explaining how to
+  #   start a debug session, then calls <tt>exit(0)</tt>. This lets the agent
+  #   see the instructions before the process terminates.
+  #
+  # - *Set* (Phase 2 - debug session): starts a Unix socket server at the
+  #   given path. The server accepts one connection at a time in a loop. Each
+  #   connection is a single request: the client sends Ruby code (or an IRB
+  #   command), closes its write end, and reads back the result. The IRB session
+  #   state persists across requests. Sending +exit+ ends the loop and resumes
+  #   execution of the host program.
+  #
+  # == Example agent workflow
+  #
+  #   # 1. Run the app - hits breakpoint, prints instructions, exits:
+  #   $ ruby app.rb
+  #
+  #   # 2. Re-run in background with a socket path:
+  #   $ IRB_SOCK_PATH=/tmp/irb-debug.sock ruby app.rb &
+  #
+  #   # 3. Send commands (one per connection):
+  #   $ ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-debug.sock"); s.puts "ls"; s.close_write; puts s.read; s.close'
+  #   $ ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-debug.sock"); s.puts "exit"; s.close_write; puts s.read; s.close'
+  #
+  class RemoteServer
+    def initialize(binding_context, sock_path:)
+      @binding_context = binding_context
+      @sock_path = sock_path
+    end
+
+    class StringInput < InputMethod
+      def initialize(str)
+        super()
+        @io = StringIO.new(str)
+      end
+
+      def gets
+        @io.gets
+      end
+
+      def eof?
+        @io.eof?
+      end
+
+      def encoding
+        Encoding::UTF_8
+      end
+    end
+
+    def run
+      server = nil
+      original_stdout = $stdout
+      original_main_context = IRB.conf[:MAIN_CONTEXT]
+      original_use_pager = IRB.conf[:USE_PAGER]
+
+      begin
+        remove_socket_file
+
+        server = UNIXServer.new(@sock_path)
+        File.chmod(0600, @sock_path)
+
+        IRB.conf[:USE_PAGER] = false
+
+        binding_irb = create_irb
+        IRB.conf[:MAIN_CONTEXT] = binding_irb.context
+
+        loop do
+          client = server.accept
+          begin
+            input = client.read
+            next if input.nil? || input.empty?
+
+            binding_irb.context.io = StringInput.new(input)
+
+            not_exited = catch(:IRB_EXIT) do
+              begin
+                $stdout = client
+                binding_irb.eval_input
+              ensure
+                $stdout = original_stdout
+              end
+              :not_exited
+            end
+
+            break unless not_exited == :not_exited
+          ensure
+            client&.close
+          end
+
+        end
+      ensure
+        $stdout = original_stdout
+        IRB.conf[:USE_PAGER] = original_use_pager
+        # Match Irb#run: restoring MAIN_CONTEXT to nil can crash threaded sessions.
+        IRB.conf[:MAIN_CONTEXT] = original_main_context if original_main_context
+        server&.close
+        remove_socket_file
+      end
+    end
+
+    private
+
+    def remove_socket_file
+      File.unlink(@sock_path) if File.lstat(@sock_path).socket?
+    rescue Errno::ENOENT
+    end
+
+    def create_irb
+      workspace = IRB::WorkSpace.new(@binding_context)
+      irb = IRB::Irb.new(workspace, StringInput.new(""), from_binding: true)
+      irb.context.irb_path = File.expand_path(@binding_context.source_location[0])
+      irb.context.verbose = false
+      irb.context.newline_before_multiline_output = false
+      irb
+    end
+
+  end
+end