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
@@ -3,27 +3,69 @@
3
3
  module Pikuri
4
4
  class Tool
5
5
  # Evaluates a basic arithmetic expression with Python operator syntax and
6
- # semantics, via the hand-rolled recursive-descent {Parser} below.
6
+ # semantics, via the hand-rolled recursive-descent {Parser} below. A
7
+ # great-circle distance, the call that motivated {FUNCTIONS}:
8
+ #
9
+ # Calculator.calculate('6371 * acos(sin(radians(60.1699)) * sin(radians(41.3874)) + ' \
10
+ # 'cos(radians(60.1699)) * cos(radians(41.3874)) * ' \
11
+ # 'cos(radians(2.1734) - radians(24.9410)))') # => "2603.339"
12
+ #
13
+ # Scope is intentionally narrow: operators (+, -, *, /, //, %, **), unary
14
+ # minus, parentheses, numeric literals, and the fixed-arity real functions
15
+ # and constants in {FUNCTIONS} / {CONSTANTS}. No variables, sequences,
16
+ # assignment or comparisons — every name is spelled the way Python spells
17
+ # it rather than as a pikuri dialect. See +design/decisions.md+
18
+ # +D_calculator_functions+.
7
19
  #
8
20
  # Hand-rolled rather than a gem: the previous backend (dentaku) pulled in
9
21
  # concurrent-ruby (~16k lines — pikuri's single heaviest audit item) plus
10
- # bigdecimal and tsort just for four-function arithmetic. The ~100 lines
11
- # here implement Python's grammar directly, which also retires the old
22
+ # bigdecimal and tsort just for four-function arithmetic. The parser here
23
+ # implements Python's grammar directly, which also retires the old
12
24
  # +**+→+^+ preprocessing (the model's native syntax is now the grammar).
13
- #
14
- # Scope is intentionally narrow: operators (+, -, *, /, //, %, **), unary
15
- # minus, parentheses, and integer/decimal/e-notation literals. No variables,
16
- # functions, or booleans — those would teach the model a dialect.
17
25
  module Calculator
18
26
  # Raised internally for anything {.calculate} should return as an
19
- # +"Error: ..."+ observation rather than crash the loop: parse failures,
20
- # division by zero, complex or non-finite results. Names the offending
21
- # token/operands.
27
+ # +"Error: ..."+ observation rather than crash the loop. Names the
28
+ # offending token, operands or call.
22
29
  class Error < StandardError; end
23
30
 
31
+ # The callable names, as +name => [permitted argument counts, callable]+.
32
+ # Every entry is pure, fixed-arity and real→real: that shape *is* the
33
+ # closed surface, so a new entry has to fit it. Trigonometry is in
34
+ # radians, as Python's is — +radians+ / +degrees+ are here because the
35
+ # conversion is otherwise unexpressible, and a model that feeds degrees
36
+ # to +sin+ gets a plausible wrong answer rather than an error.
37
+ #
38
+ # @return [Hash{String => Array(Range, #call)}]
39
+ FUNCTIONS = {
40
+ 'sin' => [1..1, Math.method(:sin)],
41
+ 'cos' => [1..1, Math.method(:cos)],
42
+ 'tan' => [1..1, Math.method(:tan)],
43
+ 'asin' => [1..1, Math.method(:asin)],
44
+ 'acos' => [1..1, Math.method(:acos)],
45
+ 'atan' => [1..1, Math.method(:atan)],
46
+ 'atan2' => [2..2, Math.method(:atan2)],
47
+ 'hypot' => [2..2, Math.method(:hypot)],
48
+ 'sqrt' => [1..1, Math.method(:sqrt)],
49
+ 'exp' => [1..1, Math.method(:exp)],
50
+ 'log' => [1..2, Math.method(:log)], # log(x) is natural; log(x, base) is Python's second form
51
+ 'log10' => [1..1, Math.method(:log10)],
52
+ 'log2' => [1..1, Math.method(:log2)],
53
+ 'floor' => [1..1, ->(x) { x.floor }],
54
+ 'ceil' => [1..1, ->(x) { x.ceil }],
55
+ 'abs' => [1..1, ->(x) { x.abs }],
56
+ 'radians' => [1..1, ->(deg) { deg * Math::PI / 180 }],
57
+ 'degrees' => [1..1, ->(rad) { rad * 180 / Math::PI }]
58
+ }.freeze
59
+
60
+ # The names that evaluate to a number with no call syntax.
61
+ #
62
+ # @return [Hash{String => Float}]
63
+ CONSTANTS = { 'pi' => Math::PI, 'e' => Math::E }.freeze
64
+
24
65
  # Evaluate +expression+ and return the result as a String. Parse and
