pikuri-core 0.0.7 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +17 -30
  3. data/lib/pikuri/agent/chat_transport.rb +168 -107
  4. data/lib/pikuri/agent/configurator.rb +194 -173
  5. data/lib/pikuri/agent/control/cancellable.rb +100 -70
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +107 -118
  8. data/lib/pikuri/agent/control.rb +13 -35
  9. data/lib/pikuri/agent/event.rb +144 -197
  10. data/lib/pikuri/agent/extension.rb +83 -95
  11. data/lib/pikuri/agent/history.rb +247 -0
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +169 -136
  14. data/lib/pikuri/agent/listener/token_log.rb +84 -157
  15. data/lib/pikuri/agent/listener.rb +24 -44
  16. data/lib/pikuri/agent/listener_list.rb +32 -47
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +1095 -577
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/bundler_env.rb +68 -0
  21. data/lib/pikuri/extractor/passthrough.rb +24 -31
  22. data/lib/pikuri/extractor.rb +125 -155
  23. data/lib/pikuri/file_type.rb +64 -136
  24. data/lib/pikuri/finalizers.rb +32 -47
  25. data/lib/pikuri/paths.rb +104 -13
  26. data/lib/pikuri/sanitizer.rb +46 -67
  27. data/lib/pikuri/subprocess.rb +86 -118
  28. data/lib/pikuri/testing.rb +369 -0
  29. data/lib/pikuri/tool/calculator.rb +168 -74
  30. data/lib/pikuri/tool/execute_context.rb +42 -0
  31. data/lib/pikuri/tool/parameters.rb +31 -29
  32. data/lib/pikuri/tool/result.rb +164 -0
  33. data/lib/pikuri/tool/trifecta_legs.rb +248 -0
  34. data/lib/pikuri/tool.rb +416 -67
  35. data/lib/pikuri/trifecta/contribution.rb +43 -0
  36. data/lib/pikuri/trifecta/node.rb +47 -0
  37. data/lib/pikuri/trifecta/report.rb +228 -0
  38. data/lib/pikuri/trifecta.rb +126 -0
  39. data/lib/pikuri/version.rb +1 -1
  40. data/lib/pikuri-core.rb +70 -92
  41. data/prompts/agent-loop.txt +5 -0
  42. data/prompts/pikuri-chat.txt +3 -12
  43. metadata +26 -72
  44. data/lib/pikuri/agent/context_window_detector.rb +0 -222
  45. data/lib/pikuri/agent/control/step_limit.rb +0 -111
  46. data/lib/pikuri/agent/extension_context.rb +0 -147
  47. data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
  48. data/lib/pikuri/agent/synthesizer.rb +0 -171
  49. data/lib/pikuri/extractor/html.rb +0 -303
  50. data/lib/pikuri/tool/fetch.rb +0 -172
  51. data/lib/pikuri/tool/scraper.rb +0 -186
  52. data/lib/pikuri/tool/search/brave.rb +0 -198
  53. data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
  54. data/lib/pikuri/tool/search/engines.rb +0 -186
  55. data/lib/pikuri/tool/search/exa.rb +0 -229
  56. data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
  57. data/lib/pikuri/tool/search/result.rb +0 -29
  58. data/lib/pikuri/tool/web_scrape.rb +0 -121
  59. data/lib/pikuri/tool/web_search.rb +0 -57
  60. data/lib/pikuri/url_cache.rb +0 -112
