pikuri-core 0.0.7 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +17 -30
  3. data/lib/pikuri/agent/chat_transport.rb +168 -107
  4. data/lib/pikuri/agent/configurator.rb +194 -173
  5. data/lib/pikuri/agent/control/cancellable.rb +100 -70
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +107 -118
  8. data/lib/pikuri/agent/control.rb +13 -35
  9. data/lib/pikuri/agent/event.rb +144 -197
  10. data/lib/pikuri/agent/extension.rb +83 -95
  11. data/lib/pikuri/agent/history.rb +247 -0
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +169 -136
  14. data/lib/pikuri/agent/listener/token_log.rb +84 -157
  15. data/lib/pikuri/agent/listener.rb +24 -44
  16. data/lib/pikuri/agent/listener_list.rb +32 -47
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +1095 -577
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/bundler_env.rb +68 -0
  21. data/lib/pikuri/extractor/passthrough.rb +24 -31
  22. data/lib/pikuri/extractor.rb +125 -155
  23. data/lib/pikuri/file_type.rb +64 -136
  24. data/lib/pikuri/finalizers.rb +32 -47
  25. data/lib/pikuri/paths.rb +104 -13
  26. data/lib/pikuri/sanitizer.rb +46 -67
  27. data/lib/pikuri/subprocess.rb +86 -118
  28. data/lib/pikuri/testing.rb +369 -0
  29. data/lib/pikuri/tool/calculator.rb +168 -74
  30. data/lib/pikuri/tool/execute_context.rb +42 -0
  31. data/lib/pikuri/tool/parameters.rb +31 -29
  32. data/lib/pikuri/tool/result.rb +164 -0
  33. data/lib/pikuri/tool/trifecta_legs.rb +248 -0
  34. data/lib/pikuri/tool.rb +416 -67
  35. data/lib/pikuri/trifecta/contribution.rb +43 -0
  36. data/lib/pikuri/trifecta/node.rb +47 -0
  37. data/lib/pikuri/trifecta/report.rb +228 -0
  38. data/lib/pikuri/trifecta.rb +126 -0
  39. data/lib/pikuri/version.rb +1 -1
  40. data/lib/pikuri-core.rb +70 -92
  41. data/prompts/agent-loop.txt +5 -0
  42. data/prompts/pikuri-chat.txt +3 -12
  43. metadata +26 -72
  44. data/lib/pikuri/agent/context_window_detector.rb +0 -222
  45. data/lib/pikuri/agent/control/step_limit.rb +0 -111
  46. data/lib/pikuri/agent/extension_context.rb +0 -147
  47. data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
  48. data/lib/pikuri/agent/synthesizer.rb +0 -171
  49. data/lib/pikuri/extractor/html.rb +0 -303
  50. data/lib/pikuri/tool/fetch.rb +0 -172
  51. data/lib/pikuri/tool/scraper.rb +0 -186
  52. data/lib/pikuri/tool/search/brave.rb +0 -198
  53. data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
  54. data/lib/pikuri/tool/search/engines.rb +0 -186
  55. data/lib/pikuri/tool/search/exa.rb +0 -229
  56. data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
  57. data/lib/pikuri/tool/search/result.rb +0 -29
  58. data/lib/pikuri/tool/web_scrape.rb +0 -121
  59. data/lib/pikuri/tool/web_search.rb +0 -57
  60. data/lib/pikuri/url_cache.rb +0 -112
@@ -2,158 +2,93 @@
2
2
 
3
3
  module Pikuri
4
4
  class Agent
5
- # Build-time collector yielded into the +Pikuri::Agent.new+ block.
6
- # Hosts and {Extension} implementations call its methods to declare
7
- # additional tools, listeners, system-prompt snippets, +on_close+
8
- # handlers, extension instances, and persona-flavored sub-agents;
9
- # {Agent#initialize} drains the collected state into the agent's
10
- # final wiring before returning.
11
- #
12
- # == Why this exists
13
- #
14
- # Splits "configure the agent" from "the agent's runtime state".
15
- # Hosts can write a block that reads cleanly:
5
+ # The one handle for wiring an {Agent}, yielded into the +Pikuri::Agent.new+
6
+ # block and handed to every {Extension#configure}:
16
7
  #
