pikuri-core 0.1.0 → 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.
- checksums.yaml +4 -4
- data/README.md +16 -29
- data/lib/pikuri/agent/chat_transport.rb +114 -33
- data/lib/pikuri/agent/configurator.rb +191 -110
- data/lib/pikuri/agent/control/cancellable.rb +25 -16
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +87 -120
- data/lib/pikuri/agent/control.rb +9 -11
- data/lib/pikuri/agent/event.rb +73 -61
- data/lib/pikuri/agent/extension.rb +45 -81
- data/lib/pikuri/agent/history.rb +91 -497
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +115 -108
- data/lib/pikuri/agent/listener/token_log.rb +21 -55
- data/lib/pikuri/agent/listener.rb +4 -4
- data/lib/pikuri/agent/listener_list.rb +19 -13
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +624 -448
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/extractor/passthrough.rb +5 -2
- data/lib/pikuri/extractor.rb +43 -12
- data/lib/pikuri/file_type.rb +4 -4
- data/lib/pikuri/finalizers.rb +2 -2
- data/lib/pikuri/paths.rb +1 -1
- data/lib/pikuri/sanitizer.rb +4 -3
- data/lib/pikuri/subprocess.rb +17 -5
- data/lib/pikuri/testing.rb +122 -49
- data/lib/pikuri/tool/calculator.rb +134 -30
- data/lib/pikuri/tool/execute_context.rb +2 -2
- data/lib/pikuri/tool/parameters.rb +10 -0
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +52 -21
- data/lib/pikuri/tool.rb +298 -24
- data/lib/pikuri/trifecta/report.rb +28 -30
- data/lib/pikuri/trifecta.rb +1 -2
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +5 -11
- metadata +16 -73
- data/lib/pikuri/agent/context_window_detector.rb +0 -181
- data/lib/pikuri/agent/control/step_limit.rb +0 -95
- data/lib/pikuri/agent/extension_context.rb +0 -120
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
- data/lib/pikuri/agent/synthesizer.rb +0 -129
- data/lib/pikuri/extractor/html.rb +0 -256
- data/lib/pikuri/ruby_llm_patches.rb +0 -106
- data/lib/pikuri/tool/fetch.rb +0 -146
- data/lib/pikuri/tool/scraper.rb +0 -144
- data/lib/pikuri/tool/search/brave.rb +0 -170
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
- data/lib/pikuri/tool/search/engines.rb +0 -319
- data/lib/pikuri/tool/search/exa.rb +0 -195
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
- data/lib/pikuri/tool/search/result.rb +0 -24
- data/lib/pikuri/tool/web_scrape.rb +0 -105
- data/lib/pikuri/tool/web_search.rb +0 -133
- data/lib/pikuri/url_cache.rb +0 -96
data/lib/pikuri/tool.rb
CHANGED
|
@@ -33,6 +33,38 @@ module Pikuri
|
|
|
33
33
|
# +execute+ Proc follows the same convention for its own recoverable failures
|
|
34
34
|
# and lets bugs raise.
|
|
35
35
|
#
|
|
36
|
+
# == Display lines
|
|
37
|
+
#
|
|
38
|
+
# A chrome shows one call as three short strings it styles, caps and defangs
|
|
39
|
+
# but never composes:
|
|
40
|
+
#
|
|
41
|
+
# Write(lib/shared/config.rb)
|
|
42
|
+
# Added 2 lines, removed 3 lines
|
|
43
|
+
#
|
|
44
|
+
# The tool owns all three, because at +execute+ time it still holds the
|
|
45
|
+
# structure it is about to flatten for the model — 23 result structs, a line
|
|
46
|
+
# count, an exit status — which no renderer can recover from the Markdown it
|
|
47
|
+
# gets. {#display_name} and {#describe_call} answer the call side;
|
|
48
|
+
# {Result#summary} answers the result side. Each default is mechanical
|
|
49
|
+
# ({.display_name_for}, the first required parameter, {.describe_content}), so
|
|
50
|
+
# a tool declaring nothing — every MCP tool, every third-party +Tool+ — still
|
|
51
|
+
# renders.
|
|
52
|
+
#
|
|
53
|
+
# Never the *model*: a narrated status line is steerable through a fetched
|
|
54
|
+
# page. {Result} carries the two rules a summary obeys.
|
|
55
|
+
#
|
|
56
|
+
# == One return type
|
|
57
|
+
#
|
|
58
|
+
# An +execute+ returns a {Result}, always — the observation plus its display
|
|
59
|
+
# line, with {Result.error} for a recoverable failure. {#run} enforces it,
|
|
60
|
+
# wrapping a bare String from a third-party +Tool+ rather than refusing it.
|
|
61
|
+
#
|
|
62
|
+
# There is no second success shape to choose between: an *attachment*
|
|
63
|
+
# observation (the image {Pikuri::Workspace::Read} answers for a PNG) is a
|
|
64
|
+
# +Result+ with non-empty {Result#attachments}, and the sole place that
|
|
65
|
+
# distinction is visible is the four-line wrapper in
|
|
66
|
+
# {#to_ruby_llm_tool}, which no tool reads.
|
|
67
|
+
#
|
|
36
68
|
# == Sharing: may one instance serve two agents?
|
|
37
69
|
#
|
|
38
70
|
# {Pikuri::Agent} is thread-unsafe, so a host running ten agents in one VM
|
|
@@ -44,11 +76,11 @@ module Pikuri
|
|
|
44
76
|
# * *P_stateless* — no mutable state. Share freely.
|
|
45
77
|
# * *P_shared_locked* — process-wide mutable state under a lock. Sharing is
|
|
46
78
|
# intended, and for anything pacing a shared *external* resource it is
|
|
47
|
-
# mandatory: a per-agent
|
|
79
|
+
# mandatory: a per-agent rate limiter (pikuri-web's search engines) would let ten agents fire
|
|
48
80
|
# ten simultaneous requests from one IP and earn the ban it exists to
|
|
49
81
|
# avoid.
|
|
50
82
|
# * *P_shared_benign* — unprotected process-wide state whose race is
|
|
51
|
-
# harmless; the doc names the race (
|
|
83
|
+
# harmless; the doc names the race (pikuri-web's on-disk URL cache: both callers
|
|
52
84
|
# compute a cold key and write identical bytes).
|
|
53
85
|
# * *P_one_agent* — agent-scoped state, so exactly one agent. It needs no
|
|
54
86
|
# lock because its only caller is that agent, whose calls are already
|
|
@@ -58,8 +90,8 @@ module Pikuri
|
|
|
58
90
|
#
|
|
59
91
|
# +P_one_agent+ is a fine answer, not a defect: most of what a tool knows is
|
|
60
92
|
# one conversation's business. Nothing enforces it, so the doc *is* the
|
|
61
|
-
# contract. The two axes stay independent — a
|
|
62
|
-
#
|
|
93
|
+
# contract. The two axes stay independent — a tool can take a lock *and* hold
|
|
94
|
+
# per-agent state, so "thread-safe" is no licence to share.
|
|
63
95
|
#
|
|
64
96
|
# A +Tool+ is a value object holding a +Proc+, so its posture is its
|
|
65
97
|
# collaborators': each tool names the one that owns the state, which is also
|
|
@@ -103,10 +135,7 @@ module Pikuri
|
|
|
103
135
|
attr_reader :parameters
|
|
104
136
|
|
|
105
137
|
# @return [Proc] callable invoked with validated keyword arguments,
|
|
106
|
-
# returning the observation —
|
|
107
|
-
# with attachments for multimodal observations (e.g.
|
|
108
|
-
# {Pikuri::Workspace::Read} on a PNG), which +RubyLLM::Chat+ turns into
|
|
109
|
-
# the right image/document blocks.
|
|
138
|
+
# returning the observation as a {Result} — see +== One return type+.
|
|
110
139
|
attr_reader :execute
|
|
111
140
|
|
|
112
141
|
# @return [Tool::TrifectaLegs] which lethal-trifecta legs this tool
|
|
@@ -118,8 +147,8 @@ module Pikuri
|
|
|
118
147
|
# to decide when to call the tool
|
|
119
148
|
# @param parameters [Tool::Parameters] declared schema
|
|
120
149
|
# @param execute [Proc] callable invoked with validated keyword arguments,
|
|
121
|
-
# returning a
|
|
122
|
-
#
|
|
150
|
+
# returning a {Result} (see {#execute}). Recoverable failures answer
|
|
151
|
+
# {Result.error} rather than raise.
|
|
123
152
|
# @param trifecta_legs [Tool::TrifectaLegs] legs this tool contributes.
|
|
124
153
|
# Compute them here rather than at a later resolution pass: construction
|
|
125
154
|
# *is* wiring time, since every collaborator that decides a leg (the
|
|
@@ -148,9 +177,193 @@ module Pikuri
|
|
|
148
177
|
# section.
|
|
149
178
|
attr_reader :wants_context
|
|
150
179
|
|
|
180
|
+
# CamelCase display form of a *raw* tool name, for the three cases with no
|
|
181
|
+
# +Tool+ instance to ask: a raw tool from {Agent::Configurator#add_raw_tool}
|
|
182
|
+
# (an MCP server's, which bypasses {Pikuri::Tool}),
|
|
183
|
+
# ruby_llm's unavailable-tool error, a replayed history.
|
|
184
|
+
#
|
|
185
|
+
# Tool.display_name_for('web_search') # => "WebSearch"
|
|
186
|
+
# Tool.display_name_for('openlibrary__search_books') # => "Openlibrary::SearchBooks"
|
|
187
|
+
#
|
|
188
|
+
# +__+ separates an MCP server's name from its tool's, so the halves CamelCase
|
|
189
|
+
# and join with +::+; inside a half any non-alphanumeric run is a word break
|
|
190
|
+
# (an MCP name may carry +-+ or +.+, which ruby_llm sanitizes to +_+).
|
|
191
|
+
#
|
|
192
|
+
# Deterministic beats pretty — +fileindex_search+ becomes +FileindexSearch+
|
|
193
|
+
# and a tool wanting +LSP+ overrides {#display_name}.
|
|
194
|
+
#
|
|
195
|
+
# @param name [String] the function name advertised to the LLM
|
|
196
|
+
# @return [String] display form; +""+ for a blank name
|
|
197
|
+
def self.display_name_for(name)
|
|
198
|
+
name.to_s.split('__').filter_map { |segment|
|
|
199
|
+
words = segment.split(/[^A-Za-z0-9]+/).reject(&:empty?)
|
|
200
|
+
words.map { |w| w[0].upcase + w[1..] }.join unless words.empty?
|
|
201
|
+
}.join('::')
|
|
202
|
+
end
|
|
203
|
+
|
|
204
|
+
# Every supplied argument as +k=v+ — the display line for a tool whose
|
|
205
|
+
# {Parameters} are unknown (an MCP tool, a replayed call) or which declares
|
|
206
|
+
# no required parameter.
|
|
207
|
+
#
|
|
208
|
+
# Tool.describe_arguments('from' => 'bob', 'after' => '2026-09')
|
|
209
|
+
# # => "from=bob after=2026-09"
|
|
210
|
+
#
|
|
211
|
+
# @param arguments [Hash] raw tool-call arguments
|
|
212
|
+
# @return [String] one line; +""+ for no arguments or a non-Hash
|
|
213
|
+
def self.describe_arguments(arguments)
|
|
214
|
+
return '' unless arguments.is_a?(Hash)
|
|
215
|
+
|
|
216
|
+
one_line(arguments.map { |k, v| "#{k}=#{describe_value(v)}" }.join(' '))
|
|
217
|
+
end
|
|
218
|
+
|
|
219
|
+
# Generic structural summary of an observation — the result line for a tool
|
|
220
|
+
# that returned a bare String rather than a {Result}.
|
|
221
|
+
#
|
|
222
|
+
# Tool.describe_content("a\nb\nc") # => "Returned 3 lines"
|
|
223
|
+
# Tool.describe_content('Error: no such file') # => "Error: no such file"
|
|
224
|
+
#
|
|
225
|
+
# An +"Error: ..."+ observation shows its own first line, because that *is*
|
|
226
|
+
# the status the reader needs. ruby_llm's unavailable-tool +Hash+ passes its
|
|
227
|
+
# +:error+ through the same way.
|
|
228
|
+
#
|
|
229
|
+
# @param content [String, Array<String, RubyLLM::Attachment>, Hash]
|
|
230
|
+
# whatever reached +after_tool_result+ — an Array is an attachment
|
|
231
|
+
# observation as {#to_ruby_llm_tool} hands it over
|
|
232
|
+
# @return [String] one line
|
|
233
|
+
def self.describe_content(content)
|
|
234
|
+
return one_line(content[:error].to_s) if content.is_a?(Hash) && content[:error]
|
|
235
|
+
return describe_attachments(content) if content.is_a?(Array) && content.any?(RubyLLM::Attachment)
|
|
236
|
+
|
|
237
|
+
text = content.to_s
|
|
238
|
+
return one_line(text.lines.first.to_s) if text.start_with?('Error:')
|
|
239
|
+
|
|
240
|
+
lines = text.lines.size
|
|
241
|
+
lines > 1 ? "Returned #{lines} lines" : "Returned #{text.bytesize} bytes"
|
|
242
|
+
end
|
|
243
|
+
|
|
244
|
+
# Flatten +text+ to one line — every display string a tool composes goes
|
|
245
|
+
# through this, since a summary or an argument spanning two lines would
|
|
246
|
+
# break the one-call-one-line shape every renderer assumes.
|
|
247
|
+
#
|
|
248
|
+
# @param text [String, nil]
|
|
249
|
+
# @return [String] whitespace runs collapsed to single spaces, stripped
|
|
250
|
+
def self.one_line(text)
|
|
251
|
+
text.to_s.gsub(/\s+/, ' ').strip
|
|
252
|
+
end
|
|
253
|
+
|
|
254
|
+
# A count with its noun pluralized — display lines are mostly counting.
|
|
255
|
+
#
|
|
256
|
+
# "Matched #{Tool.pluralize(1, 'file')}" # => "Matched 1 file"
|
|
257
|
+
# "Matched #{Tool.pluralize(7, 'match', 'matches')}" # => "Matched 7 matches"
|
|
258
|
+
#
|
|
259
|
+
# @param number [Integer]
|
|
260
|
+
# @param singular [String]
|
|
261
|
+
# @param plural [String, nil] defaults to +singular+ + +"s"+
|
|
262
|
+
# @return [String]
|
|
263
|
+
def self.pluralize(number, singular, plural = nil)
|
|
264
|
+
number == 1 ? "#{number} #{singular}" : "#{number} #{plural || "#{singular}s"}"
|
|
265
|
+
end
|
|
266
|
+
|
|
267
|
+
# Byte count in the largest unit that keeps it short.
|
|
268
|
+
#
|
|
269
|
+
# Tool.format_bytes(3_162) # => "3.1 kB"
|
|
270
|
+
#
|
|
271
|
+
# @param bytes [Integer]
|
|
272
|
+
# @return [String]
|
|
273
|
+
def self.format_bytes(bytes)
|
|
274
|
+
return "#{bytes} B" if bytes < 1024
|
|
275
|
+
return format('%.1f kB', bytes / 1024.0) if bytes < 1024 * 1024
|
|
276
|
+
|
|
277
|
+
format('%.1f MB', bytes / (1024.0 * 1024))
|
|
278
|
+
end
|
|
279
|
+
|
|
280
|
+
# @param value [String, Numeric, Boolean, Array, nil] one argument value,
|
|
281
|
+
# as ruby_llm parsed it out of the model's JSON
|
|
282
|
+
# @return [String] +to_s+, except an Array, which joins with +", "+ so a
|
|
283
|
+
# list argument reads as a list rather than as +["a", "b"]+
|
|
284
|
+
def self.describe_value(value)
|
|
285
|
+
value.is_a?(Array) ? value.join(', ') : value.to_s
|
|
286
|
+
end
|
|
287
|
+
|
|
288
|
+
# @param parts [Array<String, RubyLLM::Attachment>] holding at least one
|
|
289
|
+
# attachment
|
|
290
|
+
# @return [String] +"Returned image/png, 40.2 kB"+, or the mime alone when
|
|
291
|
+
# the size isn't free
|
|
292
|
+
def self.describe_attachments(parts)
|
|
293
|
+
attachment = parts.find { |p| p.is_a?(RubyLLM::Attachment) }
|
|
294
|
+
|
|
295
|
+
size = attachment_bytesize(attachment)
|
|
296
|
+
size ? "Returned #{attachment.mime_type}, #{format_bytes(size)}" : "Returned #{attachment.mime_type}"
|
|
297
|
+
end
|
|
298
|
+
private_class_method :describe_attachments
|
|
299
|
+
|
|
300
|
+
# @param attachment [RubyLLM::Attachment]
|
|
301
|
+
# @return [Integer, nil] the attachment's size, or +nil+ when reading it
|
|
302
|
+
# would cost more than a display line is worth
|
|
303
|
+
def self.attachment_bytesize(attachment)
|
|
304
|
+
# +Attachment#content+ fetches a URL-backed source over the network — a
|
|
305
|
+
# display line must never do that, and no test would catch it.
|
|
306
|
+
return File.size(attachment.source.to_s) if attachment.path?
|
|
307
|
+
return attachment.content&.bytesize if attachment.io_like?
|
|
308
|
+
|
|
309
|
+
nil
|
|
310
|
+
rescue SystemCallError
|
|
311
|
+
nil
|
|
312
|
+
end
|
|
313
|
+
private_class_method :attachment_bytesize
|
|
314
|
+
|
|
315
|
+
# This tool's name as a chrome shows it — {.display_name_for} of {#name}.
|
|
316
|
+
# Override where the mechanical form misreads it:
|
|
317
|
+
#
|
|
318
|
+
# class LspTool < Pikuri::Tool
|
|
319
|
+
# def display_name = 'LSP'
|
|
320
|
+
# end
|
|
321
|
+
#
|
|
322
|
+
# @return [String]
|
|
323
|
+
def display_name
|
|
324
|
+
Tool.display_name_for(@name)
|
|
325
|
+
end
|
|
326
|
+
|
|
327
|
+
# The one argument worth showing beside {#display_name} — by default the
|
|
328
|
+
# value of the first *required* parameter, which is the primary argument for
|
|
329
|
+
# most tools (+path+ for read/write/edit, +query+ for web_search, +command+
|
|
330
|
+
# for bash):
|
|
331
|
+
#
|
|
332
|
+
# read.describe_call('path' => 'lib/code/app.rb') # => "lib/code/app.rb"
|
|
333
|
+
# # → Read(lib/code/app.rb)
|
|
334
|
+
#
|
|
335
|
+
# Override when that parameter is the wrong one to show — an enum, an
|
|
336
|
+
# integer id, a whole Markdown plan:
|
|
337
|
+
#
|
|
338
|
+
# def describe_call(arguments)
|
|
339
|
+
# Tool.one_line("#{arguments['operation']} #{arguments['symbol']}")
|
|
340
|
+
# end
|
|
341
|
+
#
|
|
342
|
+
# Runs on the *unvalidated* arguments ruby_llm parsed from the model's JSON,
|
|
343
|
+
# before +execute+, so an override tolerates a missing or wrong-typed value.
|
|
344
|
+
# Neither capped nor sanitized here: only the renderer knows its width, and
|
|
345
|
+
# defanging is its job too.
|
|
346
|
+
#
|
|
347
|
+
# @param arguments [Hash] raw tool-call arguments; keys String or Symbol
|
|
348
|
+
# @return [String] one line; +""+ renders the call bare (just the display name)
|
|
349
|
+
def describe_call(arguments)
|
|
350
|
+
key = @parameters.required.first
|
|
351
|
+
return Tool.describe_arguments(arguments) if key.nil? || !arguments.is_a?(Hash)
|
|
352
|
+
|
|
353
|
+
value = arguments.key?(key) ? arguments[key] : arguments[key.to_sym]
|
|
354
|
+
return Tool.describe_arguments(arguments) if value.nil?
|
|
355
|
+
|
|
356
|
+
Tool.one_line(Tool.describe_value(value))
|
|
357
|
+
end
|
|
358
|
+
|
|
359
|
+
# The display line for an observation this tool returned as a bare String —
|
|
151
360
|
# Validate +args+ against {#parameters} and forward them as kwargs to
|
|
152
|
-
# {#execute}. Validation failures come back as
|
|
153
|
-
# for the next observation; everything else bubbles up.
|
|
361
|
+
# {#execute}, always answering a {Result}. Validation failures come back as
|
|
362
|
+
# {Result.error} for the next observation; everything else bubbles up.
|
|
363
|
+
#
|
|
364
|
+
# A bare String from +execute+ is wrapped here, with
|
|
365
|
+
# {.describe_content}'s generic display line — that is the floor a
|
|
366
|
+
# third-party +Tool+ subclass lands on, not a shape pikuri's own tools use.
|
|
154
367
|
#
|
|
155
368
|
# @param args [Hash] raw arguments supplied by the LLM
|
|
156
369
|
# @param context [ExecuteContext] this invocation's environment, forwarded
|
|
@@ -160,30 +373,70 @@ module Pikuri
|
|
|
160
373
|
# method *any* keyword and Ruby 3 re-reads the bare hash in
|
|
161
374
|
# +run('text' => 'hi')+ as keywords, so +args+ arrives empty at every
|
|
162
375
|
# existing call site.
|
|
163
|
-
# @return [
|
|
164
|
-
# always +"Error: ..."+; success is whatever +execute+ returns.
|
|
376
|
+
# @return [Result] tool observation.
|
|
165
377
|
def run(args, context = ExecuteContext.default)
|
|
166
378
|
validated = @parameters.validate(args)
|
|
167
|
-
if @wants_context
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
379
|
+
raw = if @wants_context
|
|
380
|
+
@execute.call(**validated, context: context)
|
|
381
|
+
else
|
|
382
|
+
@execute.call(**validated)
|
|
383
|
+
end
|
|
384
|
+
raw.is_a?(Result) ? raw : Result.new(content: raw, summary: Tool.describe_content(raw))
|
|
172
385
|
rescue Tool::Parameters::ValidationError => e
|
|
173
|
-
|
|
386
|
+
Result.error(e.message)
|
|
174
387
|
end
|
|
175
388
|
|
|
176
389
|
# Build a synthetic +RubyLLM::Tool+ subclass wrapping this Tool — what
|
|
177
|
-
# +RubyLLM::Chat#
|
|
390
|
+
# +RubyLLM::Chat#with_tools+ accepts. ruby_llm instantiates it and routes
|
|
178
391
|
# tool calls through +#execute(**args)+, which delegates to {#run}.
|
|
179
392
|
#
|
|
180
393
|
# A wrapper is per *agent* even when this +Tool+ is shared between several,
|
|
181
394
|
# which is what lets it close over one agent's cancellation token.
|
|
182
395
|
#
|
|
396
|
+
# The wrapper instance answers +#pikuri_tool+ with this Tool, so a holder of
|
|
397
|
+
# ruby_llm's +Chat#tools+ table can get from a called name back to
|
|
398
|
+
# {#display_name} / {#describe_call}.
|
|
399
|
+
#
|
|
400
|
+
# == The one place a Result is unwrapped
|
|
401
|
+
#
|
|
402
|
+
# ruby_llm hands the *same* value to +after_tool_result+ and to the +:tool+
|
|
403
|
+
# message it builds, and sends attachments only for a value that *is* an
|
|
404
|
+
# Array of Strings and +RubyLLM::Attachment+s — a test a {Result} cannot
|
|
405
|
+
# pass. So an attachment Result crosses as +[content, *attachments]+, each
|
|
406
|
+
# {Pikuri::Attachment} converted by {Pikuri::Attachment#to_ruby_llm}, and
|
|
407
|
+
# its display line is derived ({.describe_content}: mime plus size, which
|
|
408
|
+
# is all the structure there is); text keeps the +Result+, which ruby_llm
|
|
409
|
+
# stores as {Result#to_s}, so {Result#summary} reaches the listeners
|
|
410
|
+
# verbatim. That one line below is the whole boundary — {#run} answers a
|
|
411
|
+
# +Result+ either way, and no tool sees this.
|
|
412
|
+
#
|
|
413
|
+
# On the wire, a Chat Completions +:tool+ message is text only, so ruby_llm
|
|
414
|
+
# sends the attachments as a +:user+ message ("Attachments from tool call
|
|
415
|
+
# <id>:") right after the batch's results — never +:system+, so nothing
|
|
416
|
+
# needs fixing here.
|
|
417
|
+
#
|
|
418
|
+
# == An attachment the model can't take
|
|
419
|
+
#
|
|
420
|
+
# Before that, +refusal+ may withhold an attachment — an image a text-only
|
|
421
|
+
# model would answer with HTTP 500, on this request and every later one
|
|
422
|
+
# that replays it. A withheld one becomes a line of +content+ instead, so
|
|
423
|
+
# the model learns why it sees nothing:
|
|
424
|
+
#
|
|
425
|
+
# Read image: shot.png (27731 bytes, image/png)
|
|
426
|
+
#
|
|
427
|
+
# [shot.png not shown: model Qwen3.8-Dense-text takes no vision input]
|
|
428
|
+
#
|
|
429
|
+
# The tool never knows: the model's capabilities are stated on the
|
|
430
|
+
# agent's transport ({Agent::ChatTransport#modalities}), and a tool
|
|
431
|
+
# returning an image need not ask.
|
|
432
|
+
#
|
|
183
433
|
# @param context [ExecuteContext] passed to {#run} on every call; see the
|
|
184
434
|
# +== Cancellation+ section.
|
|
435
|
+
# @param refusal [#call] given each {Pikuri::Attachment}, answers why it
|
|
436
|
+
# must be withheld, or +nil+ to send it. Called per tool call, so it may
|
|
437
|
+
# follow a model switch.
|
|
185
438
|
# @return [Class] anonymous +RubyLLM::Tool+ subclass
|
|
186
|
-
def to_ruby_llm_tool(context: ExecuteContext.default)
|
|
439
|
+
def to_ruby_llm_tool(context: ExecuteContext.default, refusal: ->(_) {})
|
|
187
440
|
pikuri_tool = self
|
|
188
441
|
schema = @parameters.to_openai
|
|
189
442
|
tool_name = @name
|
|
@@ -191,11 +444,32 @@ module Pikuri
|
|
|
191
444
|
|
|
192
445
|
Class.new(RubyLLM::Tool) do
|
|
193
446
|
description(tool_desc)
|
|
194
|
-
|
|
447
|
+
parameters(schema)
|
|
195
448
|
|
|
196
449
|
define_singleton_method(:name) { tool_name }
|
|
197
|
-
define_method(:execute)
|
|
450
|
+
define_method(:execute) do |**args|
|
|
451
|
+
result = Tool.withhold_refused(pikuri_tool.run(args, context), refusal)
|
|
452
|
+
result.attachment? ? [result.content, *result.attachments.map(&:to_ruby_llm)] : result
|
|
453
|
+
end
|
|
454
|
+
define_method(:pikuri_tool) { pikuri_tool }
|
|
198
455
|
end
|
|
199
456
|
end
|
|
457
|
+
|
|
458
|
+
# +result+ without the attachments +refusal+ withholds, each replaced by a
|
|
459
|
+
# note in its content; see {#to_ruby_llm_tool}.
|
|
460
|
+
#
|
|
461
|
+
# @param result [Result]
|
|
462
|
+
# @param refusal [#call] see {#to_ruby_llm_tool}
|
|
463
|
+
# @return [Result] +result+ itself when nothing is withheld
|
|
464
|
+
def self.withhold_refused(result, refusal)
|
|
465
|
+
notes = result.attachments.filter_map do |a|
|
|
466
|
+
reason = refusal.call(a)
|
|
467
|
+
[a, a.withheld_note(reason)] if reason
|
|
468
|
+
end
|
|
469
|
+
return result if notes.empty?
|
|
470
|
+
|
|
471
|
+
result.with(content: [result.content, *notes.map(&:last)].join("\n\n"),
|
|
472
|
+
attachments: result.attachments - notes.map(&:first))
|
|
473
|
+
end
|
|
200
474
|
end
|
|
201
475
|
end
|
|
@@ -9,7 +9,7 @@ module Pikuri
|
|
|
9
9
|
#
|
|
10
10
|
# report = Pikuri::Trifecta.walk(node)
|
|
11
11
|
# report.tree_verdict # => :soft
|
|
12
|
-
# report.worst_path.map(&:label) # => ["
|
|
12
|
+
# report.worst_path.map(&:label) # => ["assistant", "RESEARCHER"]
|
|
13
13
|
# puts report.render # the human-readable map
|
|
14
14
|
#
|
|
15
15
|
# == Implementation details
|
|
@@ -52,10 +52,12 @@ module Pikuri
|
|
|
52
52
|
|
|
53
53
|
# How dangerous *this node* is — the tree's verdict is {#tree_verdict}.
|
|
54
54
|
#
|
|
55
|
-
# +:loud+ needs all three legs at full strength
|
|
56
|
-
#
|
|
57
|
-
#
|
|
58
|
-
#
|
|
55
|
+
# +:loud+ needs all three legs at full strength — hard untrusted, and one
|
|
56
|
+
# tool sending unreviewed bytes where the attacker can read them
|
|
57
|
+
# ({Pikuri::Tool::TrifectaLegs#egress_open}); +:soft+ is any other
|
|
58
|
+
# complete trifecta; +:silent+ is a missing leg. Absence of a warning is
|
|
59
|
+
# not evidence of safety: this reasons about capability presence, not
|
|
60
|
+
# data flow.
|
|
59
61
|
#
|
|
60
62
|
# @return [Symbol] +:silent+, +:soft+ or +:loud+
|
|
61
63
|
# @raise [NoMatchingPatternError] if a lattice level exists that this grid
|
|
@@ -63,15 +65,11 @@ module Pikuri
|
|
|
63
65
|
def verdict
|
|
64
66
|
return :silent unless legs.private && legs.untrusted != :none && legs.egress?
|
|
65
67
|
|
|
66
|
-
case [legs.untrusted, legs.
|
|
67
|
-
in [:hard,
|
|
68
|
-
in [:hard,
|
|
69
|
-
in [:
|
|
70
|
-
in [:
|
|
71
|
-
in [:weakened, :unreviewed, :attacker_reachable] then :soft
|
|
72
|
-
in [:weakened, :unreviewed, :tool_vouched] then :soft
|
|
73
|
-
in [:weakened, :human_reviewed, :attacker_reachable] then :soft
|
|
74
|
-
in [:weakened, :human_reviewed, :tool_vouched] then :soft
|
|
68
|
+
case [legs.untrusted, legs.egress_open]
|
|
69
|
+
in [:hard, true] then :loud
|
|
70
|
+
in [:hard, false] then :soft
|
|
71
|
+
in [:weakened, true] then :soft
|
|
72
|
+
in [:weakened, false] then :soft
|
|
75
73
|
end
|
|
76
74
|
end
|
|
77
75
|
|
|
@@ -79,7 +77,7 @@ module Pikuri
|
|
|
79
77
|
# so the caller can both attribute the finding and read its cell:
|
|
80
78
|
#
|
|
81
79
|
# path = report.worst_path
|
|
82
|
-
# path.map(&:label).join(' -> ') # => "
|
|
80
|
+
# path.map(&:label).join(' -> ') # => "assistant -> RESEARCHER"
|
|
83
81
|
# path.last.legs # the cell that decided the verdict
|
|
84
82
|
#
|
|
85
83
|
# Ties go to the node encountered first in pre-order — the parent over its
|
|
@@ -103,7 +101,7 @@ module Pikuri
|
|
|
103
101
|
#
|
|
104
102
|
# Trifecta: soft
|
|
105
103
|
#
|
|
106
|
-
#
|
|
104
|
+
# assistant [:private, :untrusted_hard, :egress_reviewed]
|
|
107
105
|
# mail_compose [:private, :egress_reviewed]
|
|
108
106
|
# calculator []
|
|
109
107
|
# RESEARCHER [gate: human_reviewed] [:untrusted_hard, :egress]
|
|
@@ -126,8 +124,8 @@ module Pikuri
|
|
|
126
124
|
# tree, and because it is the half that carries *meaning* — the map
|
|
127
125
|
# deliberately carries only facts.
|
|
128
126
|
#
|
|
129
|
-
# [TRIFECTA: HARD]
|
|
130
|
-
#
|
|
127
|
+
# [TRIFECTA: HARD] assistant — private(read) + untrusted(fetch) +
|
|
128
|
+
# egress(fetch). An injection in what this agent reads can drive
|
|
131
129
|
# an exfiltration. Break a leg: sever egress (a network-off sandbox), or
|
|
132
130
|
# privilege-separate the step that reads untrusted content.
|
|
133
131
|
# See book/trifecta-detector.md in this repo.
|
|
@@ -204,24 +202,24 @@ module Pikuri
|
|
|
204
202
|
# @param legs [Pikuri::Tool::TrifectaLegs]
|
|
205
203
|
# @return [String]
|
|
206
204
|
def advice(legs)
|
|
207
|
-
#
|
|
208
|
-
# not: it
|
|
209
|
-
#
|
|
210
|
-
#
|
|
211
|
-
if legs.egress_destination == :tool_vouched
|
|
212
|
-
return 'sever egress outright — bytes still leave, they merely reach a destination the ' \
|
|
213
|
-
'
|
|
205
|
+
# An unreviewed leak to a vouched destination is fragile in a way the
|
|
206
|
+
# other attenuations are not: it is soft only while no tool beside it
|
|
207
|
+
# both skips review and reaches the attacker. Say so, rather than let
|
|
208
|
+
# the soft verdict read as settled.
|
|
209
|
+
if !legs.egress_open && (legs.egress_payload_review == :unreviewed || legs.egress_destination == :tool_vouched)
|
|
210
|
+
return 'sever egress outright — bytes still leave, they merely reach a destination the attacker ' \
|
|
211
|
+
'cannot read back, and one unreviewed attacker-reachable tool re-hardens this node'
|
|
214
212
|
end
|
|
215
213
|
|
|
216
|
-
case [legs.untrusted, legs.
|
|
217
|
-
in [:hard,
|
|
214
|
+
case [legs.untrusted, legs.egress_open]
|
|
215
|
+
in [:hard, true]
|
|
218
216
|
'sever egress (a network-off sandbox), or privilege-separate the step that reads untrusted content'
|
|
219
|
-
in [:hard,
|
|
217
|
+
in [:hard, false]
|
|
220
218
|
'privilege-separate the step that reads untrusted content, or declare the workspace trusted ' \
|
|
221
219
|
'if you vouch for every byte it can reach'
|
|
222
|
-
in [:weakened,
|
|
220
|
+
in [:weakened, true]
|
|
223
221
|
'sever egress — the untrusted leg is already attenuated by delegation'
|
|
224
|
-
in [:weakened,
|
|
222
|
+
in [:weakened, false]
|
|
225
223
|
'both legs are already attenuated; narrow what counts as private, or drop a leg outright'
|
|
226
224
|
end
|
|
227
225
|
end
|
data/lib/pikuri/trifecta.rb
CHANGED
|
@@ -47,8 +47,7 @@ module Pikuri
|
|
|
47
47
|
# extension contributes ({Pikuri::Agent::Extension#trifecta_contribution}
|
|
48
48
|
# — legs no tool can declare, and a child per sub-agent persona).
|
|
49
49
|
#
|
|
50
|
-
# @param agent [Pikuri::Agent] a
|
|
51
|
-
# dynamically-added tools are present)
|
|
50
|
+
# @param agent [Pikuri::Agent] a fully built agent
|
|
52
51
|
# @param label [String] name for the root node; defaults to the running
|
|
53
52
|
# program, which is what a host wants in a boot banner
|
|
54
53
|
# @return [Node]
|
data/lib/pikuri/version.rb
CHANGED
data/lib/pikuri-core.rb
CHANGED
|
@@ -20,16 +20,14 @@ require_relative 'pikuri/version'
|
|
|
20
20
|
#
|
|
21
21
|
# == Why eager-load
|
|
22
22
|
#
|
|
23
|
-
# The
|
|
24
|
-
#
|
|
25
|
-
#
|
|
26
|
-
#
|
|
27
|
-
# per-file +require+. (web_search is host-configured via
|
|
28
|
-
# {Tool::WebSearch.build}, so it's not a value constant.) Cost: a few ms.
|
|
23
|
+
# The bundled {Tool::CALCULATOR} is an +ALL_CAPS+ value constant, and Zeitwerk
|
|
24
|
+
# only auto-loads constants matching its filename↔CamelCase convention.
|
|
25
|
+
# Eager-loading runs the file defining it so a bin script can +c.add_tool+ it
|
|
26
|
+
# without a per-file +require+. Cost: a few ms.
|
|
29
27
|
module Pikuri
|
|
30
28
|
# Search path for bundled system prompts. Mutable: each pikuri gem appends its
|
|
31
29
|
# own +prompts/+ at boot, so +Pikuri.prompt(name)+ from a host requiring
|
|
32
|
-
# +pikuri-
|
|
30
|
+
# +pikuri-subagents+ finds its persona prompts there. Public so a downstream
|
|
33
31
|
# user can read pikuri's prompts as a starting point; prefer {.prompt}.
|
|
34
32
|
#
|
|
35
33
|
# @return [Array<String>]
|
|
@@ -148,10 +146,6 @@ module Pikuri
|
|
|
148
146
|
# from a spec), kept off the production load path — so don't autoload or
|
|
149
147
|
# eager-load it. See {Pikuri::Testing}.
|
|
150
148
|
Loader.ignore(File.expand_path('pikuri/testing.rb', __dir__))
|
|
151
|
-
Loader.inflector.inflect(
|
|
152
|
-
'html' => 'HTML',
|
|
153
|
-
'duckduckgo' => 'DuckDuckGo'
|
|
154
|
-
)
|
|
155
149
|
Loader.setup
|
|
156
150
|
Loader.eager_load
|
|
157
151
|
|