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.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +16 -29
  3. data/lib/pikuri/agent/chat_transport.rb +114 -33
  4. data/lib/pikuri/agent/configurator.rb +191 -110
  5. data/lib/pikuri/agent/control/cancellable.rb +25 -16
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +87 -120
  8. data/lib/pikuri/agent/control.rb +9 -11
  9. data/lib/pikuri/agent/event.rb +73 -61
  10. data/lib/pikuri/agent/extension.rb +45 -81
  11. data/lib/pikuri/agent/history.rb +91 -497
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +115 -108
  14. data/lib/pikuri/agent/listener/token_log.rb +21 -55
  15. data/lib/pikuri/agent/listener.rb +4 -4
  16. data/lib/pikuri/agent/listener_list.rb +19 -13
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +624 -448
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/extractor/passthrough.rb +5 -2
  21. data/lib/pikuri/extractor.rb +43 -12
  22. data/lib/pikuri/file_type.rb +4 -4
  23. data/lib/pikuri/finalizers.rb +2 -2
  24. data/lib/pikuri/paths.rb +1 -1
  25. data/lib/pikuri/sanitizer.rb +4 -3
  26. data/lib/pikuri/subprocess.rb +17 -5
  27. data/lib/pikuri/testing.rb +122 -49
  28. data/lib/pikuri/tool/calculator.rb +134 -30
  29. data/lib/pikuri/tool/execute_context.rb +2 -2
  30. data/lib/pikuri/tool/parameters.rb +10 -0
  31. data/lib/pikuri/tool/result.rb +164 -0
  32. data/lib/pikuri/tool/trifecta_legs.rb +52 -21
  33. data/lib/pikuri/tool.rb +298 -24
  34. data/lib/pikuri/trifecta/report.rb +28 -30
  35. data/lib/pikuri/trifecta.rb +1 -2
  36. data/lib/pikuri/version.rb +1 -1
  37. data/lib/pikuri-core.rb +5 -11
  38. metadata +16 -73
  39. data/lib/pikuri/agent/context_window_detector.rb +0 -181
  40. data/lib/pikuri/agent/control/step_limit.rb +0 -95
  41. data/lib/pikuri/agent/extension_context.rb +0 -120
  42. data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
  43. data/lib/pikuri/agent/synthesizer.rb +0 -129
  44. data/lib/pikuri/extractor/html.rb +0 -256
  45. data/lib/pikuri/ruby_llm_patches.rb +0 -106
  46. data/lib/pikuri/tool/fetch.rb +0 -146
  47. data/lib/pikuri/tool/scraper.rb +0 -144
  48. data/lib/pikuri/tool/search/brave.rb +0 -170
  49. data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
  50. data/lib/pikuri/tool/search/engines.rb +0 -319
  51. data/lib/pikuri/tool/search/exa.rb +0 -195
  52. data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
  53. data/lib/pikuri/tool/search/result.rb +0 -24
  54. data/lib/pikuri/tool/web_scrape.rb +0 -105
  55. data/lib/pikuri/tool/web_search.rb +0 -133
  56. 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 {Search::RateLimiter} would let ten agents fire
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 ({Pikuri::UrlCache}: both callers
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 {Skill::Activation} locks *and*
62
- # is per-agent, so "thread-safe" is no licence to share.
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 — usually a +String+, or a +RubyLLM::Content+
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 +String+ or +RubyLLM::Content+ (see {#execute}). Recoverable
122
- # failures return +"Error: <message>"+ rather than raise.
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 +"Error: <message>"+ Strings
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 [String, RubyLLM::Content] tool observation — validation failures
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
- @execute.call(**validated, context: context)
169
- else
170
- @execute.call(**validated)
171
- end
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
- "Error: #{e.message}"
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#with_tool+ accepts. ruby_llm instantiates it and routes
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
- params(schema)
447
+ parameters(schema)
195
448
 
196
449
  define_singleton_method(:name) { tool_name }
197
- define_method(:execute) { |**args| pikuri_tool.run(args, context) }
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) # => ["pikuri-computer", "RESEARCHER"]
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; +:soft+ is any complete
56
- # trifecta whose untrusted or egress leg is attenuated; +:silent+ is a
57
- # missing leg. Absence of a warning is not evidence of safety: this
58
- # reasons about capability presence, not data flow.
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.egress_payload_review, legs.egress_destination]
67
- in [:hard, :unreviewed, :attacker_reachable] then :loud
68
- in [:hard, :unreviewed, :tool_vouched] then :soft
69
- in [:hard, :human_reviewed, :attacker_reachable] then :soft
70
- in [:hard, :human_reviewed, :tool_vouched] then :soft
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(' -> ') # => "pikuri-computer -> RESEARCHER"
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
- # pikuri-computer [:private, :untrusted_hard, :egress_reviewed]
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] pikuri-code — private(read, bash) + untrusted(read,
130
- # bash) + egress(bash). An injection in what this agent reads can drive
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
- # A vouched destination is fragile in a way the other attenuations are
208
- # not: it survives only while it is the *sole* egress leg, since the
209
- # union hardens the whole node the moment one attacker-reachable tool
210
- # joins it. Say so, rather than let the soft verdict read as settled.
211
- if legs.egress_destination == :tool_vouched
212
- return 'sever egress outright — bytes still leave, they merely reach a destination the ' \
213
- 'attacker cannot read back, and one attacker-reachable tool re-hardens this node'
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.egress_payload_review]
217
- in [:hard, :unreviewed]
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, :unreviewed]
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
@@ -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 *wired* agent (after the bind sweep, so
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]
@@ -6,5 +6,5 @@ module Pikuri
6
6
  # additions to the public surface (+Pikuri::Tool+ / +Pikuri::Agent+ /
7
7
  # listeners / bundled tools), major for breaking changes to that
8
8
  # surface or to the +bin/pikuri-*+ CLIs.
9
- VERSION = '0.1.0'
9
+ VERSION = '0.2.0'
10
10
  end
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 stateless bundled tools (+Tool::CALCULATOR+, +Tool::WEB_SCRAPE+,
24
- # +Tool::FETCH+) are +ALL_CAPS+ value constants, and Zeitwerk only auto-loads
25
- # constants matching its filename↔CamelCase convention. Eager-loading runs the
26
- # files defining those values so a bin script can +c.add_tool+ them without
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-code+ finds +coding-system-prompt.txt+ there. Public so a downstream
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