17
8
  # Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
18
9
  # c.add_listener Pikuri::Agent::Listener::Terminal.new
19
- # c.add_tool Pikuri::Tool::WebSearch.build
20
- # c.add_tool Pikuri::Tool::WEB_SCRAPE
21
- # c.add_tool Pikuri::Tool::FETCH
22
- # c.add_extension Pikuri::Skill::Extension.new(catalog: catalog)
10
+ # c.add_tool Pikuri::Tool::CALCULATOR
11
+ # c.add_extension Pikuri::Workspace::Extension.new(filesystem: fs, confirmer: confirmer)
23
12
  # end
24
13
  #
25
- # == Two tool pools: regular vs. sub-agent-only
14
+ # Two kinds of call. *Declarations* — {#add_tool}, {#add_listener},
15
+ # {#add_extension}, {#on_close} — shape the agent being built. *Capabilities*
16
+ # — {#emit_event}, {#add_raw_tool}, {#sub_agent_listeners},
17
+ # {#replace_compacted_history} — act on the live
18
+ # agent, so an extension keeps the Configurator and uses them later, from a
19
+ # callback or a tool's +execute+:
20
+ #
21
+ # def configure(c)
22
+ # @list.on_change = -> { c.emit_event(ListChanged.new(items: @list.items)) }
23
+ # end
24
+ #
25
+ # == Why a handed object, not methods on Agent
26
+ #
27
+ # {Agent} has no public path to these capabilities (no +listeners+ or
28
+ # +chat+ reader, no emit method): holding an agent grants read access to
29
+ # its config and nothing more. The way to them is to be handed the
30
+ # Configurator — by +Agent.new+, or onward by whoever was
31
+ # ({Pikuri::SubAgent::SubAgentTool} keeps its extension's). The boundary is
32
+ # the API contract, not a mechanical seal.
26
33
  #
27
- # {#add_tool} registers a tool the parent agent can call: it lands
28
- # in {#tools} and gets handed to ruby_llm via +chat.with_tool+.
29
- # {#add_sub_agent_tool} registers a tool the parent *cannot* call
30
- # — it lands in {#sub_agent_tools} and is never sent to ruby_llm
31
- # for the parent, but is visible to {Pikuri::SubAgent::Extension}'s
32
- # persona-tool-name resolution. The use case is the lethal-trifecta
33
- # defense in {Pikuri::Code::Bash::Sandbox} terms: keep network tools
34
- # (+web_search+ / +web_scrape+ / +fetch+) off the parent so a prompt-
35
- # injected file read cannot egress through the parent's own tools,
36
- # while still letting the +researcher+ persona reach them via the
37
- # +agent+ delegation tool. See SECURITY.md §"Defense: capability
38
- # boundaries via sub-agents".
34
+ # == Two tool pools: regular vs. sub-agent-only
39
35
  #
40
- # Extensions implement their +configure(c)+ hook against the same
41
- # type, so the call sites for "block users add stuff" and
42
- # "extensions add stuff" share one API.
36
+ # {#add_tool} registers a tool the parent agent can call. {#add_sub_agent_tool}
37
+ # registers one the parent *cannot* call, which only a sub-agent whose
38
+ # persona names it receives. The use case is the lethal-trifecta defense:
39
+ # keep network tools (+web_search+ / +web_scrape+ / +fetch+) off the parent
40
+ # so a prompt-injected file read can't egress through it, while the
41
+ # +researcher+ persona still reaches them via the +agent+ tool. See
42
+ # SECURITY.md.
43
43
  #
44
- # == Lifecycle
44
+ # == Implementation details
45
45
  #
46
- # One +Configurator+ per +Agent.new+ invocation. The Configurator
47
- # is constructed inside {Agent#initialize}, yielded to the block
48
- # (if any), then its collected state is drained by the Agent body.
49
- # The Configurator instance is discarded once +Agent.new+ returns
50
- # — it carries no runtime state.
46
+ # {#add_raw_tool} reaches the chat at once, so a raw tool added inside the
47
+ # block precedes the regular tools, which the Agent registers when the block
48
+ # returns. An event emitted inside the block reaches only the listeners
49
+ # added so far.
51
50
  class Configurator
