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 TTY REPL they cannot reliably drive.

That makes the most useful debugging workflow hard to automate: discover the breakpoint, inspect live locals and receiver state, try IRB commands, make a small state change if needed, and then let the original Ruby program continue.

The breakpoint also needs to teach the agent how to reconnect without assuming a dedicated client library or prior IRB-specific setup.

Solution

• Add experimental binding.agent, a two-phase breakpoint for non-interactive agents and scripts.
• In discovery mode, print self-contained socket workflow instructions and exit when IRB_SOCK_PATH is absent.
• In socket mode, run a Unix-socket-backed IRB session where each foreground client connection sends one Ruby expression or IRB command, receives output, and closes.
• Preserve the IRB workspace across socket connections so agents can inspect locals, run commands like ls and show_source, and mutate live state before resuming the host program with exit.
• Restore temporary IRB process state after the socket session, safely clean up socket files, and document the Unix-socket platform requirement plus the required require "irb"; binding.agent setup.
• Cover discovery, evaluation, IRB commands, errors, multiline input, persistent state, resume behavior, empty connections, and config restoration with focused integration tests.

Agent Flow

sequenceDiagram
  participant Agent
  participant Shell
  participant App as "Ruby app"
  participant Remote as "IRB::RemoteServer"

  Agent->>Shell: ruby app.rb
  Shell->>App: run without IRB_SOCK_PATH
  App-->>Agent: print socket workflow and exit

  Agent->>Shell: IRB_SOCK_PATH=/tmp/irb.sock ruby app.rb &
  Shell->>App: restart app in background
  App->>Remote: binding.agent opens socket server

  loop one command per connection
    Agent->>Remote: connect, send command, close_write
    Remote->>Remote: evaluate in persistent binding
    Remote-->>Agent: return IRB output and close
  end

  Agent->>Remote: exit
  Remote->>App: close server and resume

Loading

End-to-End Notes

• The local IRB flow exercises discovery, socket interaction, persisted session state, IRB helper commands, host-state mutation, and resume after exit.
• The same flow works from the RDoc checkout while loading IRB from this branch, so an agent can inspect real RDoc objects through binding.agent and still resume the host script.
• The important operational learning is that discovery mode intentionally exits; agents should restart the target command in the background with IRB_SOCK_PATH, then use short foreground socket commands for the interactive loop.