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.
- checksums.yaml +4 -4
- data/README.md +17 -30
- data/lib/pikuri/agent/chat_transport.rb +168 -107
- data/lib/pikuri/agent/configurator.rb +194 -173
- data/lib/pikuri/agent/control/cancellable.rb +100 -70
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +107 -118
- data/lib/pikuri/agent/control.rb +13 -35
- data/lib/pikuri/agent/event.rb +144 -197
- data/lib/pikuri/agent/extension.rb +83 -95
- data/lib/pikuri/agent/history.rb +247 -0
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +169 -136
- data/lib/pikuri/agent/listener/token_log.rb +84 -157
- data/lib/pikuri/agent/listener.rb +24 -44
- data/lib/pikuri/agent/listener_list.rb +32 -47
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +1095 -577
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/bundler_env.rb +68 -0
- data/lib/pikuri/extractor/passthrough.rb +24 -31
- data/lib/pikuri/extractor.rb +125 -155
- data/lib/pikuri/file_type.rb +64 -136
- data/lib/pikuri/finalizers.rb +32 -47
- data/lib/pikuri/paths.rb +104 -13
- data/lib/pikuri/sanitizer.rb +46 -67
- data/lib/pikuri/subprocess.rb +86 -118
- data/lib/pikuri/testing.rb +369 -0
- data/lib/pikuri/tool/calculator.rb +168 -74
- data/lib/pikuri/tool/execute_context.rb +42 -0
- data/lib/pikuri/tool/parameters.rb +31 -29
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +248 -0
- data/lib/pikuri/tool.rb +416 -67
- data/lib/pikuri/trifecta/contribution.rb +43 -0
- data/lib/pikuri/trifecta/node.rb +47 -0
- data/lib/pikuri/trifecta/report.rb +228 -0
- data/lib/pikuri/trifecta.rb +126 -0
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +70 -92
- data/prompts/agent-loop.txt +5 -0
- data/prompts/pikuri-chat.txt +3 -12
- metadata +26 -72
- data/lib/pikuri/agent/context_window_detector.rb +0 -222
- data/lib/pikuri/agent/control/step_limit.rb +0 -111
- data/lib/pikuri/agent/extension_context.rb +0 -147
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
- data/lib/pikuri/agent/synthesizer.rb +0 -171
- data/lib/pikuri/extractor/html.rb +0 -303
- data/lib/pikuri/tool/fetch.rb +0 -172
- data/lib/pikuri/tool/scraper.rb +0 -186
- data/lib/pikuri/tool/search/brave.rb +0 -198
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
- data/lib/pikuri/tool/search/engines.rb +0 -186
- data/lib/pikuri/tool/search/exa.rb +0 -229
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
- data/lib/pikuri/tool/search/result.rb +0 -29
- data/lib/pikuri/tool/web_scrape.rb +0 -121
- data/lib/pikuri/tool/web_search.rb +0 -57
- 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
|