52
- # @return [Agent::ChatTransport] same transport the Agent will
53
- # use. Extensions read this to wire helpers consistently
54
- # (e.g. an MCP description-synthesizer that calls the same
55
- # model the agent itself uses).
56
- attr_reader :transport
57
-
58
- # @return [String] the +system_prompt:+ kwarg passed to
59
- # {Agent#initialize}, untouched. Extensions append to the
60
- # prompt via {#append_system_prompt} rather than mutating
61
- # this; the attribute exists so a peek at the base is
62
- # available for diagnostics.
63
- attr_reader :system_prompt_base
64
-
65
- # @return [String] this agent's unique identifier; empty for the
66
- # main agent, persona-rooted (e.g. +"researcher 0"+) for sub-agents.
67
- attr_reader :id
68
-
69
- # @return [Boolean] +true+ when the agent opted into chunk-level
70
- # streaming.
71
- attr_reader :streaming
72
-
73
- # @return [Control::StepLimit, nil] step-budget control passed
74
- # to the Agent ctor, or +nil+.
75
- attr_reader :step_limit
76
-
77
- # @return [Control::Cancellable, nil] cancellation control
78
- # passed to the Agent ctor, or +nil+. Extensions that run
79
- # sub-LLM calls during +configure+ (e.g. an MCP description
80
- # synthesizer) share this so a user cancel during boot
81
- # propagates correctly.
82
- attr_reader :cancellable
83
-
84
- # @return [Control::Interloper, nil] mid-loop user-input queue
85
- # passed to the Agent ctor, or +nil+.
86
- attr_reader :interloper
87
-
88
- # @return [Array<Tool>] tools added via {#add_tool}, in
89
- # declaration order. Drained by {Agent#initialize} and
90
- # registered with ruby_llm so the parent LLM can call them.
51
+ # @return [Agent] the agent being built. Its constructor arguments
52
+ # (+transport+, +id+, +cancellable+, +interloper+, ...) are readable at
53
+ # once; what the block declares (+tools+, +system_prompt+) only once
54
+ # +Agent.new+ returns.
55
+ attr_reader :agent
56
+
57
+ # @return [History, nil] the conversation +Agent.new(history:)+ resumes,
58
+ # as passed in, or +nil+ for a fresh one — so an extension can rebuild
59
+ # what the transcript implies (MCP re-registers the tools of servers it
60
+ # had connected).
61
+ attr_reader :history
62
+
63
+ # @return [Array<Tool>] tools added via {#add_tool}, in declaration order.
91
64
  attr_reader :tools
92
65
 
93
- # @return [Array<Tool>] tools added via {#add_sub_agent_tool},
94
- # in declaration order. Drained by {Agent#initialize} but
95
- # *not* registered with ruby_llm — invisible to the parent
96
- # LLM, available only to sub-agents through
97
- # {Pikuri::SubAgent::Extension}'s persona-tool-name
98
- # resolution. See the class header.
66
+ # @return [Array<Tool>] tools added via {#add_sub_agent_tool}, in
67
+ # declaration order.
99
68
  attr_reader :sub_agent_tools
100
69
 
101
- # @return [Array<Listener::Base>] listeners added via
102
- # {#add_listener}, in declaration order. Drained by
103
- # {Agent#initialize}.
104
- attr_reader :listeners
105
-
106
- # @return [Array<String>] system-prompt snippets added via
107
- # {#append_system_prompt}, in declaration order. Joined with
108
- # double-newline separators between the base prompt and each
109
- # snippet by {Agent#initialize}.
110
- attr_reader :system_prompt_additions
111
-
112
- # @return [Array<Proc>] +on_close+ handlers added via
113
- # {#on_close}, in declaration order. Fired by {Agent#close}
114
- # in LIFO order with per-handler rescue.
115
- attr_reader :on_close_handlers
116
-
117
- # @return [Array<#configure>] extension instances added via
118
- # {#add_extension}, in declaration order. The Agent ctor
119
- # walks this list after wiring is complete and calls +bind+
120
- # on each with the agent's {ExtensionContext}.
70
+ # @return [Array<Extension>] extensions added via {#add_extension}, in
71
+ # declaration order.
121
72
  attr_reader :extensions