25
66
  # arithmetic failures (division by zero, overflow to infinity, complex
26
- # results) come back as +"Error: ..."+ so the model self-corrects.
67
+ # results, a function outside its domain) come back as +"Error: ..."+ so
68
+ # the model self-corrects.
27
69
  #
28
70
  # @param expression [String] Python-syntax arithmetic expression
29
71
  # @return [String] numeric result, or +"Error: ..."+ on failure
@@ -55,7 +97,8 @@ module Pikuri
55
97
  # multiplicative := unary (('*' | '/' | '//' | '%') unary)*
56
98
  # unary := ('+' | '-') unary | power
57
99
  # power := atom ('**' unary)?
58
- # atom := NUMBER | '(' additive ')'
100
+ # atom := NUMBER | NAME '(' additive (',' additive)* ')'
101
+ # | NAME | '(' additive ')'
59
102
  #
60
103
  # The +power+→+unary+ recursion on the right operand makes +**+
61
104
  # right-associative (+2**3**2+ is 512) and lets a sign follow it
@@ -66,11 +109,19 @@ module Pikuri
66
109
  # division, +//+ floors, +2**-1+ is Float 0.5 (not a Rational), and a
67
110
  # negative base under a fractional exponent is rejected (not a Complex).
68
111
  class Parser
