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,228 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Pikuri
|
|
4
|
+
module Trifecta
|
|
5
|
+
# The result of walking one agent tree: a {Node} with its legs folded — its
|
|
6
|
+
# own tools unioned with everything propagated up from its sub-agents. What
|
|
7
|
+
# {Pikuri::Trifecta.walk} returns, mirroring the tree shape so a host can
|
|
8
|
+
# both classify and display it:
|
|
9
|
+
#
|
|
10
|
+
# report = Pikuri::Trifecta.walk(node)
|
|
11
|
+
# report.tree_verdict # => :soft
|
|
12
|
+
# report.worst_path.map(&:label) # => ["assistant", "RESEARCHER"]
|
|
13
|
+
# puts report.render # the human-readable map
|
|
14
|
+
#
|
|
15
|
+
# == Implementation details
|
|
16
|
+
#
|
|
17
|
+
# {#verdict} is *derived, never stored*: +Data#with+ would otherwise let a
|
|
18
|
+
# copy carry a severity that contradicts its own legs. It reads presence
|
|
19
|
+
# (leg-absence, correct for any level ever added) and matches strength
|
|
20
|
+
# exhaustively across all three graded axes, so introducing a lattice level
|
|
21
|
+
# without placing it in the grid raises on the first wiring that reaches it
|
|
22
|
+
# rather than being silently absorbed into +:soft+.
|
|
23
|
+
#
|
|
24
|
+
# Immutable.
|
|
25
|
+
#
|
|
26
|
+
# @!attribute [r] label
|
|
27
|
+
# @return [String] this agent's name (see {Node#label})
|
|
28
|
+
# @!attribute [r] legs
|
|
29
|
+
# @return [Pikuri::Tool::TrifectaLegs] folded legs — own tools plus
|
|
30
|
+
# everything propagated up from {#children}. What {#verdict} reads.
|
|
31
|
+
# @!attribute [r] tool_legs
|
|
32
|
+
# @return [Hash{String=>Pikuri::Tool::TrifectaLegs}] carried through from
|
|
33
|
+
# the {Node} so {#render} can print the tools as leaves
|
|
34
|
+
# @!attribute [r] children
|
|
35
|
+
# @return [Array<Report>] one per sub-agent, already walked
|
|
36
|
+
# @!attribute [r] channel_egress
|
|
37
|
+
# @return [Symbol, nil] the parent edge's gate level (see
|
|
38
|
+
# {Node#channel_egress})
|
|
39
|
+
class Report < Data.define(:label, :legs, :tool_legs, :children, :channel_egress)
|
|
40
|
+
# Verdicts, least to most severe. The only ordering outside
|
|
41
|
+
# {Pikuri::Tool::TrifectaLegs}.
|
|
42
|
+
#
|
|
43
|
+
# @return [Array<Symbol>]
|
|
44
|
+
SEVERITY = %i[silent soft loud].freeze
|
|
45
|
+
|
|
46
|
+
# Closing pointer of {#advisory}. Names the chapter by *slug*, not by
|
|
47
|
+
# ordinal: book chapters are ordered only by `book/README.md`, so this
|
|
48
|
+
# path survives a reordering that would silently falsify a number.
|
|
49
|
+
#
|
|
50
|
+
# @return [String]
|
|
51
|
+
FOOTER = 'See book/trifecta-detector.md in this repo.'
|
|
52
|
+
|
|
53
|
+
# How dangerous *this node* is — the tree's verdict is {#tree_verdict}.
|
|
54
|
+
#
|
|
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.
|
|
61
|
+
#
|
|
62
|
+
# @return [Symbol] +:silent+, +:soft+ or +:loud+
|
|
63
|
+
# @raise [NoMatchingPatternError] if a lattice level exists that this grid
|
|
64
|
+
# does not place — deliberate, so a new level cannot be absorbed silently
|
|
65
|
+
def verdict
|
|
66
|
+
return :silent unless legs.private && legs.untrusted != :none && legs.egress?
|
|
67
|
+
|
|
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
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Root-first path of Reports down to the most severe node in this subtree,
|
|
77
|
+
# so the caller can both attribute the finding and read its cell:
|
|
78
|
+
#
|
|
79
|
+
# path = report.worst_path
|
|
80
|
+
# path.map(&:label).join(' -> ') # => "assistant -> RESEARCHER"
|
|
81
|
+
# path.last.legs # the cell that decided the verdict
|
|
82
|
+
#
|
|
83
|
+
# Ties go to the node encountered first in pre-order — the parent over its
|
|
84
|
+
# own children, since a parent's trifecta is the more actionable finding.
|
|
85
|
+
#
|
|
86
|
+
# @return [Array<Report>] never empty; +[self]+ when nothing below is worse
|
|
87
|
+
def worst_path
|
|
88
|
+
best = [self]
|
|
89
|
+
children.each do |child|
|
|
90
|
+
candidate = [self, *child.worst_path]
|
|
91
|
+
best = candidate if SEVERITY.index(candidate.last.verdict) > SEVERITY.index(best.last.verdict)
|
|
92
|
+
end
|
|
93
|
+
best
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
# @return [Symbol] the most severe {#verdict} anywhere in this subtree
|
|
97
|
+
def tree_verdict = worst_path.last.verdict
|
|
98
|
+
|
|
99
|
+
# The human-readable map: one line per agent and per tool, indented by
|
|
100
|
+
# depth, with each entry's legs as tags.
|
|
101
|
+
#
|
|
102
|
+
# Trifecta: soft
|
|
103
|
+
#
|
|
104
|
+
# assistant [:private, :untrusted_hard, :egress_reviewed]
|
|
105
|
+
# mail_compose [:private, :egress_reviewed]
|
|
106
|
+
# calculator []
|
|
107
|
+
# RESEARCHER [gate: human_reviewed] [:untrusted_hard, :egress]
|
|
108
|
+
# fetch [:untrusted_hard, :egress]
|
|
109
|
+
#
|
|
110
|
+
# See book/trifecta-detector.md in this repo for ...
|
|
111
|
+
#
|
|
112
|
+
# An agent line carries its *folded* legs and a tool line its own, so
|
|
113
|
+
# propagation shows up as layout: the parent above holds egress that no
|
|
114
|
+
# tool of its own contributes. Plain text by design — a host wanting color
|
|
115
|
+
# or width walks this tree itself rather than asking for styled output.
|
|
116
|
+
#
|
|
117
|
+
# @return [String] newline-separated, no trailing newline
|
|
118
|
+
def render
|
|
119
|
+
[advisory, '', *render_lines].join("\n")
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
# The one-line conclusion: what was found, where, and the leg to break.
|
|
123
|
+
# Separate from {#render} because a status line wants this without the
|
|
124
|
+
# tree, and because it is the half that carries *meaning* — the map
|
|
125
|
+
# deliberately carries only facts.
|
|
126
|
+
#
|
|
127
|
+
# [TRIFECTA: HARD] assistant — private(read) + untrusted(fetch) +
|
|
128
|
+
# egress(fetch). An injection in what this agent reads can drive
|
|
129
|
+
# an exfiltration. Break a leg: sever egress (a network-off sandbox), or
|
|
130
|
+
# privilege-separate the step that reads untrusted content.
|
|
131
|
+
# See book/trifecta-detector.md in this repo.
|
|
132
|
+
#
|
|
133
|
+
# A clean verdict never says "no trifecta detected". This reasons about
|
|
134
|
+
# capability presence, so a quiet result is not a clean bill of health —
|
|
135
|
+
# it under-warns on a single tool that is all three internally, and on
|
|
136
|
+
# private data staged into a file by one tool and read by another.
|
|
137
|
+
# Reporting the *finding* names what would tip the wiring over and claims
|
|
138
|
+
# nothing it cannot support.
|
|
139
|
+
#
|
|
140
|
+
# @return [String]
|
|
141
|
+
def advisory
|
|
142
|
+
path = worst_path
|
|
143
|
+
where = path.map(&:label).join(' -> ')
|
|
144
|
+
legs = path.last.legs
|
|
145
|
+
return "Trifecta: #{where} — #{presence(legs)}." if tree_verdict == :silent
|
|
146
|
+
|
|
147
|
+
"[TRIFECTA: #{tree_verdict == :loud ? 'HARD' : 'soft'}] #{where} — " \
|
|
148
|
+
"#{attribution(path.last)}. An injection in what this agent reads can drive " \
|
|
149
|
+
"an exfiltration. Break a leg: #{advice(legs)}. #{FOOTER}"
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
protected
|
|
153
|
+
|
|
154
|
+
# @param depth [Integer] indentation level
|
|
155
|
+
# @return [Array<String>]
|
|
156
|
+
def render_lines(depth = 0)
|
|
157
|
+
indent = ' ' * depth
|
|
158
|
+
gate = channel_egress ? " [gate: #{channel_egress}]" : ''
|
|
159
|
+
lines = ["#{indent}#{label}#{gate} #{legs.to_tags.inspect}"]
|
|
160
|
+
tool_legs.each { |name, tool| lines << "#{indent} #{name} #{tool.to_tags.inspect}" }
|
|
161
|
+
children.each { |child| lines.concat(child.render_lines(depth + 1)) }
|
|
162
|
+
lines
|
|
163
|
+
end
|
|
164
|
+
|
|
165
|
+
private
|
|
166
|
+
|
|
167
|
+
# @param legs [Pikuri::Tool::TrifectaLegs]
|
|
168
|
+
# @return [String] e.g. +"2 of 3 legs (private, untrusted); no egress leg found"+
|
|
169
|
+
def presence(legs)
|
|
170
|
+
held = { 'private' => legs.private, 'untrusted' => legs.untrusted != :none,
|
|
171
|
+
'egress' => legs.egress? }
|
|
172
|
+
"#{held.count { |_, v| v }} of 3 legs (#{held.select { |_, v| v }.keys.join(', ')}); " \
|
|
173
|
+
"no #{held.reject { |_, v| v }.keys.join('/')} leg found"
|
|
174
|
+
end
|
|
175
|
+
|
|
176
|
+
# Which tool contributed each leg, so the line names something the reader
|
|
177
|
+
# can actually go and change.
|
|
178
|
+
#
|
|
179
|
+
# @param node [Report]
|
|
180
|
+
# @return [String]
|
|
181
|
+
def attribution(node)
|
|
182
|
+
%i[private untrusted egress].filter_map do |axis|
|
|
183
|
+
contributors = node.tool_legs.select { |_, l| leg_present?(l, axis) }.keys
|
|
184
|
+
"#{axis}(#{contributors.join(', ')})" unless contributors.empty?
|
|
185
|
+
end.join(' + ')
|
|
186
|
+
end
|
|
187
|
+
|
|
188
|
+
# @param legs [Pikuri::Tool::TrifectaLegs]
|
|
189
|
+
# @param axis [Symbol] +:private+, +:untrusted+ or +:egress+
|
|
190
|
+
# @return [Boolean]
|
|
191
|
+
def leg_present?(legs, axis)
|
|
192
|
+
case axis
|
|
193
|
+
in :private then legs.private
|
|
194
|
+
in :untrusted then legs.untrusted != :none
|
|
195
|
+
in :egress then legs.egress?
|
|
196
|
+
end
|
|
197
|
+
end
|
|
198
|
+
|
|
199
|
+
# The fix, per cell of the verdict grid — the soft cells want different
|
|
200
|
+
# answers, which is why this reads the legs rather than the verdict symbol.
|
|
201
|
+
#
|
|
202
|
+
# @param legs [Pikuri::Tool::TrifectaLegs]
|
|
203
|
+
# @return [String]
|
|
204
|
+
def advice(legs)
|
|
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'
|
|
212
|
+
end
|
|
213
|
+
|
|
214
|
+
case [legs.untrusted, legs.egress_open]
|
|
215
|
+
in [:hard, true]
|
|
216
|
+
'sever egress (a network-off sandbox), or privilege-separate the step that reads untrusted content'
|
|
217
|
+
in [:hard, false]
|
|
218
|
+
'privilege-separate the step that reads untrusted content, or declare the workspace trusted ' \
|
|
219
|
+
'if you vouch for every byte it can reach'
|
|
220
|
+
in [:weakened, true]
|
|
221
|
+
'sever egress — the untrusted leg is already attenuated by delegation'
|
|
222
|
+
in [:weakened, false]
|
|
223
|
+
'both legs are already attenuated; narrow what counts as private, or drop a leg outright'
|
|
224
|
+
end
|
|
225
|
+
end
|
|
226
|
+
end
|
|
227
|
+
end
|
|
228
|
+
end
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Pikuri
|
|
4
|
+
# The lethal-trifecta detector: does one agent simultaneously hold private
|
|
5
|
+
# data, exposure to attacker-influenceable content, and a way to send bytes
|
|
6
|
+
# out? Any two legs are fine; all three is the live wire, because an injection
|
|
7
|
+
# hidden in the untrusted content can drive the exfiltration.
|
|
8
|
+
#
|
|
9
|
+
# Build a {Node} tree — the agent, its tools, its sub-agents — and walk it:
|
|
10
|
+
#
|
|
11
|
+
# report = Pikuri::Trifecta.walk(node)
|
|
12
|
+
# report.tree_verdict # => :loud
|
|
13
|
+
# puts report.render # the map a bin script prints
|
|
14
|
+
#
|
|
15
|
+
# Nothing here reports itself. Core computes the picture and stops; surfacing
|
|
16
|
+
# it belongs to whoever has a screen ({Pikuri::Agent#trifecta} is the reader).
|
|
17
|
+
# A library writing to a log its embedder never asked for is noise, and a
|
|
18
|
+
# once-per-process guard would be worse than silence in a host that builds
|
|
19
|
+
# two differently-wired agents: it would report the first and stay quiet
|
|
20
|
+
# about the second, which reads as coverage.
|
|
21
|
+
#
|
|
22
|
+
# == This is a smoke alarm, not a firewall
|
|
23
|
+
#
|
|
24
|
+
# It reasons about *capability presence*, never data flow, so it both
|
|
25
|
+
# over-warns (an egress query too narrow to carry anything) and under-warns
|
|
26
|
+
# (one tool that is all three internally; private data staged into a file by
|
|
27
|
+
# one tool and read out by another). It can prove you hold the ingredients. It
|
|
28
|
+
# can prove neither that you are exploitable nor that you are safe — which is
|
|
29
|
+
# why nothing here ever blocks execution, and why the absence of a warning is
|
|
30
|
+
# never reported as an assurance.
|
|
31
|
+
#
|
|
32
|
+
# == Implementation details
|
|
33
|
+
#
|
|
34
|
+
# {.walk} is a pure function of the tree, so the whole rule set is testable
|
|
35
|
+
# from hand-built {Node}s with no agent, no LLM and no sandbox probe.
|
|
36
|
+
#
|
|
37
|
+
# Two operations move legs between nodes, and their asymmetry is the design:
|
|
38
|
+
# +max+ in *parallel* (legs meeting at one node, {Pikuri::Tool::TrifectaLegs#|})
|
|
39
|
+
# and +min+ in *series* (a leg squeezed through a delegation channel,
|
|
40
|
+
# {Pikuri::Tool::TrifectaLegs#cap_payload_review}). Severity is evaluated at every node
|
|
41
|
+
# rather than only at the root, and the tree's verdict is the max over all of
|
|
42
|
+
# them — which localizes a finding to the agent that actually holds it instead
|
|
43
|
+
# of smearing a sub-agent's danger across its parent.
|
|
44
|
+
module Trifecta
|
|
45
|
+
class << self
|
|
46
|
+
# Assemble the tree for a wired agent: its own tools, plus whatever each
|
|
47
|
+
# extension contributes ({Pikuri::Agent::Extension#trifecta_contribution}
|
|
48
|
+
# — legs no tool can declare, and a child per sub-agent persona).
|
|
49
|
+
#
|
|
50
|
+
# @param agent [Pikuri::Agent] a fully built agent
|
|
51
|
+
# @param label [String] name for the root node; defaults to the running
|
|
52
|
+
# program, which is what a host wants in a boot banner
|
|
53
|
+
# @return [Node]
|
|
54
|
+
def build(agent, label: File.basename($PROGRAM_NAME))
|
|
55
|
+
# The root node holds +tools+ ONLY. +sub_agent_tools+ are registered for
|
|
56
|
+
# personas and never reach the parent's LLM — crediting the parent with
|
|
57
|
+
# them reports the sub-agent quarantine as broken, which is the one
|
|
58
|
+
# false alarm guaranteed to get this advisory muted, since that
|
|
59
|
+
# quarantine is the defense the loudest wirings are built around.
|
|
60
|
+
#
|
|
61
|
+
# The *hook* gets both, because a persona resolves its +tool_names+
|
|
62
|
+
# against either list.
|
|
63
|
+
#
|
|
64
|
+
# A tool neither list places — registered on the sub-agent pool and
|
|
65
|
+
# named by no persona — therefore appears nowhere in the tree, and gets
|
|
66
|
+
# no line of its own. Deliberate: nothing here can call it, so it is the
|
|
67
|
+
# absence of a capability rather than one, and it can never explain a
|
|
68
|
+
# verdict. The reverse direction *is* a bug and fails loudly elsewhere —
|
|
69
|
+
# {Pikuri::SubAgent::Extension#configure} raises on a persona naming an
|
|
70
|
+
# unregistered tool. See +D_trifecta_map_orphans+.
|
|
71
|
+
contributions = agent.extensions.filter_map do |ext|
|
|
72
|
+
if ext.respond_to?(:trifecta_contribution)
|
|
73
|
+
ext.trifecta_contribution(agent.tools + agent.sub_agent_tools)
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
tool_legs = agent.tools.to_h { |t| [t.name, t.trifecta_legs] }
|
|
78
|
+
contributions.each do |contribution|
|
|
79
|
+
next if contribution.legs == Tool::TrifectaLegs::NONE
|
|
80
|
+
|
|
81
|
+
previous = tool_legs[contribution.label] || Tool::TrifectaLegs::NONE
|
|
82
|
+
tool_legs[contribution.label] = previous | contribution.legs
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
Node.new(label: label, tool_legs: tool_legs,
|
|
86
|
+
children: contributions.flat_map(&:children))
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# Fold a {Node} tree into a {Report} tree: each node's own tools unioned,
|
|
90
|
+
# then every sub-agent's legs propagated up.
|
|
91
|
+
#
|
|
92
|
+
# @param node [Node] root of the tree, usually the main agent
|
|
93
|
+
# @return [Report] mirrors the input tree, legs folded
|
|
94
|
+
def walk(node)
|
|
95
|
+
children = node.children.map { |child| walk(child) }
|
|
96
|
+
legs = node.tool_legs.values.reduce(Tool::TrifectaLegs::NONE) { |acc, tool| acc | tool }
|
|
97
|
+
legs = children.reduce(legs) { |acc, child| acc | propagated(child) }
|
|
98
|
+
|
|
99
|
+
Report.new(label: node.label, legs: legs, tool_legs: node.tool_legs,
|
|
100
|
+
children: children, channel_egress: node.channel_egress)
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
private
|
|
104
|
+
|
|
105
|
+
# What +child+ contributes to its parent: untrusted attenuated by the
|
|
106
|
+
# boundary, egress capped by the gate on the delegation channel.
|
|
107
|
+
#
|
|
108
|
+
# The cap is skipped when the child holds private data of its own, and
|
|
109
|
+
# that precondition is load-bearing rather than a nicety. A child with
|
|
110
|
+
# file tools can be handed an innocuous approved task, read secrets
|
|
111
|
+
# *after* the gate, and egress a derivative of bytes no human ever saw —
|
|
112
|
+
# so the channel no longer bounds what can leave.
|
|
113
|
+
#
|
|
114
|
+
# @param child [Report]
|
|
115
|
+
# @return [Pikuri::Tool::TrifectaLegs]
|
|
116
|
+
def propagated(child)
|
|
117
|
+
contribution = child.legs.relabel_inbound
|
|
118
|
+
return contribution if child.legs.private
|
|
119
|
+
|
|
120
|
+
# A child with no recorded edge is treated as ungated: absent evidence
|
|
121
|
+
# of a gate is not evidence of one.
|
|
122
|
+
contribution.cap_payload_review(child.channel_egress || :unreviewed)
|
|
123
|
+
end
|
|
124
|
+
end
|
|
125
|
+
end
|
|
126
|
+
end
|
data/lib/pikuri/version.rb
CHANGED
data/lib/pikuri-core.rb
CHANGED
|
@@ -3,55 +3,32 @@
|
|
|
3
3
|
require 'logger'
|
|
4
4
|
require 'zeitwerk'
|
|
5
5
|
|
|
6
|
-
# +Pikuri::VERSION+ lives in its own tiny file so the gemspec can
|
|
7
|
-
#
|
|
8
|
-
#
|
|
9
|
-
#
|
|
10
|
-
# without this line, Zeitwerk's ignore-rule below would leave
|
|
11
|
-
# +Pikuri::VERSION+ undefined for anyone using the installed gem.
|
|
6
|
+
# +Pikuri::VERSION+ lives in its own tiny file so the gemspec can +require_relative+
|
|
7
|
+
# it at build time without loading Zeitwerk and every runtime dep. Requiring it
|
|
8
|
+
# here also defines the constant for ordinary +require 'pikuri-core'+ callers —
|
|
9
|
+
# without this line the Zeitwerk ignore-rule below would leave it undefined.
|
|
12
10
|
require_relative 'pikuri/version'
|
|
13
11
|
|
|
14
|
-
# Boot file: configures the Zeitwerk autoloader for
|
|
15
|
-
#
|
|
16
|
-
#
|
|
17
|
-
#
|
|
18
|
-
# is defined and resolvable. Sibling gems (+pikuri-skills+,
|
|
19
|
-
# +pikuri-mcp+, ...) set up their own Zeitwerk loaders rooted at
|
|
20
|
-
# their own +lib/+ and contribute to the same +Pikuri::+ namespace.
|
|
12
|
+
# Boot file: configures the Zeitwerk autoloader for +pikuri-core/lib/pikuri/+
|
|
13
|
+
# and eager-loads it, so after +require 'pikuri-core'+ every constant
|
|
14
|
+
# pikuri-core ships is defined. Sibling gems set up their own loaders into the
|
|
15
|
+
# same +Pikuri::+ namespace.
|
|
21
16
|
#
|
|
22
|
-
#
|
|
23
|
-
#
|
|
24
|
-
# +
|
|
25
|
-
# memoized +Logger+, all writing through a shared IO that
|
|
26
|
-
# {.log_io=} can swap in one shot (handy in tests, daemons, or
|
|
27
|
-
# anywhere stderr isn't the right sink).
|
|
17
|
+
# The +Pikuri+ module also owns the logging surface ({.logger_for}, {.log_io=},
|
|
18
|
+
# the +PIKURI_LOG+ / +PIKURI_LOG_<NAME>+ env vars): each subsystem holds a
|
|
19
|
+
# memoized +Logger+ writing through a shared IO that {.log_io=} swaps in one shot.
|
|
28
20
|
#
|
|
29
21
|
# == Why eager-load
|
|
30
22
|
#
|
|
31
|
-
# The
|
|
32
|
-
#
|
|
33
|
-
#
|
|
34
|
-
#
|
|
35
|
-
# at boot guarantees the files defining those values run, so the bin
|
|
36
|
-
# script can drop them straight into the +Agent.new+ block via
|
|
37
|
-
# +c.add_tool+ without per-file +require+ ceremony. (web_search is instead
|
|
38
|
-
# host-configured — built per-wiring via {Pikuri::Tool::WebSearch.build}
|
|
39
|
-
# with the host's provider keys — so it is not a value constant.) The cost
|
|
40
|
-
# is a few milliseconds of startup — negligible compared to a single LLM
|
|
41
|
-
# round-trip.
|
|
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.
|
|
42
27
|
module Pikuri
|
|
43
|
-
# Search path for bundled system prompts. Mutable
|
|
44
|
-
#
|
|
45
|
-
# +
|
|
46
|
-
#
|
|
47
|
-
# +pikuri-code/prompts/+. The core gem registers its own
|
|
48
|
-
# +pikuri-core/prompts/+ below; sibling gems do the equivalent in
|
|
49
|
-
# their own entry files.
|
|
50
|
-
#
|
|
51
|
-
# Exposed publicly so a downstream library user can read pikuri's
|
|
52
|
-
# prompts as a starting point for their own system prompt (or
|
|
53
|
-
# use them verbatim). Prefer {.prompt} for the common case of
|
|
54
|
-
# loading one by name.
|
|
28
|
+
# Search path for bundled system prompts. Mutable: each pikuri gem appends its
|
|
29
|
+
# own +prompts/+ at boot, so +Pikuri.prompt(name)+ from a host requiring
|
|
30
|
+
# +pikuri-subagents+ finds its persona prompts there. Public so a downstream
|
|
31
|
+
# user can read pikuri's prompts as a starting point; prefer {.prompt}.
|
|
55
32
|
#
|
|
56
33
|
# @return [Array<String>]
|
|
57
34
|
PROMPT_DIRS = [File.expand_path('../prompts', __dir__)]
|
|
@@ -76,19 +53,15 @@ module Pikuri
|
|
|
76
53
|
# @return [IO] shared sink every {.logger_for} writes through
|
|
77
54
|
attr_reader :log_io
|
|
78
55
|
|
|
79
|
-
# Swap the shared sink (
|
|
80
|
-
#
|
|
81
|
-
# {.logger_for} so callers don't have to re-fetch them.
|
|
56
|
+
# Swap the shared sink (a +StringIO+ in tests, a file in a daemon),
|
|
57
|
+
# re-pointing every logger already handed out by {.logger_for}.
|
|
82
58
|
#
|
|
83
|
-
#
|
|
84
|
-
#
|
|
85
|
-
#
|
|
86
|
-
#
|
|
87
|
-
#
|
|
88
|
-
#
|
|
89
|
-
# caller can hand the same +IO+ back in later. This uses a documented
|
|
90
|
-
# but internal Logger ivar; if a future Ruby renames it the
|
|
91
|
-
# +Engines+ logging specs will fail loudly.
|
|
59
|
+
# Not +Logger#reopen+: it closes the previous sink before installing the new
|
|
60
|
+
# one, which makes "swap to a capture StringIO, then swap back" impossible —
|
|
61
|
+
# the original handle would be dead. Instead we swap each logger's +@logdev+
|
|
62
|
+
# to a fresh +Logger::LogDevice+ over +io+, leaving the previous device
|
|
63
|
+
# open. Uses an internal Logger ivar; if a future Ruby renames it the
|
|
64
|
+
# +Engines+ logging specs fail loudly.
|
|
92
65
|
#
|
|
93
66
|
# @param io [IO] new sink for every Pikuri logger
|
|
94
67
|
# @return [IO]
|
|
@@ -100,16 +73,11 @@ module Pikuri
|
|
|
100
73
|
io
|
|
101
74
|
end
|
|
102
75
|
|
|
103
|
-
# Memoized {Logger} tagged with +name+
|
|
104
|
-
#
|
|
105
|
-
#
|
|
106
|
-
# then +PIKURI_LOG+, then +INFO+.
|
|
107
|
-
#
|
|
108
|
-
# Repeated calls with the same +name+ return the same instance so
|
|
109
|
-
# there is one logger per subsystem and {.log_io=} can rewire them
|
|
110
|
-
# all in one shot.
|
|
76
|
+
# Memoized {Logger} tagged with +name+ as its +progname+. Level resolves
|
|
77
|
+
# +PIKURI_LOG_<NAME>+ → +PIKURI_LOG+ → +INFO+. Repeated calls with the same
|
|
78
|
+
# +name+ return the same instance, so {.log_io=} can rewire them all.
|
|
111
79
|
#
|
|
112
|
-
# @param name [String] subsystem tag (
|
|
80
|
+
# @param name [String] subsystem tag (the +progname+)
|
|
113
81
|
# @return [Logger]
|
|
114
82
|
def logger_for(name)
|
|
115
83
|
@log_loggers[name] ||= begin
|
|
@@ -120,25 +88,16 @@ module Pikuri
|
|
|
120
88
|
end
|
|
121
89
|
end
|
|
122
90
|
|
|
123
|
-
# Read a bundled prompt by basename
|
|
124
|
-
#
|
|
125
|
-
#
|
|
126
|
-
# (+:pikuri-chat+ / +'pikuri-chat'+ / +'pikuri-chat.txt'+ all
|
|
127
|
-
# resolve to the same file).
|
|
128
|
-
#
|
|
129
|
-
# Intended for downstream library users who want to bootstrap their
|
|
130
|
-
# own +Pikuri::Agent+ wiring from pikuri's defaults — read the
|
|
131
|
-
# prompt, customize the bits they care about, hand the result to
|
|
132
|
-
# +Agent.new(system_prompt: ...)+.
|
|
91
|
+
# Read a bundled prompt by basename, searching {PROMPT_DIRS} in order
|
|
92
|
+
# (+.txt+ auto-appended; Symbols accepted). For downstream users
|
|
93
|
+
# bootstrapping their own +Agent+ wiring from pikuri's defaults.
|
|
133
94
|
#
|
|
134
95
|
# @example
|
|
135
|
-
#
|
|
136
|
-
# agent = Pikuri::Agent.new(system_prompt: chat_prompt, ...)
|
|
96
|
+
# agent = Pikuri::Agent.new(system_prompt: Pikuri.prompt(:'pikuri-chat'), ...)
|
|
137
97
|
#
|
|
138
98
|
# @param name [String, Symbol] basename of the prompt file
|
|
139
99
|
# @return [String] file contents
|
|
140
|
-
# @raise [ArgumentError] if no matching file exists in any
|
|
141
|
-
# directory in {PROMPT_DIRS}
|
|
100
|
+
# @raise [ArgumentError] if no matching file exists in any {PROMPT_DIRS}
|
|
142
101
|
def prompt(name)
|
|
143
102
|
basename = name.to_s
|
|
144
103
|
basename += '.txt' unless basename.end_with?('.txt')
|
|
@@ -149,30 +108,49 @@ module Pikuri
|
|
|
149
108
|
available = PROMPT_DIRS.flat_map { |dir| Dir.exist?(dir) ? Dir.children(dir) : [] }.sort.uniq
|
|
150
109
|
raise ArgumentError, "Unknown pikuri prompt #{name.inspect}; available: #{available.join(', ')}"
|
|
151
110
|
end
|
|
111
|
+
|
|
112
|
+
# Read several bundled prompts and join them into one system prompt —
|
|
113
|
+
# the way a binary assembles a base prompt plus shared fragments (e.g.
|
|
114
|
+
# the tool-loop hygiene in +agent-loop.txt+).
|
|
115
|
+
#
|
|
116
|
+
# system_prompt = Pikuri.prompts(:'pikuri-chat', :'agent-loop')
|
|
117
|
+
# system_prompt += "\n\nCurrent date: #{...}" # dynamic tail, still one blank line
|
|
118
|
+
#
|
|
119
|
+
# Each fragment is right-stripped before joining with a single blank
|
|
120
|
+
# line, and the result carries no trailing newline — so neither the
|
|
121
|
+
# fragment seams nor a later +"\n\n"+-prefixed append double-blanks,
|
|
122
|
+
# regardless of the +.txt+ files' own trailing newlines.
|
|
123
|
+
#
|
|
124
|
+
# @param names [Array<String, Symbol>] prompt basenames, in order
|
|
125
|
+
# @return [String] the fragments joined by a blank line
|
|
126
|
+
# @raise [ArgumentError] if any name has no matching file
|
|
127
|
+
def prompts(*names)
|
|
128
|
+
names.map { |name| prompt(name).rstrip }.join("\n\n")
|
|
129
|
+
end
|
|
152
130
|
end
|
|
153
131
|
|
|
154
|
-
# Zeitwerk loader
|
|
155
|
-
#
|
|
156
|
-
#
|
|
157
|
-
# rules can reach it without monkey-patching. Sibling gems
|
|
158
|
-
# (+pikuri-skills+, +pikuri-mcp+, ...) set up their own loaders
|
|
159
|
-
# rooted at their own +lib/+ dirs — see each gem's entry file.
|
|
132
|
+
# Zeitwerk loader for every constant under +pikuri-core/lib/pikuri/+. A
|
|
133
|
+
# constant (not block-scoped) so a downstream host can add ignore rules
|
|
134
|
+
# without monkey-patching. Sibling gems set up their own loaders.
|
|
160
135
|
#
|
|
161
136
|
# @return [Zeitwerk::Loader]
|
|
162
137
|
Loader = Zeitwerk::Loader.new
|
|
163
138
|
Loader.tag = 'pikuri-core'
|
|
164
139
|
Loader.push_dir(File.expand_path('.', __dir__))
|
|
165
140
|
Loader.ignore(__FILE__)
|
|
166
|
-
# +pikuri/version.rb+ defines +Pikuri::VERSION
|
|
167
|
-
#
|
|
168
|
-
#
|
|
169
|
-
# at the top of this file (and also by the gemspec at build time), so
|
|
170
|
-
# the constant is defined before Zeitwerk runs.
|
|
141
|
+
# +pikuri/version.rb+ defines the ALL_CAPS +Pikuri::VERSION+, not
|
|
142
|
+
# +Pikuri::Version+ as Zeitwerk expects — so skip it (it's +require_relative+'d
|
|
143
|
+
# above and by the gemspec, so the constant is already defined).
|
|
171
144
|
Loader.ignore(File.expand_path('pikuri/version.rb', __dir__))
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
)
|
|
145
|
+
# +pikuri/testing.rb+ is opt-in test scaffolding (+require 'pikuri/testing'+
|
|
146
|
+
# from a spec), kept off the production load path — so don't autoload or
|
|
147
|
+
# eager-load it. See {Pikuri::Testing}.
|
|
148
|
+
Loader.ignore(File.expand_path('pikuri/testing.rb', __dir__))
|
|
176
149
|
Loader.setup
|
|
177
150
|
Loader.eager_load
|
|
151
|
+
|
|
152
|
+
# Reap +~/.cache/pikuri/temp-*+ scratch left by processes killed before their
|
|
153
|
+
# {Pikuri::Finalizers} reap could fire. Best-effort, once per process at the
|
|
154
|
+
# earliest load point (every gem requires pikuri-core). See {Paths.new_temp}.
|
|
155
|
+
Paths.sweep_stale_temps!
|
|
178
156
|
end
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
Working with tools:
|
|
2
|
+
- If several next steps are independent (e.g. two unrelated lookups), emit them as parallel tool calls in one turn rather than one at a time.
|
|
3
|
+
- Don't repeat a tool call with identical arguments — re-read the previous observation instead.
|
|
4
|
+
- Treat a tool error (an observation starting with `Error:`) as feedback, not a dead-end: it often tells you how to proceed — retry with corrected or narrowed arguments. Only when the error genuinely leaves no way forward, use what you already have, or tell the user plainly what failed and why (a timeout, an unreachable resource, a rate limit, a missing tool). Don't retry the identical call.
|
|
5
|
+
- When you're done, reply in plain text with no tool call — that is how you end the turn.
|
data/prompts/pikuri-chat.txt
CHANGED
|
@@ -1,15 +1,6 @@
|
|
|
1
1
|
You are an expert assistant who solves tasks by calling tools when needed.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
Choosing a tool:
|
|
8
|
-
- Default to `web_search` whenever a question asks for a specific fact about a named entity — company HQs and headcounts, product versions and release dates, prices, people's bios and roles, anything tying a proper noun to a specific attribute — and for anything time-sensitive or obscure. Your training will *feel* certain on these and is often wrong; check rather than guess. One well-chosen search beats three exploratory ones.
|
|
9
|
-
- Use `calculator` for any arithmetic beyond simple mental math. Don't search the web for "what is X * Y".
|
|
3
|
+
How to work:
|
|
4
|
+
- When a question asks for a specific fact about a named entity — company HQs and headcounts, product versions and release dates, prices, people's bios and roles, anything tying a proper noun to a specific attribute — or for anything time-sensitive or obscure, search the web rather than answering from memory. Your training will *feel* certain on these and is often wrong; check rather than guess. One well-chosen search beats three exploratory ones.
|
|
5
|
+
- For any arithmetic beyond simple mental math, compute it with a tool rather than in your head — and don't search the web for "what is X * Y".
|
|
10
6
|
- Reply directly, without any tool, for language and translation, definitions of common terms, and widely-known general history.
|
|
11
|
-
|
|
12
|
-
Other guidelines:
|
|
13
|
-
- Don't repeat a tool call with identical arguments — re-read the previous observation instead.
|
|
14
|
-
- On a tool error (observation starting with `Error:`): use the data you already have to answer if you can. If you can't, reply to the user that you weren't able to find the answer and briefly say why (e.g. "web search hit a rate limit", "the page wasn't reachable"). Do not retry the same call hoping for a different result, and do not loop on rephrased variants of the same failing call.
|
|
15
|
-
- When you have the answer, reply in plain text with no tool call. That is how you finish.
|