pi-agent-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ea32a398a43c159c3e7afaad55542aaf726215675960c52da2dea2fe8e29675
+  data.tar.gz: d8fe5e18907cea1da1ee0f8a0698be286ecd02792232b69bc419dd79e2c6de52
+SHA512:
+  metadata.gz: 8cad377c04b0c45fd6eaa2dd29cdfff690e250431caaf479ca0819d8ab0682c689be9bdabc63e7a57a6bc395d0f9e1bc24b2a2847b946151af33727f7a539f26
+  data.tar.gz: 1d6fa73ab6578a09cafea186979879ab501480b951a4ee3f5fe25113282068ce56ea5774911b66463ef9201d75c1a9cab107ffe95b0ec6af9de60e481fb82385

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-27
+
+### Added
+- Initial project scaffold.
+- `Session#run` single-shot helper (pi print-mode equivalent).
+- `Session` commands: `cycle_model`, `available_models`, `messages`,
+  `last_assistant_text`, `compact`, `new_session`, `switch_session`.
+
+### Fixed
+- `Session#set_model` now sends `provider`/`modelId` (pi rejected the
+  previous single `model` field).
+- `Session#set_thinking` now sends the `set_thinking_level` command (pi
+  has no `set_thinking` command).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MGC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+# pi-agent-rb
+
+Ruby client for the [pi coding agent](https://github.com/earendil-works/pi).
+Spawns `pi --mode rpc` and speaks its JSONL protocol from Ruby. Designed for
+building interactive agent UIs (web, TUI) on top of pi.
+
+> Not officially maintained by the pi project.
+
+## Requirements
+
+- Ruby 3.2+
+- `pi` on `PATH` (install via `npm i -g @earendil-works/pi-coding-agent`)
+- This gem is pinned against pi `0.75.3`; other versions may work but are not verified.
+
+## Quick start
+
+```ruby
+require "pi_agent"
+
+PiAgent.session do |session|
+  session.prompt("Write a haiku about Ruby") do |event|
+    print event.delta if event.type == :message_update
+  end
+end
+```
+
+A pi RPC process hosts one session, so there is no create/select step —
+`PiAgent.session` spawns `pi --mode rpc` and the session *is* that process.
+
+`prompt` yields each [`Event`](lib/pi_agent/event.rb) until the agent
+finishes (`agent_end`). Without a block it returns an `Enumerator`:
+
+```ruby
+PiAgent.session do |session|
+  events = session.prompt("List three primes")
+  text = events.filter_map(&:delta).join
+  puts text
+end
+```
+
+For a single-shot call, `run` submits a prompt, drains the stream, and
+returns the final assistant text — pi's print mode:
+
+```ruby
+PiAgent.session do |session|
+  puts session.run("What's 2 + 2?")   # => "4"
+end
+```
+
+Other session methods:
+
+- Prompting: `steer`, `follow_up`, `abort`
+- Model: `set_model`, `cycle_model`, `available_models`, `set_thinking`
+- State: `get_state`, `messages`, `last_assistant_text`, `session_stats`
+- Context: `compact`
+- Sessions: `new_session`, `switch_session`, `fork`, `clone_session`,
+  `set_session_name`
+
+`set_model` accepts either `set_model("anthropic/claude-sonnet-4-5")` or
+`set_model("anthropic", "claude-sonnet-4-5")`.
+
+### Images
+
+`prompt`, `steer`, and `follow_up` accept an `images:` array. Entries
+may be `PiAgent::Image` objects, file path strings, or raw
+`ImageContent` hashes, mixed freely:
+
+```ruby
+PiAgent.session do |session|
+  session.prompt("What's in these?", images: [
+    "screenshot.png",                                  # path
+    PiAgent::Image.from_file("diagram.jpg"),           # Image object
+    PiAgent::Image.from_bytes(blob, mime_type: "image/webp")
+  ]) { |e| ... }
+end
+```
+
+Supported formats: png, jpeg, gif, webp.
+
+For low-level RPC access (raw `request`/`notify`/`subscribe`), use
+`PiAgent.open`, which yields a `PiAgent::Client`.
+
+## Extension UI
+
+pi extensions can request user interaction (confirm, select, input,
+editor) mid-run. Pass an `extension_ui` handler to answer them:
+
+```ruby
+handler = lambda do |req|
+  case req.method
+  when :confirm then true              # confirmed
+  when :select  then req.options.first # pick an option
+  when :input   then "default"         # entered text
+  when :editor  then req.prefill       # edited text
+  # fire-and-forget (:notify, :set_status, ...) — return value ignored
+  end
+end
+
+PiAgent.session(extension_ui: handler) do |session|
+  session.prompt("Refactor the parser") { |e| ... }
+end
+```
+
+Returning `nil` from a dialog handler cancels it. With no handler,
+dialogs are auto-cancelled so the agent never hangs. Handlers run on
+their own thread and never block the event stream.
+
+## Forking
+
+```ruby
+PiAgent.session do |session|
+  session.prompt("Add a feature") { |e| ... }
+
+  # Branch from an earlier message
+  forkable = session.fork_messages           # [{ "entryId" =>, "text" => }]
+  session.fork(forkable.first["entryId"])    # => { "text" =>, "cancelled" => }
+
+  session.clone_session                      # duplicate the active branch
+  session.set_session_name("feature-work")
+end
+```
+
+`fork`/`clone_session` return `cancelled: true` (rather than raising) if
+a pi extension vetoes the operation — that is an expected outcome, not
+an error.
+
+## Errors
+
+- A failed RPC command (`success: false`) raises `PiAgent::CommandError`,
+  which carries the failing `#command` name.
+- Agent-side errors arrive *in* the event stream, not as exceptions —
+  inspect them with `Event#error?`, `#error_message`, and `#error_reason`
+  (`"aborted"` vs `"error"`). This covers `extension_error` events and
+  errored assistant turns. The gem does not abort your iteration on
+  agent errors; you decide how to react.
+
+## Protocol reference
+
+The wire protocol is documented upstream in
+[`packages/coding-agent/docs/rpc.md`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md).
+
+## Development
+
+```bash
+bin/setup        # bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/pi_agent/client.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module PiAgent
+  # High-level client. Owns a Transport, correlates request/response by id,
+  # and fans notifications out to subscribers.
+  #
+  #   client = PiAgent::Client.new.start
+  #   client.subscribe { |msg| ... }              # all server-pushed messages
+  #   future = client.request("get_commands")     # request/response
+  #   future.value!(timeout: 5)                   # blocks for response
+  #   client.notify("set_thinking", level: "off") # fire-and-forget (no id)
+  #   client.close
+  #
+  # By default the client spawns `pi --mode rpc` as a local subprocess.
+  # Pass `transport_factory:` — a callable `(on_message:, on_stderr:) ->
+  # transport` — to run pi somewhere else (e.g. inside a remote sandbox).
+  # See Transport for the transport contract.
+  class Client
+    DEFAULT_BIN = "pi"
+    DEFAULT_ARGS = ["--mode", "rpc"].freeze
+
+    attr_reader :bin
+
+    def self.resolve_bin(override = nil)
+      candidate = override || ENV["PI_BIN"] || DEFAULT_BIN
+      path = which(candidate)
+      return path if path
+
+      raise BinaryNotFoundError, <<~MSG
+        Could not find the `pi` binary on PATH (looked for #{candidate.inspect}).
+
+        Install with: npm install -g @earendil-works/pi-coding-agent@#{PiAgent::SUPPORTED_PI_VERSION}
+        Or set PI_BIN to an explicit path.
+      MSG
+    end
+
+    def self.which(cmd)
+      exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [""]
+      ENV["PATH"].to_s.split(File::PATH_SEPARATOR).each do |dir|
+        exts.each do |ext|
+          candidate = File.join(dir, "#{cmd}#{ext}")
+          return candidate if File.executable?(candidate) && !File.directory?(candidate)
+        end
+      end
+      nil
+    end
+
+    def initialize(bin: nil, args: DEFAULT_ARGS, env: {}, cwd: nil, extension_ui: nil, transport_factory: nil)
+      @extension_ui_handler = extension_ui
+      @transport_factory = transport_factory || build_subprocess_factory(bin, args, env, cwd)
+      @pending = {}
+      @pending_mutex = Mutex.new
+      @next_id = 0
+      @subscribers = []
+      @subscribers_mutex = Mutex.new
+      @transport = nil
+      @extension_ui = nil
+    end
+
+    def start
+      @transport = @transport_factory.call(
+        on_message: method(:handle_message),
+        on_stderr: method(:handle_stderr)
+      )
+      @extension_ui = ExtensionUI.new(writer: @transport, handler: @extension_ui_handler)
+      @transport.start
+      self
+    end
+
+    def request(type, params = {})
+      id = next_id
+      future = Future.new
+      @pending_mutex.synchronize { @pending[id] = future }
+      payload = { id: id, type: type }.merge(params)
+      @transport.write(payload)
+      future
+    end
+
+    def notify(type, params = {})
+      payload = { type: type }.merge(params)
+      @transport.write(payload)
+    end
+
+    def subscribe(&block)
+      raise ArgumentError, "subscribe requires a block" unless block
+
+      @subscribers_mutex.synchronize { @subscribers << block }
+      block
+    end
+
+    def unsubscribe(handle)
+      @subscribers_mutex.synchronize { @subscribers.delete(handle) }
+    end
+
+    def close
+      # Drain extension UI handler threads while the transport is still
+      # open so their responses can still be written.
+      @extension_ui&.shutdown
+      @transport&.close
+      reject_pending(ProtocolError.new("Transport closed before response"))
+    end
+
+    def alive?
+      @transport&.alive? || false
+    end
+
+    private
+
+    # Default factory: resolve the pi binary now (so a missing binary
+    # fails fast at construction) and build a subprocess transport on
+    # start, once Client's message handlers are known.
+    def build_subprocess_factory(bin, args, env, cwd)
+      @bin = self.class.resolve_bin(bin)
+      command = [@bin, *Array(args)]
+      lambda do |on_message:, on_stderr:|
+        Transport::Subprocess.new(
+          command: command, env: env, cwd: cwd,
+          on_message: on_message, on_stderr: on_stderr
+        )
+      end
+    end
+
+    def next_id
+      @pending_mutex.synchronize do
+        @next_id += 1
+        "req-#{@next_id}"
+      end
+    end
+
+    def handle_message(msg)
+      type = msg["type"]
+      if type == "response" && msg["id"]
+        deliver_response(msg)
+      elsif type == "extension_ui_request"
+        @extension_ui&.dispatch(msg)
+      else
+        notify_subscribers(msg)
+      end
+    end
+
+    def deliver_response(msg)
+      future = @pending_mutex.synchronize { @pending.delete(msg["id"]) }
+      return unless future
+
+      if msg["success"] == false
+        future.reject(CommandError.new(msg["error"] || "command failed: #{msg.inspect}", command: msg["command"]))
+      else
+        future.resolve(msg)
+      end
+    end
+
+    def notify_subscribers(msg)
+      callbacks = @subscribers_mutex.synchronize { @subscribers.dup }
+      callbacks.each { |cb| cb.call(msg) }
+    end
+
+    def handle_stderr(line)
+      # no-op by default; future versions may wire a logger
+    end
+
+    def reject_pending(error)
+      pending = @pending_mutex.synchronize do
+        snapshot = @pending.values
+        @pending.clear
+        snapshot
+      end
+      pending.each { |f| f.reject(error) }
+    end
+  end
+end

data/lib/pi_agent/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PiAgent
+  class Error < StandardError; end
+
+  class BinaryNotFoundError < Error; end
+  class VersionMismatchError < Error; end
+  class ProtocolError < Error; end
+  class SessionError < Error; end
+  class TimeoutError < Error; end
+
+  # Raised when an RPC command returns `success: false`. Carries the
+  # failing command name so callers can branch on it.
+  class CommandError < Error
+    attr_reader :command
+
+    def initialize(message, command: nil)
+      @command = command
+      super(message)
+    end
+  end
+end

data/lib/pi_agent/event.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PiAgent
+  # Thin typed wrapper over a pi RPC event message. The native JSON payload
+  # is preserved on `#raw` so callers can reach fields we haven't given a
+  # dedicated accessor yet.
+  #
+  # Event types are exposed as Ruby symbols (e.g. `:text_delta`,
+  # `:agent_end`) matching the upstream protocol's `type` field.
+  class Event
+    # Event types that terminate a single prompt's event stream.
+    # `agent_end` fires when the agent finishes processing the current
+    # prompt cycle; we stop iterating then.
+    TERMINAL_TYPES = %i[agent_end].freeze
+
+    attr_reader :raw, :type
+
+    def initialize(raw)
+      @raw = raw
+      @type = raw["type"]&.to_sym
+    end
+
+    def terminal?
+      TERMINAL_TYPES.include?(@type)
+    end
+
+    def [](key)
+      @raw[key.to_s]
+    end
+
+    # Common shorthand for streaming text deltas.
+    # `message_update` with `assistantMessageEvent.type == "text_delta"`.
+    def delta
+      assistant_event&.[]("delta")
+    end
+
+    # True for an `extension_error` event, or a `message_update` whose
+    # assistant event is an error (agent turn errored or was aborted).
+    def error?
+      @type == :extension_error || assistant_event_type == :error
+    end
+
+    # Best-effort error text for an error event; nil if not an error.
+    def error_message
+      return @raw["error"] if @type == :extension_error
+      return nil unless assistant_event_type == :error
+
+      assistant_event["error"] || assistant_event["message"]
+    end
+
+    # Reason for an assistant-event error: "aborted" or "error". nil
+    # otherwise. Use this to distinguish a user abort from a real failure.
+    def error_reason
+      return nil unless assistant_event_type == :error
+
+      assistant_event["reason"]
+    end
+
+    def to_h
+      @raw
+    end
+
+    def inspect
+      "#<#{self.class.name} type=#{@type.inspect}>"
+    end
+
+    private
+
+    def assistant_event
+      ev = @raw["assistantMessageEvent"]
+      ev.is_a?(Hash) ? ev : nil
+    end
+
+    def assistant_event_type
+      assistant_event&.[]("type")&.to_sym
+    end
+  end
+end

data/lib/pi_agent/extension_ui.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module PiAgent
+  # Handles the bidirectional Extension UI sub-protocol.
+  #
+  # pi extensions can request user interaction (`ctx.ui.select`,
+  # `ctx.ui.confirm`, ...). In RPC mode these arrive as
+  # `extension_ui_request` messages. Dialog methods block the agent until
+  # the client sends a matching `extension_ui_response`; fire-and-forget
+  # methods expect no response.
+  #
+  # Each request is handled on its own thread so a slow or blocking
+  # handler never stalls the transport reader thread (and therefore the
+  # agent event stream).
+  #
+  # The handler is a callable taking a Request and returning:
+  #   - select / input / editor : a String value, or nil to cancel
+  #   - confirm                 : true / false, or nil to cancel
+  #   - fire-and-forget methods : return value ignored
+  #
+  # With no handler, dialogs are auto-cancelled so the agent never hangs.
+  class ExtensionUI
+    DIALOG_METHODS = %i[select confirm input editor].freeze
+
+    # One extension UI request. Wraps the raw protocol message.
+    class Request
+      attr_reader :id, :method, :raw
+
+      def initialize(raw)
+        @raw = raw
+        @id = raw["id"]
+        @method = raw["method"]&.to_sym
+      end
+
+      def dialog?
+        DIALOG_METHODS.include?(@method)
+      end
+
+      def title = @raw["title"]
+      def message = @raw["message"]
+      def options = @raw["options"]
+      def placeholder = @raw["placeholder"]
+      def prefill = @raw["prefill"]
+      def timeout_ms = @raw["timeout"]
+      def notify_type = @raw["notifyType"]
+      def text = @raw["text"]
+
+      def [](key)
+        @raw[key.to_s]
+      end
+    end
+
+    def initialize(writer:, handler: nil)
+      @writer = writer
+      @handler = handler
+      @threads = []
+      @mutex = Mutex.new
+    end
+
+    # Route an `extension_ui_request` message. Non-blocking: spawns a
+    # thread to run the handler and (for dialogs) send the response.
+    def dispatch(msg)
+      request = Request.new(msg)
+      @mutex.synchronize do
+        @threads.select!(&:alive?)
+        @threads << Thread.new { handle(request) }
+      end
+    end
+
+    # Wait for in-flight handler threads to finish (each up to `timeout`s).
+    def shutdown(timeout: 5)
+      @mutex.synchronize { @threads.dup }.each { |t| t.join(timeout) }
+    end
+
+    private
+
+    def handle(request)
+      result = invoke_handler(request)
+      return unless request.dialog?
+
+      @writer.write(response_for(request, result))
+    rescue ProtocolError
+      # Transport closed during shutdown; the response is moot.
+    end
+
+    def invoke_handler(request)
+      return nil if @handler.nil?
+
+      @handler.call(request)
+    rescue StandardError
+      # A raising handler cancels the dialog rather than hanging the agent.
+      nil
+    end
+
+    def response_for(request, result)
+      base = { type: "extension_ui_response", id: request.id }
+      return base.merge(cancelled: true) if result.nil?
+      return base.merge(confirmed: result ? true : false) if request.method == :confirm
+
+      base.merge(value: result.to_s)
+    end
+  end
+end

data/lib/pi_agent/framer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PiAgent
+  # Strict LF-only line framer for the pi RPC protocol.
+  #
+  # The protocol explicitly forbids generic line readers (Ruby `readline`,
+  # Node `readline`) because they also split on U+2028 / U+2029, which are
+  # valid inside JSON strings.
+  #
+  # Feed bytes; yield complete lines with any trailing CR stripped. Empty
+  # lines are dropped (the protocol uses single LFs between records).
+  class Framer
+    LF = "\n"
+
+    def initialize
+      @buffer = String.new(encoding: Encoding::BINARY)
+    end
+
+    def feed(bytes)
+      @buffer << bytes.b
+      while (idx = @buffer.index(LF))
+        line = @buffer.byteslice(0, idx)
+        @buffer = @buffer.byteslice(idx + 1, @buffer.bytesize - idx - 1) || String.new(encoding: Encoding::BINARY)
+        line.chomp!("\r")
+        next if line.empty?
+
+        yield line.force_encoding(Encoding::UTF_8)
+      end
+    end
+
+    def buffered?
+      !@buffer.empty?
+    end
+  end
+end

data/lib/pi_agent/future.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module PiAgent
+  # Thread-safe single-shot promise. Used to correlate RPC requests with
+  # their responses across the transport's stdout reader thread and the
+  # caller's thread.
+  class Future
+    def initialize
+      @mon = Monitor.new
+      @cond = @mon.new_cond
+      @resolved = false
+      @value = nil
+      @error = nil
+    end
+
+    def resolve(value)
+      @mon.synchronize do
+        return if @resolved
+
+        @value = value
+        @resolved = true
+        @cond.broadcast
+      end
+    end
+
+    def reject(error)
+      raise ArgumentError, "error must be an Exception" unless error.is_a?(Exception)
+
+      @mon.synchronize do
+        return if @resolved
+
+        @error = error
+        @resolved = true
+        @cond.broadcast
+      end
+    end
+
+    def value!(timeout: nil)
+      @mon.synchronize do
+        unless @resolved
+          @cond.wait(timeout)
+          raise PiAgent::TimeoutError, "Future timed out after #{timeout}s" unless @resolved
+        end
+        raise @error if @error
+
+        @value
+      end
+    end
+
+    def resolved?
+      @mon.synchronize { @resolved }
+    end
+  end
+end

data/lib/pi_agent/image.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module PiAgent
+  # An image attachment for a prompt/steer/follow_up message.
+  #
+  # Serializes to the pi RPC ImageContent shape:
+  #   { "type" => "image", "data" => <base64>, "mimeType" => <mime> }
+  #
+  # The pi prompt commands accept image attachments only; other file
+  # types are not part of the prompt wire protocol.
+  class Image
+    MIME_BY_EXTENSION = {
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif",
+      ".webp" => "image/webp"
+    }.freeze
+
+    attr_reader :data, :mime_type
+
+    # Build from a file on disk. MIME type is inferred from the extension.
+    def self.from_file(path)
+      ext = File.extname(path).downcase
+      mime = MIME_BY_EXTENSION[ext]
+      raise ArgumentError, "Unsupported image extension #{ext.inspect} (#{path})" unless mime
+
+      from_bytes(File.binread(path), mime_type: mime)
+    end
+
+    # Build from raw binary image bytes.
+    def self.from_bytes(bytes, mime_type:)
+      new(data: Base64.strict_encode64(bytes), mime_type: mime_type)
+    end
+
+    # `data` must already be base64-encoded image data.
+    def initialize(data:, mime_type:)
+      @data = data
+      @mime_type = mime_type
+    end
+
+    def to_h
+      { "type" => "image", "data" => @data, "mimeType" => @mime_type }
+    end
+  end
+end

data/lib/pi_agent/session.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module PiAgent
+  # High-level agent session. Wraps a Client and exposes prompt-flow
+  # ergonomics: submit a prompt and iterate the resulting event stream.
+  #
+  #   PiAgent.session do |session|
+  #     session.prompt("Write a haiku").each do |event|
+  #       print event.delta if event.type == :message_update
+  #     end
+  #   end
+  #
+  # A pi RPC process hosts exactly one session, so there is no
+  # create/select step — the Session *is* the running pi process.
+  #
+  # v1 limitation: `prompt` streams one agent cycle (agent_start..agent_end).
+  # Messages queued mid-flight via `follow_up`/`steer` run in subsequent
+  # cycles; consume those by calling `prompt`-less `events` or another
+  # `prompt`. Bidirectional extension UI is not yet surfaced here.
+  class Session
+    # Max time to wait for the next event before assuming the agent stalled.
+    DEFAULT_EVENT_TIMEOUT = 300
+    # Max time to wait for a command to be acknowledged.
+    DEFAULT_ACK_TIMEOUT = 30
+
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Submit a user prompt. With a block, yields each Event until the
+    # agent finishes (agent_end), then returns self. Without a block,
+    # returns an Enumerator of Events.
+    #
+    # `images` accepts PiAgent::Image objects, file path strings, or
+    # raw ImageContent hashes — in any mix.
+    def prompt(message, images: nil, event_timeout: DEFAULT_EVENT_TIMEOUT, &block)
+      stream = event_stream("prompt", message_params(message, images), event_timeout: event_timeout)
+
+      return stream unless block
+
+      stream.each(&block)
+      self
+    end
+
+    # Queue a steering message while the agent is running. Delivered after
+    # the current assistant turn finishes its tool calls, before the next
+    # LLM call. Fire-and-forget; raises on rejection.
+    def steer(message, images: nil)
+      @client.request("steer", message_params(message, images)).value!(timeout: DEFAULT_ACK_TIMEOUT)
+      self
+    end
+
+    # Queue a follow-up message, delivered only after the agent stops.
+    def follow_up(message, images: nil)
+      @client.request("follow_up", message_params(message, images)).value!(timeout: DEFAULT_ACK_TIMEOUT)
+      self
+    end
+
+    # Single-shot helper mirroring pi's print mode: submit `message`,
+    # drain the whole event stream, and return the final assistant text
+    # (nil if the agent produced none). Yields each Event to an optional
+    # block while the stream drains.
+    def run(message, images: nil, event_timeout: DEFAULT_EVENT_TIMEOUT)
+      prompt(message, images: images, event_timeout: event_timeout) do |event|
+        yield event if block_given?
+      end
+      last_assistant_text
+    end
+
+    # Abort the current agent run. Fire-and-forget.
+    def abort
+      @client.notify("abort")
+      self
+    end
+
+    # Switch to a specific model. Accepts either a single "provider/modelId"
+    # string or the two parts as separate arguments.
+    def set_model(provider, model_id = nil)
+      provider, model_id = provider.split("/", 2) if model_id.nil?
+      @client.request("set_model", provider: provider, modelId: model_id)
+             .value!(timeout: DEFAULT_ACK_TIMEOUT)
+      self
+    end
+
+    # Switch to the next configured model. Returns the new
+    # { "model" =>, "thinkingLevel" =>, "isScoped" => } hash, or {} when
+    # only one model is available.
+    def cycle_model
+      request_data("cycle_model")
+    end
+
+    # All configured models, as an array of Model hashes.
+    def available_models
+      request_data("get_available_models").fetch("models", [])
+    end
+
+    # Set the reasoning level: "off", "minimal", "low", "medium", "high",
+    # or "xhigh" (xhigh is OpenAI codex-max only).
+    def set_thinking(level)
+      @client.request("set_thinking_level", level: level).value!(timeout: DEFAULT_ACK_TIMEOUT)
+      self
+    end
+
+    def get_state
+      @client.request("get_state").value!(timeout: DEFAULT_ACK_TIMEOUT)
+    end
+
+    # Full conversation history, as an array of AgentMessage hashes.
+    def messages
+      request_data("get_messages").fetch("messages", [])
+    end
+
+    # Text of the last assistant message, or nil if there is none.
+    def last_assistant_text
+      request_data("get_last_assistant_text")["text"]
+    end
+
+    # Manually compact the conversation context to reduce token usage.
+    # Returns the result hash ({ "summary" =>, "firstKeptEntryId" =>,
+    # "tokensBefore" => }).
+    def compact(custom_instructions: nil)
+      params = {}
+      params[:customInstructions] = custom_instructions if custom_instructions
+      request_data("compact", params)
+    end
+
+    # Start a fresh session in the same pi process. Pass `parent_session:`
+    # (a session file path) to record provenance. Returns
+    # { "cancelled" => bool }; cancelled is true if an extension vetoed it.
+    def new_session(parent_session: nil)
+      params = {}
+      params[:parentSession] = parent_session if parent_session
+      request_data("new_session", params)
+    end
+
+    # Load a different session file into this process. Returns
+    # { "cancelled" => bool }; cancelled is true if an extension vetoed it.
+    def switch_session(path)
+      request_data("switch_session", sessionPath: path)
+    end
+
+    # Token usage, cost, and context-window stats for the current session.
+    # Returns the data hash, including "sessionId" and "sessionFile".
+    def session_stats
+      request_data("get_session_stats")
+    end
+
+    # List user messages available for forking. Returns an array of
+    # { "entryId" => ..., "text" => ... } hashes.
+    def fork_messages
+      request_data("get_fork_messages").fetch("messages", [])
+    end
+
+    # Fork a new branch from a previous user message (an entryId from
+    # `fork_messages`). Returns { "text" => <forked-from text>,
+    # "cancelled" => bool }; `cancelled` is true if an extension vetoed it.
+    def fork(entry_id)
+      request_data("fork", entryId: entry_id)
+    end
+
+    # Duplicate the current active branch into a new session at the
+    # current position. Returns { "cancelled" => bool }. Maps to the
+    # `clone` RPC command (named `clone_session` to avoid shadowing
+    # Object#clone).
+    def clone_session
+      request_data("clone")
+    end
+
+    def set_session_name(name)
+      @client.request("set_session_name", name: name).value!(timeout: DEFAULT_ACK_TIMEOUT)
+      self
+    end
+
+    def close
+      @client.close
+    end
+
+    private
+
+    # Build the { message:, images? } params for a prompt-style command.
+    def message_params(message, images)
+      params = { message: message }
+      normalized = normalize_images(images)
+      params[:images] = normalized unless normalized.empty?
+      params
+    end
+
+    # Coerce mixed image inputs into ImageContent hashes.
+    def normalize_images(images)
+      Array(images).map do |image|
+        case image
+        when Image  then image.to_h
+        when String then Image.from_file(image).to_h
+        when Hash   then image
+        else raise ArgumentError, "Unsupported image: #{image.inspect}"
+        end
+      end
+    end
+
+    # Send a request and return its `data` payload (the part RPC commands
+    # like fork/clone/get_fork_messages carry their result in).
+    def request_data(type, params = {})
+      response = @client.request(type, params).value!(timeout: DEFAULT_ACK_TIMEOUT)
+      response["data"] || {}
+    end
+
+    # Subscribe, send the command, then yield Events from the notification
+    # stream until a terminal event. The subscription is scoped to one
+    # iteration of the returned Enumerator so cleanup is deterministic.
+    def event_stream(type, params, event_timeout:)
+      Enumerator.new do |yielder|
+        queue = Queue.new
+        handle = @client.subscribe { |msg| queue << msg }
+        begin
+          @client.request(type, params).value!(timeout: DEFAULT_ACK_TIMEOUT)
+          pump_events(queue, yielder, event_timeout)
+        ensure
+          @client.unsubscribe(handle)
+        end
+      end
+    end
+
+    def pump_events(queue, yielder, event_timeout)
+      loop do
+        msg = queue.pop(timeout: event_timeout)
+        raise TimeoutError, "No event received within #{event_timeout}s" if msg.nil?
+
+        event = Event.new(msg)
+        yielder << event
+        break if event.terminal?
+      end
+    end
+  end
+end

data/lib/pi_agent/transport/subprocess.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module PiAgent
+  module Transport
+    # Runs `pi --mode rpc` as a local child process and speaks NDJSON
+    # over its stdio.
+    #
+    # One reader thread per pipe; stdout lines are JSON-parsed and
+    # dispatched to `on_message`; stderr lines are forwarded raw to
+    # `on_stderr`. Writes are serialized through a mutex so concurrent
+    # senders don't interleave JSON payloads on stdin.
+    class Subprocess
+      DEFAULT_CHUNK_SIZE = 4096
+      DEFAULT_CLOSE_TIMEOUT = 5
+
+      attr_reader :pid
+
+      # `cwd` sets the child's working directory — pi's built-in tools
+      # (bash/read/edit/...) operate relative to it. nil leaves the
+      # child in this process's working directory.
+      def initialize(command:, env: {}, cwd: nil, on_message: nil, on_stderr: nil)
+        @command = Array(command)
+        @env = env.transform_keys(&:to_s)
+        @cwd = cwd
+        @on_message = on_message
+        @on_stderr = on_stderr
+        @write_mutex = Mutex.new
+        @closed = false
+      end
+
+      def start
+        @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*spawn_args)
+        @pid = @wait_thr.pid
+        @stdin.binmode
+        @stdout.binmode
+        @stderr.binmode
+        @stdout_thread = Thread.new { read_loop(@stdout, :stdout) }
+        @stderr_thread = Thread.new { read_loop(@stderr, :stderr) }
+        self
+      end
+
+      def write(obj)
+        payload = "#{JSON.generate(obj)}\n"
+        @write_mutex.synchronize do
+          raise ProtocolError, "Transport closed" if @closed
+
+          @stdin.write(payload)
+          @stdin.flush
+        end
+      rescue Errno::EPIPE
+        raise ProtocolError, "Broken pipe writing to subprocess (process may have exited)"
+      end
+
+      def close(timeout: DEFAULT_CLOSE_TIMEOUT)
+        return if mark_closed!
+
+        safe_close(@stdin)
+        wait_for_exit(timeout)
+        [@stdout_thread, @stderr_thread].compact.each(&:join)
+        safe_close(@stdout)
+        safe_close(@stderr)
+      end
+
+      def alive?
+        !!@wait_thr&.alive?
+      end
+
+      def exit_status
+        @wait_thr&.value
+      end
+
+      private
+
+      def spawn_args
+        args = [@env, *@command]
+        args << { chdir: @cwd.to_s } if @cwd
+        args
+      end
+
+      def mark_closed!
+        @write_mutex.synchronize do
+          return true if @closed
+
+          @closed = true
+          false
+        end
+      end
+
+      def safe_close(io)
+        io&.close
+      rescue IOError
+        # already closed
+      end
+
+      def wait_for_exit(timeout)
+        return if @wait_thr&.join(timeout)
+
+        terminate_process
+        return if @wait_thr&.join(2)
+
+        kill_process
+        @wait_thr&.join
+      end
+
+      def read_loop(io, channel)
+        framer = Framer.new
+        loop do
+          chunk = io.readpartial(DEFAULT_CHUNK_SIZE)
+          framer.feed(chunk) do |line|
+            channel == :stdout ? dispatch_stdout(line) : @on_stderr&.call(line)
+          end
+        end
+      rescue IOError, Errno::EBADF
+        # Pipe closed; reader exits normally. (EOFError descends from IOError.)
+      end
+
+      def dispatch_stdout(line)
+        msg = JSON.parse(line)
+        @on_message&.call(msg)
+      rescue JSON::ParserError => e
+        @on_stderr&.call("[pi-agent-rb] invalid JSON on stdout: #{e.message}: #{line.inspect}")
+      end
+
+      def terminate_process
+        Process.kill("TERM", @pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # Process already gone
+      end
+
+      def kill_process
+        Process.kill("KILL", @pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # Process already gone
+      end
+    end
+  end
+end

data/lib/pi_agent/transport.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PiAgent
+  # A transport carries the pi RPC protocol between this process and a
+  # running `pi --mode rpc`. It abstracts *where* pi runs: a local
+  # subprocess (Transport::Subprocess), or — via a caller-supplied
+  # transport — a process inside a remote sandbox.
+  #
+  # Contract. A transport is constructed with two callables:
+  #
+  #   on_message: ->(Hash)    # one parsed JSON message from pi's stdout
+  #   on_stderr:  ->(String)  # one line from pi's stderr
+  #
+  # and responds to:
+  #
+  #   #start            -> self;  begin delivering messages
+  #   #write(Hash)      -> serialize to a JSON line, send to pi's stdin
+  #   #close(timeout:)  -> shut pi down
+  #   #alive?           -> Boolean
+  #
+  # Implementations own framing (pi speaks strict-LF JSONL — see Framer)
+  # and the thread-safety of #write. Client injects its own handlers via
+  # a transport factory, so transports never need settable callbacks.
+  module Transport
+  end
+end

data/lib/pi_agent/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PiAgent
+  VERSION = "0.1.0"
+
+  # Pinned upstream pi-coding-agent version this gem is verified against.
+  # See: https://www.npmjs.com/package/@earendil-works/pi-coding-agent
+  SUPPORTED_PI_VERSION = "0.75.3"
+end

data/lib/pi_agent.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "pi_agent/version"
+require_relative "pi_agent/errors"
+require_relative "pi_agent/framer"
+require_relative "pi_agent/future"
+require_relative "pi_agent/transport"
+require_relative "pi_agent/transport/subprocess"
+require_relative "pi_agent/extension_ui"
+require_relative "pi_agent/client"
+require_relative "pi_agent/event"
+require_relative "pi_agent/image"
+require_relative "pi_agent/session"
+
+module PiAgent
+  # Open a low-level RPC client (spawns `pi --mode rpc`).
+  def self.open(**)
+    client = Client.new(**).start
+    return client unless block_given?
+
+    begin
+      yield client
+    ensure
+      client.close
+    end
+  end
+
+  # Open a high-level agent session. This is the common entrypoint.
+  def self.session(**)
+    client = Client.new(**).start
+    session = Session.new(client)
+    return session unless block_given?
+
+    begin
+      yield session
+    ensure
+      session.close
+    end
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: pi-agent-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- chagel
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: |
+  Ruby client for `@earendil-works/pi-coding-agent`. Spawns the pi CLI in RPC
+  mode and speaks its JSONL protocol from Ruby. Designed for building
+  interactive agent UIs (web, TUI) on top of pi.
+
+  Not officially maintained by the pi project.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/pi_agent.rb
+- lib/pi_agent/client.rb
+- lib/pi_agent/errors.rb
+- lib/pi_agent/event.rb
+- lib/pi_agent/extension_ui.rb
+- lib/pi_agent/framer.rb
+- lib/pi_agent/future.rb
+- lib/pi_agent/image.rb
+- lib/pi_agent/session.rb
+- lib/pi_agent/transport.rb
+- lib/pi_agent/transport/subprocess.rb
+- lib/pi_agent/version.rb
+homepage: https://github.com/chagel/pi-agent-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/chagel/pi-agent-rb
+  source_code_uri: https://github.com/chagel/pi-agent-rb
+  changelog_uri: https://github.com/chagel/pi-agent-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby client for the pi coding agent (drives `pi --mode rpc`)
+test_files: []