Add experimental agent mode for binding.agent

[st0012]

Problem

Agents usually interact with programs through non-interactive shell commands, so a process that stops at binding.irb can leave them stranded at a terminal REPL they cannot reliably drive.

The useful debugging loop needs to work without a dedicated client: discover the breakpoint, restart the target in a controllable mode, inspect live locals and receiver state, run normal IRB commands, make a small state change, and then resume the original Ruby program.

That loop also has two output streams with different ownership. IRB results, errors, and command output belong in the agent response, while output from the running application and its other threads must remain on the application's stdout and stderr. Commands that start a second interactive UI cannot honestly fit a one-request/one-response protocol.

Solution

• Add experimental binding.agent with a self-teaching two-phase workflow.
• Without IRB_SOCK_PATH, print complete restart and connection instructions, then exit without initializing an IRB session.
• With IRB_SOCK_PATH, run a normal IRB::Irb#run lifecycle through an agent-specific SocketInputMethod. Each connection supplies one complete request and receives one response; the workspace persists across connections.
• Pair each context with its session output instead of replacing global $stdout. IRB-owned results, diagnostics, paged output, RI output, and built-in command output go to the socket. Application code that writes stdout or stderr continues to write to the host.
• Keep commands open by default, including aliases and registered custom commands. Preserve exit as resume and exit! as process exit. Refuse only commands that require another interactive loop or host UI: debug commands, deprecated multi-IRB commands, edit, and bare show_doc.
• Keep agent history for the session without writing it to the user's human IRB history file.
• Refuse active and non-socket paths, create the socket with mode 0600, reclaim stale sockets, and only remove a socket whose identity still matches the one this session created. Stale-path reclamation is best-effort, so callers should use a unique path in a private directory.
• Restore normal IRB configuration and signal lifecycle on exit, preserve the primary exit result when cleanup fails, and leave replacement socket paths untouched.

Command Behavior

Input	Agent mode
Ruby expressions and multiline definitions	Supported
Normal commands, aliases, and registered custom commands	Supported
ls, history, show_source, and named show_doc	Supported
source, require, copy, workspace commands, and measure	Supported with their normal side effects
exit	End the agent session and resume the program
exit!	Exit the process
Debug and multi-IRB command families	Unavailable because they transfer control to another input loop
edit and bare show_doc	Unavailable because they launch an interactive host program

Custom commands that explicitly write process stdout or stderr still target the host by design. Commands using IRB's command output helpers are returned through the socket.

Agent Flow

sequenceDiagram
  participant Agent
  participant App as "Ruby process"
  participant Session as "IRB::AgentSession"
  participant IRB as "IRB::Irb"
  participant Host as "Host stdout/stderr"

  Agent->>App: run without IRB_SOCK_PATH
  App-->>Agent: print workflow instructions and exit

  Agent->>App: restart with unique IRB_SOCK_PATH
  App->>Session: binding.agent
  Session->>Session: bind protected Unix socket
  Session->>IRB: run with SocketInputMethod

  loop one complete request per connection
    Agent->>Session: connect, send request, close_write
    Session->>IRB: provide request as IRB input
    IRB->>IRB: evaluate in persistent workspace
    IRB-->>Session: result, error, or command output
    Session-->>Agent: response and EOF
    App-->>Host: application output remains on host streams
  end

  alt exit
    Agent->>Session: exit
    Session->>App: close session and resume
  else exit!
    Agent->>Session: exit!
    Session->>App: exit process
  end

Loading

End-to-End Notes

• A fresh agent exercised discovery and the complete socket loop from this branch: expressions, persistent history, ls, show_source, named show_doc, a registered custom command, narrow command refusals, host-thread output isolation, live mutation, resume, and socket cleanup.
• A second fresh agent entered the RDoc checkout while loading IRB from this branch. It inspected and mutated real RDoc::Markup::Document and RDoc::Comment objects, resolved source into that checkout, preserved state across connections, resumed the target, and confirmed both loaded feature paths.
• The first passes exposed one startup line written before the agent context became quiet. Passing verbose: false during IRB::Irb construction fixed it; both complete flows were rerun and observed no startup noise on either host or socket output.
• The operational model is intentionally simple: discovery exits, the agent restarts the target in the background with a private socket path, then uses short foreground socket requests as its interactive loop.