122
73
 
123
- # @param transport [Agent::ChatTransport]
124
- # @param system_prompt_base [String]
125
- # @param id [String]
126
- # @param streaming [Boolean]
127
- # @param step_limit [Control::StepLimit, nil]
128
- # @param cancellable [Control::Cancellable, nil]
129
- # @param interloper [Control::Interloper, nil]
130
- # @param on_close_sink [Array<Proc>, nil] array that {#on_close}
131
- # appends to. {Agent#initialize} passes its own live
132
- # +@on_close_handlers+ so a handler an extension arms via
133
- # +c.on_close+ is reachable the instant it's registered — which
134
- # is what lets the constructor close a half-built agent if a
135
- # later extension's +configure+ raises. Defaults to a fresh
136
- # array for standalone use (e.g. specs).
137
- def initialize(transport:, system_prompt_base:, id:, streaming:,
138
- step_limit:, cancellable:, interloper:, on_close_sink: nil)
139
- @transport = transport
140
- @system_prompt_base = system_prompt_base
141
- @id = id
142
- @streaming = streaming
143
- @step_limit = step_limit
144
- @cancellable = cancellable
145
- @interloper = interloper
146
-
74
+ # @param agent [Agent] the agent under construction
75
+ # @param chat [RubyLLM::Chat] its chat, the target of {#add_raw_tool}
76
+ # @param listeners [ListenerList] its listener list
77
+ # @param history [History, nil]
78
+ # @param on_close_sink [Array<Proc>] the agent's live +on_close+ list, so
79
+ # a handler armed mid-block is there when a later +configure+ raises
80
+ # and the constructor closes the half-built agent.
81
+ def initialize(agent:, chat:, listeners:, history:, on_close_sink:)
82
+ @agent = agent
83
+ @chat = chat
84
+ @listeners = listeners
85
+ @history = history
86
+ @on_close_handlers = on_close_sink
147
87
  @tools = []
148
88
  @sub_agent_tools = []
149
- @listeners = []
150
- @system_prompt_additions = []
151
- @on_close_handlers = on_close_sink || []
152
89
  @extensions = []
153
90
  end
154
91
 
155
- # Append a tool to the agent's static tool list.
156
- #
157
92
  # @param tool [Tool]
158
93
  # @return [void]
159
94
  def add_tool(tool)
@@ -161,20 +96,14 @@ module Pikuri
161
96
  nil
162
97
  end
163
98
 
164
- # Append several tools at once. Equivalent to calling {#add_tool}
165
- # for each element of +tools+; declaration order is preserved.
166
- #
167
99
  # @param tools [Enumerable<Tool>]
168
100
  # @return [void]
169
101
  def add_tools(tools)
170
- tools.each { |t| @tools << t }
102
+ tools.each { |t| add_tool(t) }
171
103
  nil
172
104
  end
173
105
 
174
- # Append a tool to the sub-agent-only pool. The parent LLM
175
- # never sees it; only sub-agents whose persona +tool_names+
176
- # include the tool's +name+ get it in their toolset. See the
177
- # class header for the trifecta-defense rationale.
106
+ # Add a tool only sub-agents can receive; see +== Two tool pools+.
178
107
  #
179
108
  # @param tool [Tool]
180
109
  # @return [void]
@@ -183,61 +112,42 @@ module Pikuri
183
112
  nil
184
113
  end
185
114
 
186
- # Append a listener to the agent's listener list.
187
- #
188
115
  # @param listener [Listener::Base]
189
116
  # @return [void]
190
117
  def add_listener(listener)
191
- @listeners << listener
118
+ @listeners.add(listener)
192
119
  nil
193
120
  end
194
121
 