@@ -0,0 +1,248 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Pikuri
4
+ class Tool
5
+ # Which of the lethal trifecta's three legs a tool contributes — private
6
+ # data in, attacker-influenceable content in, bytes out. A tool declares its
7
+ # legs in its own constructor, where every collaborator that decides them
8
+ # (workspace, sandbox, confirmer) is already a kwarg:
9
+ #
10
+ # super(name: 'read', ..., trifecta_legs: Tool::TrifectaLegs.new(
11
+ # private: fs.private?,
12
+ # untrusted: fs.trusted? ? :none : :hard,
13
+ # egress_payload_review: :no_egress))
14
+ #
15
+ # {Pikuri::Trifecta} unions these across an agent's tools and folds in its
16
+ # sub-agents to decide whether all three legs are live at one node.
17
+ #
18
+ # == Implementation details
19
+ #
20
+ # Three axes are graded rather than boolean, and this class is the only
21
+ # place their ordering lives: {#|} takes the per-axis +max+ (legs meeting at
22
+ # one node), {#cap_payload_review} the +min+ (a leg squeezed through a
23
+ # delegation channel), and {#relabel_inbound} applies the one fixed demotion
24
+ # a sub-agent boundary buys. Nothing else may compare levels — the verdict
25
+ # reads presence and top-ness only (see {Pikuri::Trifecta::Report#verdict}).
26
+ #
27
+ # The egress leg is *two* axes because they are orthogonal: an unreviewed
28
+ # query to a vouched engine and a human-reviewed send to an attacker's inbox
29
+ # are different animals, and neither dominates the other. Both carry
30
+ # +:no_egress+ at the bottom and the constructor keeps them coherent, so the
31
+ # leg is present on both or on neither ({#egress?} is the canonical read).
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
+ #
40
+ # Immutable.
41
+ #
42
+ # @!attribute [r] private
43
+ # @return [Boolean] reads data that may be sensitive. The framework cannot
44
+ # know this — sensitivity is a property of the data, not of the tool — so
45
+ # the user declares it on the workspace/corpus and the tool inherits it.
46
+ # @!attribute [r] untrusted
47
+ # @return [Symbol] +:none+, +:weakened+ (reached this agent through a
48
+ # sub-agent, whose summarization relays an injected instruction as a
49
+ # reported fact) or +:hard+ (verbatim into this agent's context).
50
+ # @!attribute [r] egress_payload_review
51
+ # Answers: did a human see the bytes that leave?
52
+ #
53
+ # @return [Symbol] +:no_egress+, +:human_reviewed+ (the payload *is* the
54
+ # reviewed artifact — a compose window, an editable task string) or
55
+ # +:unreviewed+, which covers both no human at all and a human who saw
56
+ # only a proxy: approving +curl+ approves a program, and the bytes it
57
+ # sends are computed after the click.
58
+ # @!attribute [r] egress_destination
59
+ # Answers: if an injection hijacks the model, can it reach the attacker?
60
+ #
61
+ # @return [Symbol] +:no_egress+; +:attacker_reachable+ — the caller picks
62
+ # the host, *or* a fixed sink republishes what it receives (a hard-coded
63
+ # +gist.github.com+ POST is pinned and world-readable, so pinning alone
64
+ # buys nothing); or +:tool_vouched+, declarable iff the caller cannot
65
+ # choose the destination, that destination does not republish, and the
66
+ # request is not attacker-readable in flight or at rest. Unverifiable by
67
+ # the framework: like +private+, it is a declaration it inherits.
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)
77
+ # Danger order, least to most: +max+ is union at a node, +min+ is the cap
78
+ # through a delegation channel.
79
+ #
80
+ # @return [Array<Symbol>]
81
+ UNTRUSTED_ORDER = %i[none weakened hard].freeze
82
+
83
+ # @return [Array<Symbol>] danger order, least to most (see {UNTRUSTED_ORDER})
84
+ EGRESS_REVIEW_ORDER = %i[no_egress human_reviewed unreviewed].freeze
85
+
86
+ # @return [Array<Symbol>] danger order, least to most (see {UNTRUSTED_ORDER})
87
+ EGRESS_DESTINATION_ORDER = %i[no_egress tool_vouched attacker_reachable].freeze
88
+
89
+ # @param private [Boolean]
90
+ # @param untrusted [Symbol] one of {UNTRUSTED_ORDER}
91
+ # @param egress_payload_review [Symbol] one of {EGRESS_REVIEW_ORDER}
92
+ # @param egress_destination [Symbol, nil] one of {EGRESS_DESTINATION_ORDER};
93
+ # omit to derive — +:no_egress+ without a leg, else the pessimistic
94
+ # +:attacker_reachable+, so silence never buys the softer grade.
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)
103
+ egress_destination ||= egress_payload_review == :no_egress ? :no_egress : :attacker_reachable
104
+ check!(untrusted, UNTRUSTED_ORDER, 'untrusted')
105
+ check!(egress_payload_review, EGRESS_REVIEW_ORDER, 'egress review')
106
+ check!(egress_destination, EGRESS_DESTINATION_ORDER, 'egress destination')
107
+ unless (egress_payload_review == :no_egress) == (egress_destination == :no_egress)
108
+ raise ArgumentError, 'egress axes disagree on whether the leg exists: ' \
109
+ "#{egress_payload_review.inspect} / #{egress_destination.inspect}"
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
114
+
115
+ super(private: private, untrusted: untrusted, egress_payload_review: egress_payload_review,
116
+ egress_destination: egress_destination, egress_open: egress_open)
117
+ end
118
+
119
+ # Union: the strongest value on each axis wins, and the node is open if
120
+ # either side is.
121
+ #
122
+ # read_legs | bash_legs # what an agent holding both ends up with
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
+ #
129
+ # @param other [TrifectaLegs]
130
+ # @return [TrifectaLegs]
131
+ def |(other)
132
+ TrifectaLegs.new(
133
+ private: private || other.private,
134
+ untrusted: [untrusted, other.untrusted].max_by { UNTRUSTED_ORDER.index(_1) },
135
+ egress_payload_review: [egress_payload_review, other.egress_payload_review]
136
+ .max_by { EGRESS_REVIEW_ORDER.index(_1) },
137
+ egress_destination: [egress_destination, other.egress_destination]
138
+ .max_by { EGRESS_DESTINATION_ORDER.index(_1) },
139
+ egress_open: egress_open || other.egress_open
140
+ )
141
+ end
142
+
143
+ # @return [Boolean] whether this contributes an egress leg at all. The
144
+ # canonical presence read, since both egress axes encode absence.
145
+ def egress? = egress_payload_review != :no_egress
146
+
147
+ # These legs as they reach a *parent* across a sub-agent boundary: +:hard+
148
+ # untrusted demotes to +:weakened+, the other three axes are identity.
149
+ #
150
+ # The boundary filters *instructions*, not *content* — a faithful summary
151
+ # preserves the page's facts but has no reason to adopt an out-of-band
152
+ # imperative, so an injection arrives as a reported fact rather than as a
153
+ # command. Private data survives intact (a summary of a secret still
154
+ # contains the secret), and egress survives because the parent can simply
155
+ # ask the child to send the thing.
156
+ #
157
+ # @return [TrifectaLegs]
158
+ def relabel_inbound
159
+ # Saturating, not one-rung-down: :weakened stays :weakened. Decrementing
160
+ # per hop would launder a grandchild's untrusted content to :none at
161
+ # depth three — two summarizers are no more instruction-resistant than
162
+ # one, and that is the structural claim this design refuses to make.
163
+ with(untrusted: untrusted == :hard ? :weakened : untrusted)
164
+ end
165
+
166
+ # These legs with the *review* axis capped at what the delegation channel
167
+ # itself allows — +min+ in series, the counterpart to {#|}'s +max+ in
168
+ # parallel.
169
+ #
170
+ # A child's egress cannot exceed the channel feeding it: when the only
171
+ # bytes crossing into the child are a task string a human approved, even a
172
+ # fully poisoned child can send nothing else. That holds *only* while the
173
+ # child has no private data of its own, so {Pikuri::Trifecta.walk} owns the
174
+ # precondition and this method is the mechanical +min+.
175
+ #
176
+ # {#egress_destination} is deliberately untouched: a gate bounds *what*
177
+ # leaves and *who saw it*, never who can read it back. {#egress_open}
178
+ # closes below +:unreviewed+, since every source is then reviewed.
179
+ #
180
+ # @param channel_level [Symbol] one of {EGRESS_REVIEW_ORDER}
181
+ # @return [TrifectaLegs] with the leg gone entirely when the channel
182
+ # carries no egress at all
183
+ # @raise [ArgumentError] on a level outside the lattice
184
+ def cap_payload_review(channel_level)
185
+ check!(channel_level, EGRESS_REVIEW_ORDER, 'egress review')
186
+ capped = [egress_payload_review, channel_level].min_by { EGRESS_REVIEW_ORDER.index(_1) }
187
+ return with(egress_payload_review: :no_egress, egress_destination: :no_egress, egress_open: false) if
188
+ capped == :no_egress
189
+
190
+ with(egress_payload_review: capped, egress_open: egress_open && capped == :unreviewed)
191
+ end
192
+
193
+ # Symbols naming the legs actually present, in the vocabulary the docs and
194
+ # the rendered tree use. Absent legs are omitted, so a leg-free tool
195
+ # yields +[]+ rather than three +:none+ entries.
196
+ #
197
+ # TrifectaLegs.new(private: true, untrusted: :hard,
198
+ # egress_payload_review: :no_egress).to_tags
199
+ # # => [:private, :untrusted_hard]
200
+ #
201
+ # @return [Array<Symbol>]
202
+ def to_tags
203
+ tags = []
204
+ tags << :private if private
205
+ tags << :"untrusted_#{untrusted}" unless untrusted == :none
206
+ tags.concat(egress_tags) if egress?
207
+ tags
208
+ end
209
+
210
+ private
211
+
212
+ # @return [Array<Symbol>] +:egress+ at full strength, with +_reviewed+ /
213
+ # +_vouched+ appended per attenuated axis, so the four cells name
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
+
221
+ parts = ['egress']
222
+ parts << 'reviewed' if egress_payload_review == :human_reviewed
223
+ parts << 'vouched' if egress_destination == :tool_vouched
224
+ [parts.join('_').to_sym]
225
+ end
226
+
227
+ # @raise [ArgumentError] unless +value+ is a level of the +order+ lattice
228
+ def check!(value, order, name)
229
+ raise ArgumentError, "unknown #{name} level: #{value.inspect}" unless order.include?(value)
230
+ end
231
+
232
+ # @return [TrifectaLegs] no legs at all
233
+ NONE = new(private: false, untrusted: :none, egress_payload_review: :no_egress)
234
+
235
+ # What an *undeclared* tool is presumed to hold: hostile on every axis the
236
+ # framework could have determined for itself. Silence from a tool author is
237
+ # not evidence of safety.
238
+ #
239
+ # It stops short of +private: true+ deliberately — that axis is the user's
240
+ # to declare, and assuming it would make every wiring loud, turning a
241
+ # warn-only advisory into noise and getting it muted.
242
+ #
243
+ # @return [TrifectaLegs]
244
+ ASSUMED = new(private: false, untrusted: :hard, egress_payload_review: :unreviewed,
245
+ egress_destination: :attacker_reachable)
246
+ end
247
+ end
248
+ end