WIP

Author: st0012

doc/Index.md

@@ -95,7 +95,7 @@ To learn more about debugging with IRB, see [Debugging with IRB](#label-Debuggin
 
 ### Agent Mode (Experimental)
 
-`binding.irb(agent: true)` 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.
+`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.
 
 The behavior depends on the `IRB_SOCK_PATH` environment variable:
 

lib/irb.rb

@@ -746,31 +746,7 @@ class Binding
   #
   # See IRB for more information.
   #
-  # When +agent+ is true, the session is designed for non-interactive use by
-  # AI agents or scripts (experimental). Instead of opening an interactive REPL,
-  # it starts a Unix socket server that accepts one command per connection. See
-  # IRB::RemoteServer for the full protocol and workflow.
-  def irb(show_code: true, agent: false)
-    if agent
-      require_relative "irb/remote_server"
-      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.
-      unless sock_path
-        IRB::RemoteServer.print_instructions(self)
-        exit(0)
-      end
-
-      # Phase 2 (debug session): socket path set, start a request/response
-      # server that the agent can send commands to.
-      IRB.setup(source_location[0], argv: []) unless IRB.initialized?
-      server = IRB::RemoteServer.new(self, sock_path: sock_path)
-      server.run
-      return
-    end
-
+  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?
 
@@ -801,4 +777,38 @@ def irb(show_code: true, agent: false)
       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
+    require_relative "irb/remote_server"
+    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.
+    unless sock_path
+      IRB::RemoteServer.print_instructions(self)
+      exit(0)
+    end
+
+    # Phase 2 (debug session): socket path set, start a request/response
+    # server that the agent can send commands to.
+    IRB.setup(source_location[0], argv: []) unless IRB.initialized?
+    server = IRB::RemoteServer.new(self, sock_path: sock_path)
+    server.run
+  end
 end

lib/irb/remote_server.rb

@@ -7,7 +7,7 @@ module IRB
   # A request/response server for agent-driven IRB sessions over a Unix socket
   # (experimental).
   #
-  # When <tt>binding.irb(agent: true)</tt> is called, the behavior depends on
+  # 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
@@ -123,6 +123,8 @@ def print_instructions(binding_context)
 
           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:

test/irb/test_remote.rb

@@ -10,7 +10,7 @@ def test_phase1_prints_instructions_and_exits
       write_ruby <<~'RUBY'
         require "irb"
         puts "BEFORE"
-        binding.irb(agent: true)
+        binding.agent
         puts "AFTER"
       RUBY
 
@@ -20,6 +20,7 @@ def test_phase1_prints_instructions_and_exits
 
       assert_include output, "IRB agent breakpoint hit at"
       assert_include output, "IRB_SOCK_PATH"
+      assert_include output, 'require "irb"; binding.agent'
       assert_include output, "BEFORE"
       # exit(0) means AFTER should not print
       assert_not_include output, "AFTER"
@@ -28,7 +29,7 @@ def test_phase1_prints_instructions_and_exits
     def test_phase2_basic_eval
       write_ruby <<~'RUBY'
         require "irb"
-        binding.irb(agent: true)
+        binding.agent
       RUBY
 
       output = run_agent_session do |sock_path|
@@ -46,7 +47,7 @@ class Potato
           attr_accessor :name
           def initialize(name); @name = name; end
         end
-        Potato.new("Russet").instance_eval { binding.irb(agent: true) }
+        Potato.new("Russet").instance_eval { binding.agent }
       RUBY
 
       output = run_agent_session do |sock_path|
@@ -64,7 +65,7 @@ def test_phase2_show_source_command
         class Potato
           def cook!; "done"; end
         end
-        Potato.new.instance_eval { binding.irb(agent: true) }
+        Potato.new.instance_eval { binding.agent }
       RUBY
 
       output = run_agent_session do |sock_path|
@@ -78,7 +79,7 @@ def cook!; "done"; end
     def test_phase2_error_handling
       write_ruby <<~'RUBY'
         require "irb"
-        binding.irb(agent: true)
+        binding.agent
       RUBY
 
       output = run_agent_session do |sock_path|
@@ -92,7 +93,7 @@ def test_phase2_error_handling
     def test_phase2_multiline_expression
       write_ruby <<~'RUBY'
         require "irb"
-        binding.irb(agent: true)
+        binding.agent
       RUBY
 
       output = run_agent_session do |sock_path|
@@ -108,7 +109,7 @@ def test_phase2_multiline_expression
     def test_phase2_session_state_persists
       write_ruby <<~'RUBY'
         require "irb"
-        binding.irb(agent: true)
+        binding.agent
       RUBY
 
       output = run_agent_session do |sock_path|
@@ -125,7 +126,7 @@ def test_phase2_resumes_execution_after_exit
       write_ruby <<~'RUBY'
         require "irb"
         puts "BEFORE"
-        binding.irb(agent: true)
+        binding.agent
         puts "AFTER"
       RUBY
 
@@ -140,7 +141,7 @@ def test_phase2_resumes_execution_after_exit
     def test_phase2_help_command
       write_ruby <<~'RUBY'
         require "irb"
-        binding.irb(agent: true)
+        binding.agent
       RUBY
 
       output = run_agent_session do |sock_path|