195
- # Append several listeners at once. Accepts any enumerable
196
- # (Array, {ListenerList}, …); declaration order is preserved.
197
- #
198
122
  # @param listeners [Enumerable<Listener::Base>]
199
123
  # @return [void]
200
124
  def add_listeners(listeners)
201
- listeners.each { |l| @listeners << l }
202
- nil
203
- end
204
-
205
- # Append a snippet to the system prompt. Snippets are joined
206
- # to the base prompt with double-newline separators.
207
- #
208
- # Used by extensions to register +<available_skills>+,
209
- # +<available_mcps>+, and similar advertisement blocks. Block
210
- # users typically pass the full system prompt via the ctor's
211
- # +system_prompt:+ kwarg instead.
212
- #
213
- # @param snippet [String]
214
- # @return [void]
215
- def append_system_prompt(snippet)
216
- @system_prompt_additions << snippet
125
+ listeners.each { |l| add_listener(l) }
217
126
  nil
218
127
  end
219
128
 
220
- # Register an extension. The extension's +configure(self)+ is
221
- # called immediately so source-order matches execution-order.
222
- # The instance is also retained for the +bind(ctx)+ sweep
223
- # that runs at the end of {Agent#initialize}.
129
+ # Register an extension and run its +configure(self)+ at once, so source
130
+ # order is execution order: a later extension sees what earlier ones
131
+ # added. +include Pikuri::Agent::Extension+ for no-op defaults.
224
132
  #
225
- # Extensions must implement both +configure+ and +bind+. The
226
- # easy way is to +include Pikuri::Agent::Extension+ — that
227
- # mixes in empty defaults for both, so an extension overrides
228
- # only what it cares about and leaves the other as a no-op.
133
+ # An instance serves one agent ({Extension}), so one already added to
134
+ # any agent — this one included, and even after that agent closed — is
135
+ # refused before its +configure+ runs. Reuse is a host bug that fails
136
+ # quietly otherwise: the second agent would share the first one's
137
+ # per-conversation state and the servers it started.
229
138
  #
230
- # @param extension [Extension, #configure, #bind] extension instance
139
+ # @param extension [Extension, #configure] extension instance
231
140
  # @return [void]
141
+ # @raise [ArgumentError] when +extension+ was already added to an agent
232
142
  def add_extension(extension)
143
+ claim(extension)
233
144
  @extensions << extension
234
145
  extension.configure(self)
235
146
  nil
236
147
  end
237
148
 
238
- # Register a handler called by {Agent#close}. Handlers fire in
239
- # LIFO order, each inside its own +rescue+ — same semantics as
240
- # +ensure+-block cleanup discipline.
149
+ # Register a handler called by {Agent#close} (LIFO, each inside its own
150
+ # +rescue+).
241
151
  #
242
152
  # @yield called with no arguments at close time
243
153
  # @return [void]
@@ -247,6 +157,117 @@ module Pikuri
247
157
  @on_close_handlers << blk
248
158
  nil
249
159
  end
