Class: PiAgent::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/pi_agent/client.rb

Overview

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.

Since pi 0.79.0 project-local inputs (.pi/settings.json, project extensions, resources, packages) are trust-gated, and in RPC mode pi silently ignores them unless the project was already trusted. Pass ‘approve: true` to trust the project (`–approve`), or `approve: false` to explicitly ignore project inputs (`–no-approve`).

Constant Summary collapse

DEFAULT_BIN = 
"pi"
DEFAULT_ARGS = 
["--mode", "rpc"].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(bin: nil, args: DEFAULT_ARGS, env: {}, cwd: nil, approve: nil, extension_ui: nil, transport_factory: nil) ⇒ Client

Returns a new instance of Client.



54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/pi_agent/client.rb', line 54

def initialize(bin: nil, args: DEFAULT_ARGS, env: {}, cwd: nil, approve: nil,
               extension_ui: nil, transport_factory: nil)
  @extension_ui_handler = extension_ui
  args = [*args, approve ? "--approve" : "--no-approve"] unless approve.nil?
  @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

Instance Attribute Details

#bin ⇒ Object (readonly)

Returns the value of attribute bin.



28
29
30
 
# File 'lib/pi_agent/client.rb', line 28

def bin
  @bin
end

Class Method Details

.resolve_bin(override = nil) ⇒ Object

Raises:



30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/pi_agent/client.rb', line 30

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

.which(cmd) ⇒ Object 



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/pi_agent/client.rb', line 43

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

Instance Method Details

#alive? ⇒ Boolean

Returns:

  • (Boolean) 


111
112
113
 
# File 'lib/pi_agent/client.rb', line 111

def alive?
  @transport&.alive? || false
end

#close ⇒ Object 



103
104
105
106
107
108
109
 
# File 'lib/pi_agent/client.rb', line 103

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

#notify(type, params = {}) ⇒ Object 



87
88
89
90
 
# File 'lib/pi_agent/client.rb', line 87

def notify(type, params = {})
  payload = { type: type }.merge(params)
  @transport.write(payload)
end

#request(type, params = {}) ⇒ Object 



78
79
80
81
82
83
84
85
 
# File 'lib/pi_agent/client.rb', line 78

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

#start ⇒ Object 



68
69
70
71
72
73
74
75
76
 
# File 'lib/pi_agent/client.rb', line 68

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

#subscribe(&block) ⇒ Object

Raises:

  • (ArgumentError) 


92
93
94
95
96
97
 
# File 'lib/pi_agent/client.rb', line 92

def subscribe(&block)
  raise ArgumentError, "subscribe requires a block" unless block

  @subscribers_mutex.synchronize { @subscribers << block }
  block
end

#unsubscribe(handle) ⇒ Object 



99
100
101
 
# File 'lib/pi_agent/client.rb', line 99

def unsubscribe(handle)
  @subscribers_mutex.synchronize { @subscribers.delete(handle) }
end