69
- # One number or operator. +**+/+//+ listed before their single-char
70
- # prefixes so the two-char operators win; number literals cover +42+,
71
- # +4.2+, +5.+, +.5+, and e-notation. +\G+ anchors each match at the scan
72
- # position so nothing between tokens is missed.
73
- TOKEN_RE = %r{\G\s*(\*\*|//|\d+(?:\.\d*)?(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?|[-+*/%()])}
112
+ # One number, name or operator. +**+/+//+ listed before their
113
+ # single-char prefixes so the two-char operators win; number literals
114
+ # cover +42+, +4.2+, +5.+, +.5+, and e-notation; a name carries an
115
+ # optional +math.+ / +Math.+ qualifier as part of the token, so
116
+ # +math.cos+ and a bare +cos+ both parse. +\G+ anchors each match at
117
+ # the scan position so nothing between tokens is missed.
118
+ TOKEN_RE = %r{\G\s*(\*\*|//|\d+(?:\.\d*)?(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?|(?:[Mm]ath\.)?[A-Za-z_]\w*|[-+*/%(),])}
119
+
120
+ # Tail of every unknown-name error: the tool description lists the same
121
+ # set, but a small model recovers from the error string on the next
122
+ # turn instead of guessing a second name.
123
+ AVAILABLE = "available functions: #{FUNCTIONS.keys.join(', ')}; " \
124
+ "constants: #{CONSTANTS.keys.join(', ')}"
74
125
 
75
126
  # @param expression [String] raw expression as the model wrote it
76
127
  # @raise [Error] when +expression+ contains a character no token matches
@@ -142,13 +193,16 @@ module Pikuri
142
193
  def atom
143
194
  return parenthesized if accept('(')
144
195
 
145
- token = peek
146
- unless token&.match?(/\A[.\d]/)
147
- raise Error, token ? "unexpected #{token.inspect}" : 'unexpected end of expression'
196
+ case (token = peek)
197
+ when nil then raise Error, 'unexpected end of expression'
198
+ when /\A[.\d]/
199
+ @pos += 1
200
+ token.match?(/[.eE]/) ? token.to_f : token.to_i
201
+ when /\A[A-Za-z_]/
202
+ @pos += 1
203
+ named(token)
204
+ else raise Error, "unexpected #{token.inspect}"
148
205
  end
149
-
150
- @pos += 1
151
- token.match?(/[.eE]/) ? token.to_f : token.to_i
152
206
  end
153
207
 
154
208
  def parenthesized
@@ -158,6 +212,42 @@ module Pikuri
158
212
  value
159
213
  end
160
214
 
215
+ # A function call if a +(+ follows, a constant otherwise.
216
+ def named(token)
217
+ name = token.sub(/\A[Mm]ath\./, '')
218
+ return apply_function(name, arguments) if accept('(')
219
+ return CONSTANTS[name] if CONSTANTS.key?(name)
220
+ raise Error, "#{name} takes arguments; write #{name}(x)" if FUNCTIONS.key?(name)
221
+
222
+ raise Error, "unknown name #{token.inspect}; #{AVAILABLE}"
223
+ end
224
+
225
+ # The argument list of a call, positioned just past the opening +(+.
226
+ #
227
+ # @return [Array<Integer, Float>] one or more evaluated arguments
228
+ def arguments
229
+ args = [additive]
230
+ args << additive while accept(',')
231
+ raise Error, 'missing closing parenthesis' unless accept(')')
232
+
233
+ args
234
+ end
235
+
236
+ # +Math+ raises +DomainError+ where Python's +math+ raises +ValueError+
237
+ # (+acos(1.0000000001)+, reachable from real haversine rounding), and
238
+ # +floor+/+ceil+ raise +FloatDomainError+ on an infinite argument.
239
+ # Both are the model's error to see, not the loop's to die on.
240
+ def apply_function(name, args)
241
+ arities, callable = FUNCTIONS.fetch(name) { raise Error, "unknown function #{name.inspect}; #{AVAILABLE}" }
242
+ unless arities.cover?(args.size)
243
+ raise Error, "#{name} takes #{arities.to_a.join(' or ')} argument(s), got #{args.size}"
244
+ end
245
+
246
+ callable.call(*args)
247
+ rescue Math::DomainError, FloatDomainError
248
+ raise Error, "#{name}(#{args.join(', ')}) is undefined"
249
+ end
250
+
161
251
  # @return [String, nil] the next token without consuming it
162
252
  def peek
163
253
  @tokens[@pos]
@@ -209,12 +299,13 @@ module Pikuri
209
299
 
210
300
  # Arithmetic-evaluation tool backed by {Tool::Calculator.calculate}. Accepts
211
301
  # Python expression syntax (+, -, *, /, //, %, **, unary minus, parentheses,
212
- # decimals) so the model emits syntax it already knows.
302
+ # decimals) plus {Tool::Calculator::FUNCTIONS} / {Tool::Calculator::CONSTANTS},
303
+ # so the model emits syntax it already knows.
213
304
  #
214
- # Stays wired even in shells that have +bash+: it is the only *unconfirmed*
215
- # float arithmetic there, since a shell's own +$((…))+ is integer-only and
216
- # every interpreter that isn't must stay off the passive allowlist. See
217
- # +DECISIONS.md+ +D_keep_calculator+.
305
+ # Stays wired even beside a shell (pikuri-workshop's): it is the only
306
+ # *unconfirmed* float arithmetic there, since a shell's own +$((…))+ is
307
+ # integer-only and every interpreter that isn't must stay off the passive
308
+ # allowlist. See +design/decisions.md+ +D_keep_calculator+.
218
309
  #
219
310
  # Sharing: +P_stateless+ — arithmetic over the argument, no I/O, no state.
220
311
  # Hand this one constant to every agent in the VM.
@@ -234,9 +325,22 @@ module Pikuri
234
325
  'Arithmetic expression in Python syntax: + - * ' \
235
326
  '/ (true division), // (floor division), % (modulo), ' \
236
327
  '** (exponentiation), unary minus, parentheses, ' \
237
- 'decimals. E.g. "155 / (58 * 1000.0 / 3600)" or "2**10".'
328
+ 'decimals. Also these functions, with or without a ' \
329
+ 'math. prefix: sin cos tan asin acos atan atan2 ' \
330
+ 'hypot sqrt exp log (log(x) natural, log(x, base) ' \
331
+ 'for another base) log10 log2 floor ceil abs ' \
332
+ 'radians degrees, and the constants pi and e. ' \
333
+ 'Trigonometric functions take RADIANS, so convert ' \
334
+ 'degrees first: sin(radians(30)), never sin(30). ' \
335
+ 'E.g. "155 / (58 * 1000.0 / 3600)", "2**10", or ' \
336
+ '"hypot(3, 4)".'
337
+ },
338
+ # The one tool whose display line *is* its observation: the value was
339
+ # computed here, so echoing it is structural rather than an excerpt.
340
+ execute: ->(expression:) {
341
+ value = Calculator.calculate(expression)
342
+ Tool::Result.new(content: value, summary: value)
238
343
  },
239
- execute: ->(expression:) { Calculator.calculate(expression) },
240
344
  # No legs: pure arithmetic over the argument, no I/O of any kind.
241
345
  trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
242
346
  )
@@ -22,8 +22,8 @@ module Pikuri
22
22
  # The obvious shape is +context.args[:query]+, with one object carrying
23
23
  # everything. It loses to a plain fact about {Parameters#validate}: it
24
24
  # returns only the keys the model actually sent and applies no defaults, so
25
- # half the bundled tools declare theirs in the +execute+ signature
26
- # (+max_results: 10+). Fold the arguments in here and every one of those
25
+ # tools declare theirs in the +execute+ signature (+web_search+'s
26
+ # +max_results: 10+). Fold the arguments in here and every one of those
27
27
  # defaults has to be re-expressed. Arguments therefore stay kwargs, and this
28
28
  # object carries only what has no other home.
29
29
  #
@@ -196,6 +196,16 @@ module Pikuri
196
196
  { type: 'object', properties: @properties, required: @required }
197
197
  end
198
198
 
199
+ # @return [Array<Symbol>] every declared property, in declaration order.
200
+ def names
201
+ @properties.keys
202
+ end
203
+
204
+ # @return [Array<String>] the required properties, in declaration order —
205
+ # so +required.first+ is the argument a tool was declared around, which
206
+ # is what {Pikuri::Tool#describe_call} shows.
207
+ attr_reader :required
208
+
199
209
  # Validate a tool-call argument hash against the schema. Returns a
200
210
  # symbol-keyed hash safe to splat as kwargs into a tool's +execute+;
201
211
  # raises {ValidationError} with an LLM-actionable message listing every
@@ -0,0 +1,164 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Pikuri
4
+ class Tool
5
+ # What every {Pikuri::Tool} returns: the observation the model reads, plus
6
+ # the one-line status a chrome renders in its place.
7
+ #
8
+ # hits = cascade.search(query, max_results: max_results)
9
+ # Tool::Result.new(content: render_markdown(hits),
10
+ # summary: "Returned #{hits.size} search results")
11
+ #
12
+ # # → WebSearch(rails 8 credentials)
13
+ # # Returned 23 search results
14
+ #
15
+ # A recoverable failure is a {.error} — the +"Error: ..."+ observation the
16
+ # LLM reacts to, with the message as its own display line:
17
+ #
18
+ # return Tool::Result.error("offset must be >= 1, got #{offset}") if offset < 1
19
+ #
20
+ # == Text or an attachment, and the one rule for choosing
21
+ #
22
+ # +content+ is always the text the model reads. +attachments+ is non-empty
23
+ # only when the observation **is** the attached bytes — the image
24
+ # {Pikuri::Workspace::Read} answers for a PNG, with +content+ a short note:
25
+ #
26
+ # image = Pikuri::Attachment.new(mime: mime, filename: resolved.basename.to_s, bytes: bytes)
27
+ # note = "Read image: #{path} (#{bytes.bytesize} bytes, #{mime})"
28
+ # Tool::Result.new(content: note, attachments: [image], summary: Pikuri::Tool.one_line(note))
29
+ #
30
+ # The test is not "does this tool touch a file" but "is there anything to
31
+ # read here besides the attached bytes"; a PDF is text (extracted, paged,
32
+ # counted), a PNG is not.
33
+ #
34
+ # An attachment's display line is *derived* rather than authored
35
+ # ({Pikuri::Tool.describe_content} answers +"Returned image/png, 27.1 kB"+),
36
+ # because mime and size are the only structure there is — so pass any
37
+ # +summary+ you like and expect the derived one to win. That falls out of
38
+ # how the value crosses into ruby_llm: {Pikuri::Tool#to_ruby_llm_tool}'s
39
+ # wrapper hands an attachment Result over as a +[content, *attachments]+
40
+ # Array, the one shape ruby_llm sends as a multimodal tool message, and its
41
+ # +after_tool_result+ callback then sees that Array, not this Result. Text
42
+ # takes the other branch: ruby_llm receives this +Result+, stores {#to_s},
43
+ # and the listeners get {#summary} verbatim.
44
+ #
45
+ # == The two rules a summary obeys
46
+ #
47
+ # **Structural, never excerpted** — counts, sizes, exit codes; never the
48
+ # first line of the page that was fetched. The user reads this line as
49
+ # *status*, and those bytes are attacker-authorable.
50
+ #
51
+ # **Summaries are code** — computed by the tool's programmer from what the
52
+ # tool counted, never from model output and never from a substring of
53
+ # +content+. A narrated +Saved successfully+ over a failed write is exactly
54
+ # what a prompt injection aims for.
55
+ #
56
+ # Immutable.
57
+ Result = Data.define(:content, :summary, :attachments) do
58
+ # The observation for a failure the LLM can act on — a bad argument, an
59
+ # HTTP 4xx, a refused path. Bugs in pikuri's own code keep raising.
60
+ #
61
+ # Tool::Result.error('no such task id: 7').content # => "Error: no such task id: 7"
62
+ #
63
+ # The message doubles as the display line: an error *is* its own status,
64
+ # which is the one place echoing the content is right. Only its **first
65
+ # line** does, though — a {Parameters::ValidationError} reprints the whole
66
+ # schema for the model to fix, and none of that belongs on a status row.
67
+ #
68
+ # @param message [String] what went wrong, without the +"Error: "+ prefix
69
+ # (already prefixed is fine — it is not doubled). May be multi-line; the
70
+ # model gets all of it.
71
+ # @return [Result]
72
+ def self.error(message)
73
+ text = message.to_s
74
+ text = "Error: #{text}" unless text.start_with?('Error:')
75
+ new(content: text, summary: Tool.one_line(text.lines.first))
76
+ end
77
+
78
+ # The observation for one {Pikuri::Extractor::Page} window — what every
79
+ # line-paged reader answers, so they all share the trailer the model
80
+ # learns to page by:
81
+ #
82
+ # page = Pikuri::Extractor.extract_paged(StringIO.new(text), offset: 3, limit: 2)
83
+ # Tool::Result.page(page).content
84
+ # # => 3 gamma
85
+ # # 4 delta
86
+ # #
87
+ # # (Showing lines 3-4 of 9. Use offset=5 to continue.)
88
+ #
89
+ # A +:pdf+ page words itself as one (+"Showing PDF lines"+, +"End of
90
+ # PDF"+), and an empty one answers the scanned-image hint over
91
+ # +empty_note+. An +offset+ past the end is an {.error}.
92
+ #
93
+ # @param page [Pikuri::Extractor::Page] the window to render.
94
+ # @param name [String] what the document is called in the end-of-document
95
+ # trailer and the past-the-end error, e.g. +"file"+, +"attachment"+.
96
+ # @param empty_note [String] the whole observation for an empty document.
97
+ # @return [Result] summary +"Read 214 lines"+ / +"Read 3 PDF lines"+ for a
98
+ # rendered window.
99
+ def self.page(page, name: 'file', empty_note: "(Empty #{name})")
100
+ pdf = page.kind == :pdf
101
+ what = pdf ? 'PDF' : name
102
+ if page.lines.empty?
103
+ if page.total_lines.zero?
104
+ note = pdf ? '(PDF has no extractable text; likely scanned image content)' : empty_note
105
+ return new(content: note, summary: Tool.one_line(note))
106
+ end
107
+
108
+ return error("offset #{page.start_line} is beyond end of #{what} (#{page.total_lines} lines total)")
109
+ end
110
+
111
+ lines = pdf ? 'PDF lines' : 'lines'
112
+ last = page.start_line + page.lines.length - 1
113
+ body = page.lines.each_with_index.map { |line, i| format("%6d\t%s", i + page.start_line, line) }.join("\n")
114
+ trailer =
115
+ if page.byte_capped
116
+ "(Output capped at #{Extractor::PAGE_MAX_BYTES / 1024} KB. Showing #{lines} " \
117
+ "#{page.start_line}-#{last}. Use offset=#{last + 1} to continue.)"
118
+ elsif page.more
119
+ total = page.total_lines ? " of #{page.total_lines}" : ''
120
+ "(Showing #{lines} #{page.start_line}-#{last}#{total}. Use offset=#{last + 1} to continue.)"
121
+ else
122
+ "(End of #{what} - total #{page.total_lines} lines)"
123
+ end
124
+
125
+ new(content: "#{body}\n\n#{trailer}",
126
+ summary: "Read #{Tool.pluralize(page.lines.length, pdf ? 'PDF line' : 'line')}")
127
+ end
128
+
129
+ # @param content [String] the text the model reads; for an attachment
130
+ # observation, the note beside the bytes.
131
+ # @param summary [String] the display line; see the two rules above.
132
+ # @param attachments [Array<Pikuri::Attachment>] the bytes the
133
+ # observation *is*; see +== Text or an attachment+ above.
134
+ # @raise [ArgumentError] if +content+ is not a String, an attachment is
135
+ # not a {Pikuri::Attachment}, or +summary+ is not a single-line
136
+ # String — all programmer errors in tool code, so they raise rather
137
+ # than degrade.
138
+ def initialize(content:, summary:, attachments: [])
139
+ raise ArgumentError, "content must be a String, got #{content.class}" unless content.is_a?(String)
140
+ unless attachments.all?(Pikuri::Attachment)
141
+ raise ArgumentError, "attachments must be Pikuri::Attachments, got #{attachments.map(&:class)}"
142
+ end
143
+ raise ArgumentError, "summary must be a String, got #{summary.class}" unless summary.is_a?(String)
144
+ raise ArgumentError, "summary must be one line, got #{summary.inspect}" if summary.include?("\n")
145
+
146
+ super(content: content, summary: summary, attachments: attachments.dup.freeze)
147
+ end
148
+
149
+ # Whether the observation carries attached bytes — what decides which
150
+ # value crosses into ruby_llm.
151
+ #
152
+ # @return [Boolean]
153
+ def attachment? = !attachments.empty?
154
+
155
+ # @return [Boolean] whether this is a recoverable failure, i.e. an
156
+ # observation the LLM should try to correct rather than build on.
157
+ def error? = content.start_with?('Error:')
158
+
159
+ # @return [String] {#content} — what ruby_llm stores for a text tool
160
+ # message.
161
+ def to_s = content
162
+ end
163
+ end
164
+ end
@@ -30,6 +30,13 @@ module Pikuri
30
30
  # +:no_egress+ at the bottom and the constructor keeps them coherent, so the
31
31
  # leg is present on both or on neither ({#egress?} is the canonical read).
32
32
  #
33
+ # Unioned, the two axes are each a +max+, which can describe a tool nobody
34
+ # wired: that vouched query beside that reviewed send max out to unreviewed
35
+ # *and* attacker-reachable. Egress is a sink, so bytes leave through one tool
36
+ # and only that tool's own pair decides whether an unreviewed leak reaches a
37
+ # reader. {#egress_open} carries that per-source fact through the union;
38
+ # with the two maxes it pins down exactly which egress shapes a node holds.
39
+ #
33
40
  # Immutable.
34
41
  #
35
42
  # @!attribute [r] private
@@ -58,7 +65,15 @@ module Pikuri
58
65
  # choose the destination, that destination does not republish, and the
59
66
  # request is not attacker-readable in flight or at rest. Unverifiable by
60
67
  # the framework: like +private+, it is a declaration it inherits.
61
- class TrifectaLegs < Data.define(:private, :untrusted, :egress_payload_review, :egress_destination)
68
+ # @!attribute [r] egress_open
69
+ # Answers: does one single source send unreviewed bytes to a destination
70
+ # the attacker can reach? The full-strength egress the loud verdict needs.
71
+ #
72
+ # @return [Boolean] derived for a declaration; after a {#|} it can be
73
+ # +false+ while the two axes read +:unreviewed+ / +:attacker_reachable+,
74
+ # because different tools hold the two.
75
+ class TrifectaLegs < Data.define(:private, :untrusted, :egress_payload_review, :egress_destination,
76
+ :egress_open)
62
77
  # Danger order, least to most: +max+ is union at a node, +min+ is the cap
63
78
  # through a delegation channel.
64
79
  #
@@ -77,11 +92,14 @@ module Pikuri
77
92
  # @param egress_destination [Symbol, nil] one of {EGRESS_DESTINATION_ORDER};
78
93
  # omit to derive — +:no_egress+ without a leg, else the pessimistic
79
94
  # +:attacker_reachable+, so silence never buys the softer grade.
80
- # @raise [ArgumentError] on a level outside its lattice, or on the two
81
- # egress axes disagreeing about whether the leg exists at all — a typo'd
82
- # level would otherwise read as a missing leg, the one failure mode this
83
- # detector exists to refuse.
84
- def initialize(private:, untrusted:, egress_payload_review:, egress_destination: nil)
95
+ # @param egress_open [Boolean, nil] omit to derive from the two axes; only
96
+ # {#|} and +with+ pass it.
97
+ # @raise [ArgumentError] on a level outside its lattice, on the two egress
98
+ # axes disagreeing about whether the leg exists at all — a typo'd level
99
+ # would otherwise read as a missing leg, the one failure mode this
100
+ # detector exists to refuse — or on +egress_open+ claimed where the axes
101
+ # say no source could be.
102
+ def initialize(private:, untrusted:, egress_payload_review:, egress_destination: nil, egress_open: nil)
85
103
  egress_destination ||= egress_payload_review == :no_egress ? :no_egress : :attacker_reachable
86
104
  check!(untrusted, UNTRUSTED_ORDER, 'untrusted')
87
105
  check!(egress_payload_review, EGRESS_REVIEW_ORDER, 'egress review')
@@ -90,29 +108,35 @@ module Pikuri
90
108
  raise ArgumentError, 'egress axes disagree on whether the leg exists: ' \
91
109
  "#{egress_payload_review.inspect} / #{egress_destination.inspect}"
92
110
  end
111
+ could_be_open = egress_payload_review == :unreviewed && egress_destination == :attacker_reachable
112
+ egress_open = could_be_open if egress_open.nil?
113
+ raise ArgumentError, 'egress_open needs an unreviewed, attacker-reachable leg' if egress_open && !could_be_open
93
114
 
94
115
  super(private: private, untrusted: untrusted, egress_payload_review: egress_payload_review,
95
- egress_destination: egress_destination)
116
+ egress_destination: egress_destination, egress_open: egress_open)
96
117
  end
97
118
 
98
- # Union: the strongest value on each axis wins.
119
+ # Union: the strongest value on each axis wins, and the node is open if
120
+ # either side is.
99
121
  #
100
122
  # read_legs | bash_legs # what an agent holding both ends up with
101
123
  #
124
+ # search = new(private: false, untrusted: :hard,
125
+ # egress_payload_review: :unreviewed, egress_destination: :tool_vouched)
126
+ # compose = new(private: false, untrusted: :none, egress_payload_review: :human_reviewed)
127
+ # (search | compose).egress_open # => false: neither tool leaks unreviewed to a reader
128
+ #
102
129
  # @param other [TrifectaLegs]
103
130
  # @return [TrifectaLegs]
104
131
  def |(other)
105
- # Per-axis, so web_search (unreviewed, vouched) beside a compose tool
106
- # (reviewed, attacker-reachable) scores a cell neither occupies. Pairing
107
- # them up instead would be data flow, which this detector refuses to
108
- # model; over-warning is the declared bias.
109
132
  TrifectaLegs.new(
110
133
  private: private || other.private,
111
134
  untrusted: [untrusted, other.untrusted].max_by { UNTRUSTED_ORDER.index(_1) },
112
135
  egress_payload_review: [egress_payload_review, other.egress_payload_review]
113
136
  .max_by { EGRESS_REVIEW_ORDER.index(_1) },
114
137
  egress_destination: [egress_destination, other.egress_destination]
115
- .max_by { EGRESS_DESTINATION_ORDER.index(_1) }
138
+ .max_by { EGRESS_DESTINATION_ORDER.index(_1) },
139
+ egress_open: egress_open || other.egress_open
116
140
  )
117
141
  end
118
142
 
@@ -150,7 +174,8 @@ module Pikuri
150
174
  # precondition and this method is the mechanical +min+.
151
175
  #
152
176
  # {#egress_destination} is deliberately untouched: a gate bounds *what*
153
- # leaves and *who saw it*, never who can read it back.
177
+ # leaves and *who saw it*, never who can read it back. {#egress_open}
178
+ # closes below +:unreviewed+, since every source is then reviewed.
154
179
  #
155
180
  # @param channel_level [Symbol] one of {EGRESS_REVIEW_ORDER}
156
181
  # @return [TrifectaLegs] with the leg gone entirely when the channel
@@ -159,9 +184,10 @@ module Pikuri
159
184
  def cap_payload_review(channel_level)
160
185
  check!(channel_level, EGRESS_REVIEW_ORDER, 'egress review')
161
186
  capped = [egress_payload_review, channel_level].min_by { EGRESS_REVIEW_ORDER.index(_1) }
162
- return with(egress_payload_review: capped) unless capped == :no_egress
187
+ return with(egress_payload_review: :no_egress, egress_destination: :no_egress, egress_open: false) if
188
+ capped == :no_egress
163
189
 
164
- with(egress_payload_review: :no_egress, egress_destination: :no_egress)
190
+ with(egress_payload_review: capped, egress_open: egress_open && capped == :unreviewed)
165
191
  end
166
192
 
167
193
  # Symbols naming the legs actually present, in the vocabulary the docs and
@@ -177,20 +203,25 @@ module Pikuri
177
203
  tags = []
178
204
  tags << :private if private
179
205
  tags << :"untrusted_#{untrusted}" unless untrusted == :none
180
- tags << egress_tag if egress?
206
+ tags.concat(egress_tags) if egress?
181
207
  tags
182
208
  end
183
209
 
184
210
  private
185
211
 
186
- # @return [Symbol] +:egress+ at full strength, with +_reviewed+ /
212
+ # @return [Array<Symbol>] +:egress+ at full strength, with +_reviewed+ /
187
213
  # +_vouched+ appended per attenuated axis, so the four cells name
188
- # themselves without a lookup table
189
- def egress_tag
214
+ # themselves without a lookup table; two tags when the axes max out
215
+ # from different tools, since no single tag describes that node
216
+ def egress_tags
217
+ if !egress_open && egress_payload_review == :unreviewed && egress_destination == :attacker_reachable
218
+ return %i[egress_reviewed egress_vouched]
219
+ end
220
+
190
221
  parts = ['egress']
191
222
  parts << 'reviewed' if egress_payload_review == :human_reviewed
192
223
  parts << 'vouched' if egress_destination == :tool_vouched
193
- parts.join('_').to_sym
224
+ [parts.join('_').to_sym]
194
225
  end
195
226
 
196
227
  # @raise [ArgumentError] unless +value+ is a level of the +order+ lattice