160
+
161
+ # Emit a domain event onto the agent's listener stream. Core {Event}
162
+ # variants narrate the loop; gems define their own (e.g. a task list's
163
+ # +ListChanged+) and emit them here. Listeners no-op on
164
+ # variants they don't recognize ({Listener::Base#on_event}'s default).
165
+ #
166
+ # Call it on the agent's thread — typically inside a tool's +execute+,
167
+ # landing between {Event::ToolCall} and {Event::ToolResult}.
168
+ #
169
+ # @param event [Object] an immutable event value (by convention a +Data+)
170
+ # @return [void]
171
+ def emit_event(event)
172
+ @listeners.on_event(event)
173
+ nil
174
+ end
175
+
176
+ # Register a raw +RubyLLM::Tool+ subclass on the agent's chat, bypassing
177
+ # {Pikuri::Tool}'s strict validation — MCP's tools, whose schema is the
178
+ # server's. Usable mid-conversation (+mcp_connect+ adds a server's tools
179
+ # when the model asks).
180
+ #
181
+ # The tool does NOT enter {Agent#tools}, so sub-agents can't snapshot it:
182
+ # activation is strictly per-agent.
183
+ #
184
+ # @param ruby_llm_tool [Class] subclass of +RubyLLM::Tool+
185
+ # @return [void]
186
+ def add_raw_tool(ruby_llm_tool)
187
+ @chat.with_tools(ruby_llm_tool)
188
+ nil
189
+ end
190
+
191
+ # Replace the conversation with a shorter rendering of *itself* — the
192
+ # actuator a compaction extension drives, deciding when and how to
193
+ # shorten on its own:
194
+ #
195
+ # def configure(c)
196
+ # @c = c
197
+ # end
198
+ #
199
+ # def on_user_message(_content, _attachments)
200
+ # @c.replace_compacted_history(compact(@c.agent.export_history)) if over_budget?
201
+ # nil
202
+ # end
203
+ #
204
+ # Only the messages change. Tools, MCP connections and the servers
205
+ # behind them, every extension's state (a workspace's read-marks,
206
+ # promoted skills), listeners, the system prompt and the transport all
207
+ # stand, because a compacted conversation is still the same
208
+ # conversation. The incoming messages get {Agent}'s resume repairs.
209
+ #
210
+ # So +history+ must be *this* conversation, shortened: handed a
211
+ # different one, that conversation inherits everything this one built
212
+ # up, the logged-in browser behind an MCP server included. Nothing
213
+ # checks this beyond the shape below; the name is the guard. See
214
+ # +design/decisions.md+ +D_compaction_in_place+.
215
+ #
216
+ # Shape it must keep, enforced:
217
+ #
218
+ # - end with the conversation's current last message, same {History::Message#id};
219
+ # rewriting its content is fine;
220
+ # - keep each tool result right after the assistant turn that made its call.
221
+ #
222
+ # Keep the ids of every other message you carry over too, so state an
223
+ # extension keys on one still finds it. Callable on the agent's thread
224
+ # anywhere outside an open tool batch: between turns, or from
225
+ # {Extension#on_user_message}.
226
+ #
227
+ # @param history [History] typically {Agent#export_history}, shortened
228
+ # @return [void]
229
+ # @raise [ArgumentError] if +history+ breaks the shape above
230
+ # @raise [RuntimeError] inside the +Agent.new+ block, or while a tool
231
+ # batch is open (from a tool's +execute+)
232
+ def replace_compacted_history(history)
233
+ # Private on Agent, so holding an agent doesn't grant it.
234
+ @agent.send(:replace_compacted_history, history)
235
+ nil
236
+ end
237
+
238
+ # A listener list for a spawned sub-agent, via {ListenerList#for_sub_agent}.
239
+ #
240
+ # @param params [Hash{Symbol => Object}] forwarded to each listener's
241
+ # +for_sub_agent+ hook (currently +id:+)
242
+ # @return [ListenerList]
243
+ def sub_agent_listeners(**params)
244
+ @listeners.for_sub_agent(**params)
245
+ end
246
+
247
+ # Every extension ever added, process-wide. Keyed by identity (a
248
+ # +WeakMap+, not a +WeakKeyMap+, so two equal value objects stay two
249
+ # extensions) and weak, so a claim never keeps an extension alive.
250
+ CLAIMED = ObjectSpace::WeakMap.new
251
+ # Agents may be built on several threads; the check and the mark are
252
+ # one step.
253
+ CLAIM_LOCK = Mutex.new
254
+ private_constant :CLAIMED, :CLAIM_LOCK
255
+
256
+ private
257
+
258
+ # @param extension [Object]
259
+ # @return [void]
260
+ # @raise [ArgumentError] when +extension+ is already claimed
261
+ def claim(extension)
262
+ CLAIM_LOCK.synchronize do
263
+ if CLAIMED.key?(extension)
264
+ raise ArgumentError, "#{extension.class} instance is already added to an agent; " \
265
+ 'build a fresh one for every Agent.new'
266
+ end
267
+
268
+ CLAIMED[extension] = true
269
+ end
270
+ end
250
271
  end
251
272
  end
252
273
  end