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,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
@@ -6,5 +6,5 @@ module Pikuri
6
6
  # additions to the public surface (+Pikuri::Tool+ / +Pikuri::Agent+ /
7
7
  # listeners / bundled tools), major for breaking changes to that
8
8
  # surface or to the +bin/pikuri-*+ CLIs.
9
- VERSION = '0.0.7'
9
+ VERSION = '0.2.0'
10
10
  end
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 read
7
- # the version constant via +require_relative+ at build time without
8
- # loading Zeitwerk and every runtime dep. Requiring it here makes the
9
- # constant available to ordinary +require 'pikuri-core'+ callers too —
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 every file under
15
- # +pikuri-core/lib/pikuri/+ and eager-loads them all. After
16
- # +require 'pikuri-core'+, every constant pikuri-core ships
17
- # (+Pikuri::Agent+, +Pikuri::Tool+, +Pikuri::Tool::Calculator+, ...)
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
- # Beyond loading, the +Pikuri+ module owns the logging surface — see
23
- # {.logger_for}, {.log_io=}, and the +PIKURI_LOG+ /
24
- # +PIKURI_LOG_<NAME>+ env vars. Each subsystem holds its own
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 stateless bundled tools (+Pikuri::Tool::CALCULATOR+,
32
- # +Pikuri::Tool::WEB_SCRAPE+, +Pikuri::Tool::FETCH+) are +ALL_CAPS+ value
33
- # constants rather than classes/modules, and Zeitwerk only auto-loads
34
- # constants that match its filename-↔-CamelCase convention. Eager-loading
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 list: each pikuri
44
- # gem appends its own +prompts/+ directory when it boots, so a
45
- # +Pikuri.prompt(name)+ call from a host that requires +pikuri-code+
46
- # (for example) finds +coding-system-prompt.txt+ in
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 (e.g. a +StringIO+ in tests, a file in a
80
- # daemon). Re-points every logger already handed out by
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
- # Why we don't use +Logger#reopen+: that method closes the previous
84
- # sink before installing the new one, which makes "swap to a
85
- # capture +StringIO+, then swap back to the original" impossible —
86
- # the original handle would be dead the second time around. Instead
87
- # we swap each logger's +@logdev+ to a fresh +Logger::LogDevice+
88
- # over the new +io+, leaving the previous device untouched so the
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+ in its +progname+, so each
104
- # subsystem's lines stand out in the shared sink. Level resolves
105
- # in this order: +PIKURI_LOG_<NAME>+ (e.g. +PIKURI_LOG_ENGINES=debug+),
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 (rendered as +progname+)
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. Searches every directory in
124
- # {PROMPT_DIRS} in order, returning the first match. +.txt+ is
125
- # auto-appended if absent. Symbols are accepted as a convenience
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
- # chat_prompt = Pikuri.prompt(:'pikuri-chat')
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 managing every constant under
155
- # +pikuri-core/lib/pikuri/+. Exposed as a constant (rather than scoped
156
- # to the boot block) so a downstream host that wants to add ignore
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+ (an ALL_CAPS value
167
- # constant), not +Pikuri::Version+ as Zeitwerk would expect from the
168
- # filename — so tell the loader to skip it. The file is +require_relative+'d
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
- Loader.inflector.inflect(
173
- 'html' => 'HTML',
174
- 'duckduckgo' => 'DuckDuckGo'
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.
@@ -1,15 +1,6 @@
1
1
  You are an expert assistant who solves tasks by calling tools when needed.
2
2
 
3
- You have access to tools described in the API's tool list. To call one, use the standard tool-call mechanism — do not write tool calls as text.
4
-
5
- If several next steps are independent (e.g. two unrelated lookups), emit them as parallel tool calls in a single turn rather than one at a time.
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.