pikuri-core 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +16 -29
  3. data/lib/pikuri/agent/chat_transport.rb +114 -33
  4. data/lib/pikuri/agent/configurator.rb +191 -110
  5. data/lib/pikuri/agent/control/cancellable.rb +25 -16
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +87 -120
  8. data/lib/pikuri/agent/control.rb +9 -11
  9. data/lib/pikuri/agent/event.rb +73 -61
  10. data/lib/pikuri/agent/extension.rb +45 -81
  11. data/lib/pikuri/agent/history.rb +91 -497
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +115 -108
  14. data/lib/pikuri/agent/listener/token_log.rb +21 -55
  15. data/lib/pikuri/agent/listener.rb +4 -4
  16. data/lib/pikuri/agent/listener_list.rb +19 -13
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +624 -448
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/extractor/passthrough.rb +5 -2
  21. data/lib/pikuri/extractor.rb +43 -12
  22. data/lib/pikuri/file_type.rb +4 -4
  23. data/lib/pikuri/finalizers.rb +2 -2
  24. data/lib/pikuri/paths.rb +1 -1
  25. data/lib/pikuri/sanitizer.rb +4 -3
  26. data/lib/pikuri/subprocess.rb +17 -5
  27. data/lib/pikuri/testing.rb +122 -49
  28. data/lib/pikuri/tool/calculator.rb +134 -30
  29. data/lib/pikuri/tool/execute_context.rb +2 -2
  30. data/lib/pikuri/tool/parameters.rb +10 -0
  31. data/lib/pikuri/tool/result.rb +164 -0
  32. data/lib/pikuri/tool/trifecta_legs.rb +52 -21
  33. data/lib/pikuri/tool.rb +298 -24
  34. data/lib/pikuri/trifecta/report.rb +28 -30
  35. data/lib/pikuri/trifecta.rb +1 -2
  36. data/lib/pikuri/version.rb +1 -1
  37. data/lib/pikuri-core.rb +5 -11
  38. metadata +16 -73
  39. data/lib/pikuri/agent/context_window_detector.rb +0 -181
  40. data/lib/pikuri/agent/control/step_limit.rb +0 -95
  41. data/lib/pikuri/agent/extension_context.rb +0 -120
  42. data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
  43. data/lib/pikuri/agent/synthesizer.rb +0 -129
  44. data/lib/pikuri/extractor/html.rb +0 -256
  45. data/lib/pikuri/ruby_llm_patches.rb +0 -106
  46. data/lib/pikuri/tool/fetch.rb +0 -146
  47. data/lib/pikuri/tool/scraper.rb +0 -144
  48. data/lib/pikuri/tool/search/brave.rb +0 -170
  49. data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
  50. data/lib/pikuri/tool/search/engines.rb +0 -319
  51. data/lib/pikuri/tool/search/exa.rb +0 -195
  52. data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
  53. data/lib/pikuri/tool/search/result.rb +0 -24
  54. data/lib/pikuri/tool/web_scrape.rb +0 -105
  55. data/lib/pikuri/tool/web_search.rb +0 -133
  56. data/lib/pikuri/url_cache.rb +0 -96
@@ -24,7 +24,7 @@ module Pikuri
24
24
  @events << event
25
25
  end
26
26
 
27
- # @return [String] short label for {Agent#to_s}
27
+ # @return [String] short label for {ListenerList#to_s}
28
28
  def to_s
29
29
  'InMemoryEventList'
30
30
  end
@@ -7,18 +7,33 @@ module Pikuri
7
7
  class Agent
8
8
  module Listener
9
9
  # Terminal renderer for the normalized event stream: dim grey reasoning,
10
- # assistant Markdown printed raw, cyan tool-call/result lines, yellow
11
- # fallback notice, red cancelled, magenta model-switch.
12
- # {Event::UserTurn} / {Event::Tokens} / {Event::ContextCap} are silent
10
+ # assistant Markdown printed unrendered, tool-call/result lines in Kuri's coat
11
+ # ({TOOL_COLOR}), yellow fallback notice, red cancelled, magenta
12
+ # model-switch. A tool call renders as the two strings the tool composed,
13
+ # never an argument dump or a slice of the observation:
14
+ #
15
+ # → Write(lib/shared/config.rb)
16
+ # = Added 2 lines, removed 3 lines
17
+ #
18
+ # {Event::UserTurn} / {Event::Tokens} are silent
13
19
  # (echo, or {TokenLog}'s business); {Event::SystemInjected} renders dim
14
20
  # grey with a +⊕+ marker. Any unrecognized event — notably a gem
15
21
  # *domain* event — renders generically via its +to_s+ (dim grey, +·+
16
- # marker), so a new variant shows in the demo without a change here. An
17
- # {Event::Transient} one instead rewrites a single line in place, and the
18
- # text of every domain event is defanged through {Pikuri::Sanitizer} —
19
- # a +to_s+ may carry a filename, a skill name or a server's own words.
22
+ # marker), so a new variant shows in the demo without a change here. Its
23
+ # text is defanged through {Pikuri::Sanitizer} — a +to_s+ may carry a
24
+ # filename, a skill name or a server's own words.
25
+ #
26
+ # Prose — reasoning, assistant Markdown, an injected block — prints as
27
+ # written except for the bytes a terminal *acts on*, which show escaped:
28
+ #
29
+ # "done\e[1A\e[2K" # prints done\x1b[1A\x1b[2K
20
30
  #
21
- # Assistant Markdown prints raw, no Markdown-to-ANSI: rendering can't
31
+ # A model echoing an attacker's bytes could otherwise recolor, overwrite
32
+ # or erase lines already on screen, a guard's warning among them. Tabs
33
+ # and zero-width joiners pass, since honest prose carries them (Go code,
34
+ # 👩‍💻) — which is why this isn't {Pikuri::Sanitizer} wholesale.
35
+ #
36
+ # Assistant Markdown prints unrendered, no Markdown-to-ANSI: rendering can't
22
37
  # apply to the streaming path anyway (half-built fences/tables), and the
23
38
  # one gem for it (tty-markdown) was unmaintained, crashed on
24
39
  # ANSI-in-tables, and pulled seven transitive deps — proper rendering
@@ -36,10 +51,29 @@ module Pikuri
36
51
  # not their content (already landed via deltas). With +streaming: false+
37
52
  # (default) the deltas are ignored and the bookends render full text.
38
53
  class Terminal < Base
39
- # Char cap on tool-result content rendered to the terminal; longer is
40
- # truncated with a marker reporting the original byte size (so a
41
- # 200-char return is distinguishable from a 50KB dump).
42
- MAX_TOOL_RESULT_CHARS = 200
54
+ # Char cap on a tool's display strings ({Event::ToolResult}'s summary, a
55
+ # display name). Generous — these are one short line by construction,
56
+ # and the cap is a backstop against an +"Error: ..."+ observation
57
+ # passing a long message through.
58
+ MAX_SUMMARY_CHARS = 200
59
+
60
+ # Floor on the room a tool-call argument gets, for the narrow terminal
61
+ # where the budget arithmetic would otherwise leave it nothing.
62
+ MIN_ARGUMENT_CHARS = 20
63
+
64
+ # The bytes a terminal acts on rather than prints, as prose may carry
65
+ # them: C0 controls bar tab and newline, DEL, C1, the bidi overrides.
66
+ # {Pikuri::Sanitizer::SUSPECT} minus tab and the zero-width set.
67
+ PROSE_SUSPECT = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f‪-‮⁦-⁩]/
68
+
69
+ # Color of the +→ call+ / += result+ lines: Kuri's Talus coat
70
+ # (+assets/kuri.svg+) with the chroma lifted, because the coat verbatim
71
+ # (+#a89c8e+, 13% saturation) lands on the dim reasoning grey's
72
+ # lightness and reads as a second shade of it. An absolute RGB rather
73
+ # than a named ANSI color, so a remapped terminal palette can't repaint
74
+ # pikuri's own color — the same hex the tui and web shells paint.
75
+ # @return [String]
76
+ TOOL_COLOR = '#c1a586'
43
77
 
44
78
  # Padding for a sub-agent's stream. Absolute, not additive — sub-agent
45
79
  # recursion is blocked (the sub-agent's toolset excludes +sub_agent+),
@@ -55,7 +89,6 @@ module Pikuri
55
89
  @padding = padding
56
90
  @streaming = streaming
57
91
  @at_line_start = true
58
- @transient = false
59
92
  end
60
93
 
61
94
  # @return [Integer] current padding width.
@@ -82,36 +115,32 @@ module Pikuri
82
115
  if @streaming
83
116
  terminate_stream
84
117
  else
85
- println(indent(Rainbow(content).color(85, 85, 85)))
118
+ println(indent(Rainbow(defang_prose(content)).color(85, 85, 85)))
86
119
  end
87
120
  in Event::Assistant(content:)
88
121
  if @streaming
89
122
  terminate_stream
90
123
  else
91
- println(indent(content))
124
+ println(indent(defang_prose(content)))
92
125
  end
93
126
  in Event::ThinkingDelta(content:)
94
- stream_fragment(Rainbow(content).color(85, 85, 85)) if @streaming
127
+ stream_fragment(Rainbow(defang_prose(content)).color(85, 85, 85)) if @streaming
95
128
  in Event::AssistantDelta(content:)
96
- stream_fragment(content) if @streaming
129
+ stream_fragment(defang_prose(content)) if @streaming
97
130
  in Event::SystemInjected(content:)
98
- println(indent(Rainbow("⊕ #{content}").color(85, 85, 85)))
99
- in Event::ToolCall(name:, arguments:)
100
- args = arguments.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
101
- println(indent(Rainbow("→ #{name}(#{args})").cyan))
102
- in Event::ToolResult(content:)
103
- println(indent(Rainbow("= #{truncate_tool_result(content)}").cyan))
131
+ println(indent(Rainbow("⊕ #{defang_prose(content)}").color(85, 85, 85)))
132
+ in Event::ToolCall(display_name:, argument:)
133
+ println(indent(Rainbow("→ #{tool_call_line(display_name, argument)}").color(TOOL_COLOR)))
134
+ in Event::ToolResult(summary:)
135
+ println(indent(Rainbow("= #{defang(summary, MAX_SUMMARY_CHARS)}").color(TOOL_COLOR)))
104
136
  in Event::ModelSwitched(from:, to:)
105
137
  println(indent(Rainbow("⇄ model: #{from.model} → #{to.model}").magenta))
106
- in Event::FallbackNotice(reason:)
107
- println(indent(Rainbow("! #{reason}").yellow))
138
+ in Event::HistoryCompacted(messages_before:, messages_after:)
139
+ println(indent(Rainbow("⇣ compacted: #{messages_before} → #{messages_after} messages").magenta))
108
140
  in Event::Cancelled
109
141
  println(indent(Rainbow('! cancelled').red))
110
- in Event::Reset
111
- println(indent(Rainbow('— context cleared —').color(85, 85, 85)))
112
- in Event::UserTurn | Event::Tokens | Event::ContextCap
113
- # Silent: UserTurn echoes just-typed input; Tokens/ContextCap are
114
- # TokenLog's. (Non-streaming deltas no-op in their branches above.)
142
+ in Event::UserTurn | Event::Tokens
143
+ # Silent: UserTurn echoes just-typed input; Tokens are TokenLog's. (Non-streaming deltas no-op in their branches above.)
115
144
  else
116
145
  # Any other event — notably a gem *domain* event — renders via its
117
146
  # own to_s; core needs no knowledge of the type. A richer host
@@ -120,7 +149,7 @@ module Pikuri
120
149
  end
121
150
  end
122
151
 
123
- # @return [String] short label for {Agent#to_s}; appends
152
+ # @return [String] short label for {ListenerList#to_s}; appends
124
153
  # each non-default knob (+padding+, +streaming+) so the
125
154
  # default form stays +"Terminal"+
126
155
  def to_s
@@ -139,85 +168,25 @@ module Pikuri
139
168
  # @param text [String]
140
169
  # @return [void]
141
170
  def println(text)
142
- clear_transient
143
171
  puts text
144
172
  @at_line_start = true
145
173
  end
146
174
 
147
- # A gem domain event, defanged and dimmed — an {Event::Transient} one
148
- # rewriting a single line rather than appending to the log.
175
+ # A gem domain event as one defanged, dimmed line.
149
176
  #
150
177
  # @param event [Object] any event variant this listener does not style.
151
178
  # @return [void]
152
179
  def domain_event(event)
153
180
  text = Sanitizer.sanitize(event.to_s.gsub(/\s+/, ' ').strip).text
154
- return dim_line(text) unless event.is_a?(Event::Transient)
155
-
156
- transient(text, done: event.done)
157
- end
158
-
159
- # @param text [String] sanitized and flattened.
160
- # @return [void]
161
- def dim_line(text)
162
181
  println(indent(Rainbow("· #{text}").color(85, 85, 85)))
163
182
  end
164
183
 
165
- # Rewrite the in-place line, or retire it.
166
- #
167
- # Off a terminal it degrades to the final state only, as an ordinary line:
168
- # a stream of +\r+ into a file is one unreadable mega-line, and a cold
169
- # index emits hundreds of updates.
170
- #
171
- # @param text [String] sanitized and flattened.
172
- # @param done [Boolean] the sequence is over, so the line goes away.
173
- # @return [void]
174
- def transient(text, done:)
175
- unless $stdout.tty?
176
- dim_line(text) if done
177
- return
178
- end
179
-
180
- clear_transient
181
- return if done
182
-
183
- print(Rainbow(cut(indent("· #{text}"))).color(85, 85, 85))
184
- $stdout.flush
185
- @transient = true
186
- @at_line_start = false
187
- end
188
-
189
- # Erase the in-place line so ordinary output does not land mid-bar.
190
- #
191
- # @return [void]
192
- def clear_transient
193
- return unless @transient
194
-
195
- print("\r\e[K")
196
- @transient = false
197
- @at_line_start = true
198
- end
199
-
200
- # Fit +text+ in one row, because a line that wraps leaves its tail behind
201
- # the carriage return that was supposed to erase it.
202
- #
203
- # @param text [String]
204
- # @return [String]
205
- def cut(text)
206
- width = begin
207
- $stdout.winsize[1]
208
- rescue StandardError
209
- 80
210
- end
211
- text.length < width ? text : "#{text[0, width - 2]}…"
212
- end
213
-
214
184
  # Emit a newline as a stream terminator and reset line-state — the
215
185
  # {Event::Thinking}/{Event::Assistant} bookend in streaming mode, where
216
186
  # the content already rendered via deltas.
217
187
  #
218
188
  # @return [void]
219
189
  def terminate_stream
220
- clear_transient
221
190
  puts
222
191
  @at_line_start = true
223
192
  end
@@ -232,8 +201,6 @@ module Pikuri
232
201
  def stream_fragment(text)
233
202
  return if text.nil? || text.empty?
234
203
 
235
- clear_transient
236
-
237
204
  if @padding.zero?
238
205
  print(text)
239
206
  @at_line_start = text.end_with?("\n")
@@ -263,23 +230,63 @@ module Pikuri
263
230
  text.to_s.each_line.map { |line| prefix + line }.join
264
231
  end
265
232
 
266
- # Flatten whitespace and cap to {MAX_TOOL_RESULT_CHARS}; a truncated
267
- # result's byte-count suffix distinguishes "returned exactly this" from
268
- # "returned much more, you're seeing a slice."
233
+ # The +Name(argument)+ half of a tool-call line, the argument capped to
234
+ # whatever the row has left — a +command+ can be a 4 kB script and a
235
+ # +path+ a very long one, and only a renderer knows its width.
236
+ #
237
+ # tool_call_line('Write', 'lib/shared/config.rb') # => "Write(lib/shared/config.rb)"
238
+ # tool_call_line('Status', '') # => "Status"
239
+ #
240
+ # @param display_name [String] see {Pikuri::Tool#display_name}
241
+ # @param argument [String] see {Pikuri::Tool#describe_call}
242
+ # @return [String]
243
+ def tool_call_line(display_name, argument)
244
+ name = defang(display_name, MAX_SUMMARY_CHARS)
245
+ return name if argument.to_s.empty?
246
+
247
+ # "→ ", the parens, and the padding are all on this row too.
248
+ budget = terminal_width - @padding - name.length - 5
249
+ "#{name}(#{defang(argument, [budget, MIN_ARGUMENT_CHARS].max)})"
250
+ end
251
+
252
+ # Flatten whitespace, defang, and cap to +limit+ — every display string
253
+ # off the event stream goes through this.
254
+ #
255
+ # Whitespace flattening is safe here (a passive status line, not an
256
+ # approval artifact); {Pikuri::Sanitizer} is what stops a path carrying
257
+ # +ESC[+ or a CR from recoloring or overwriting the transcript, now that
258
+ # these strings no longer pass through +inspect+. Its warnings are
259
+ # dropped — they belong at a confirmation prompt.
269
260
  #
270
- # Whitespace is flattened first (fine — this passive echo is a status
271
- # line, not an approval artifact), then run through {Pikuri::Sanitizer}
272
- # so a tool observation can't smuggle an ESC/control byte into this
273
- # line. Its warnings are dropped (they belong at a confirmation prompt).
261
+ # @param text [String, nil]
262
+ # @param limit [Integer] max characters, +…+ marking a cut
263
+ # @return [String]
264
+ def defang(text, limit)
265
+ flattened = Sanitizer.sanitize(text.to_s.gsub(/\s+/, ' ').strip).text
266
+ return flattened if flattened.length <= limit
267
+
268
+ "#{flattened[0, limit - 1]}…"
269
+ end
270
+
271
+ # Escape the {PROSE_SUSPECT} bytes in Sanitizer's notation, +\x1b+ /
272
+ # +\u{202e}+; per character, so an escape split across two streamed
273
+ # fragments is caught in whichever half its ESC lands.
274
274
  #
275
- # @param content [String] tool observation
276
- # @return [String] single-line display form, possibly truncated
277
- def truncate_tool_result(content)
278
- original_bytes = content.to_s.bytesize
279
- flattened = Sanitizer.sanitize(content.to_s.gsub(/\s+/, ' ').strip).text
280
- return flattened if flattened.length <= MAX_TOOL_RESULT_CHARS
275
+ # @param text [String] model- or host-authored prose
276
+ # @return [String]
277
+ def defang_prose(text)
278
+ text.gsub(PROSE_SUSPECT) do |ch|
279
+ cp = ch.ord
280
+ cp >= 0x202a ? format('\\u{%04x}', cp) : format('\\x%02x', cp)
281
+ end
282
+ end
281
283
 
282
- "#{flattened[0, MAX_TOOL_RESULT_CHARS]}… (#{original_bytes} bytes total)"
284
+ # @return [Integer] terminal columns; 80 when stdout has no window size
285
+ # (a pipe, a file, a captured StringIO).
286
+ def terminal_width
287
+ $stdout.winsize[1]
288
+ rescue StandardError
289
+ 80
283
290
  end
284
291
  end
285
292
  end
@@ -7,25 +7,25 @@ module Pikuri
7
7
  # turn via +Pikuri.logger_for('Tokens')+ — a running headline to catch
8
8
  # growth before the provider raises
9
9
  # +RubyLLM::ContextLengthExceededError+. Consumes {Event::Tokens} (one
10
- # line each), {Event::ContextCap} (caches the cap, refreshed on a model
11
- # switch), and {Event::Reset} (zero the snapshot, see {#reset_snapshot});
10
+ # line each), {Event::HistoryLoaded} (seed the snapshot, see
11
+ # {#seed_snapshot}) and {Event::HistoryCompacted} (a status line only);
12
12
  # every other variant is a no-op.
13
13
  #
14
14
  # == Log line shape
15
15
  #
16
- # msg #1: ctx=6.8k Δ+6.8k ↑6.8k ↓0.0k # no cap
17
- # msg #2: ctx=8.4k/32.0k Δ+1.6k ↑1.0k ↓0.6k # cap 32k
16
+ # msg #1: ctx=6.8k Δ+6.8k ↑6.8k ↓0.0k
17
+ # msg #2: ctx=8.4k Δ+1.6k ↑1.0k ↓0.6k
18
18
  # [researcher 0] msg #1: ctx=4.2k ... # sub-agent (Agent#id)
19
19
  #
20
20
  # +ctx+ is the through-this-turn snapshot (+input + cached +
21
- # cache_creation + output+; see {Event::Tokens}), suffixed +/<cap>+ when
22
- # {#context_window_cap} is set. +Δ+ is the signed climb between turns
21
+ # cache_creation + output+; see {Event::Tokens}), in absolute tokens: a
22
+ # host that knows the model's cap ({Agent::ChatTransport#context_window}) shows
23
+ # it beside. +Δ+ is the signed climb between turns
23
24
  # (equal to +ctx+ on msg #1); +↑+/+↓+ are this turn's input/output
24
25
  # (Claude Code's convention). Sizes are 1024-scaled with a +k+ suffix.
25
26
  #
26
27
  # One instance per conversation (the snapshot is instance state);
27
- # sub-agents and the synthesizer get a fresh zeroed one via
28
- # {#for_sub_agent}.
28
+ # sub-agents get a fresh zeroed one via {#for_sub_agent}.
29
29
  class TokenLog < Base
30
30
  # Subsystem logger; the per-turn line is +INFO+. Level via
31
31
  # +PIKURI_LOG_TOKENS+ or +PIKURI_LOG+.
@@ -40,14 +40,6 @@ module Pikuri
40
40
  # @return [Integer]
41
41
  attr_reader :context_window_size
42
42
 
43
- # Model's context-window cap, or +nil+ if no source supplied one (see
44
- # {Agent::ContextWindowDetector}). When set, +ctx+ renders as
45
- # +<used>/<cap>+. Picked off the one-shot {Event::ContextCap}; a bare
46
- # instance (tests, {#for_sub_agent}) defaults to +nil+.
47
- #
48
- # @return [Integer, nil]
49
- attr_accessor :context_window_cap
50
-
51
43
  # @return [String] owning agent's id ({Agent#id}); empty for the main
52
44
  # agent, set by {#for_sub_agent} so log lines get an +[<id>] + prefix.
53
45
  attr_reader :id
@@ -57,7 +49,7 @@ module Pikuri
57
49
  # {#id} / {#on_status_line} and choose their own presentation). Empty
58
50
  # until the first {Event::Tokens}. Hosts surfacing the snapshot in
59
51
  # their own UI (a TUI footer) read this; hosts wanting to be pushed set
60
- # {#on_status_line}.
52
+ # {#on_status_line}. Why these live here: +D_token_log_status_line+.
61
53
  #
62
54
  # Safe to read from any thread (a single +String+ ivar read); a reader
63
55
  # may briefly see the previous turn's line mid-{#on_event}, acceptable
@@ -91,7 +83,6 @@ module Pikuri
91
83
  @id = id
92
84
  @msg = 0
93
85
  @context_window_size = 0
94
- @context_window_cap = nil
95
86
  @status_line = ''
96
87
  @on_status_line = nil
97
88
  end
@@ -99,8 +90,7 @@ module Pikuri
99
90
  # Sub-agent variant: a fresh +TokenLog+ with a zeroed snapshot so the
100
91
  # sub-agent tracks its own +RubyLLM::Chat+, carrying the sub-agent's
101
92
  # +id:+ (for the +[<id>] + prefix) and the {#on_status_line} observer
102
- # by reference. The cap stays +nil+ — the sub-agent's own
103
- # {Event::ContextCap} refills it.
93
+ # by reference.
104
94
  #
105
95
  # @param id [String] sub-agent's id
106
96
  # @return [TokenLog]
@@ -116,43 +106,28 @@ module Pikuri
116
106
  case event
117
107
  in Event::Tokens => tokens
118
108
  log_tokens(tokens)
119
- in Event::ContextCap(cap:)
120
- @context_window_cap = cap
121
- in Event::Reset
122
- reset_snapshot
123
109
  in Event::HistoryLoaded(tokens:)
124
110
  seed_snapshot(tokens)
111
+ in Event::HistoryCompacted(messages_before:, messages_after:)
112
+ # The snapshot stays, so the next reply's Δ shows what the compaction freed.
113
+ @status_line = "compacted: #{messages_before} → #{messages_after} msgs, " \
114
+ "ctx was #{format_k(@context_window_size)}"
115
+ @on_status_line&.call(@id, @status_line)
125
116
  else
126
117
  # Every other variant: no-op.
127
118
  end
128
119
  end
129
120
 
130
- # @return [String] short label for {Agent#to_s}, including
131
- # the current context-window size (with cap suffix when
132
- # set)
121
+ # @return [String] short label for {ListenerList#to_s}, including
122
+ # the current context-window size
133
123
  def to_s
134
- "TokenLog(ctx=#{format_ctx})"
124
+ "TokenLog(ctx=#{format_k(@context_window_size)})"
135
125
  end
136
126
 
137
127
  private
138
128
 
139
- # Zero the running snapshot on {Event::Reset} (host cleared the
140
- # conversation): message counter, running size, and status line reset;
141
- # the cap stays (a property of the unchanged model). The blanked line
142
- # is pushed to {#on_status_line} so a footer clears at once.
143
- #
144
- # @return [void]
145
- def reset_snapshot
146
- @msg = 0
147
- @context_window_size = 0
148
- @status_line = ''
149
- @on_status_line&.call(@id, @status_line)
150
- nil
151
- end
152
-
153
129
  # Restore the running size from a conversation just loaded off disk
154
- # ({Event::HistoryLoaded}), which always arrives right after the
155
- # {Event::Reset} that zeroed it. Without this the footer reads +0.0k+
130
+ # ({Event::HistoryLoaded}). Without this the footer reads +0.0k+
156
131
  # against 40k of restored history until the next reply corrects it.
157
132
  #
158
133
  # The message counter deliberately stays at zero: it counts replies
@@ -168,7 +143,7 @@ module Pikuri
168
143
 
169
144
  @context_window_size = tokens.input.to_i + tokens.cached.to_i +
170
145
  tokens.cache_creation.to_i + tokens.output.to_i
171
- @status_line = "restored: ctx=#{format_ctx}"
146
+ @status_line = "restored: ctx=#{format_k(@context_window_size)}"
172
147
  @on_status_line&.call(@id, @status_line)
173
148
  nil
174
149
  end
@@ -197,16 +172,7 @@ module Pikuri
197
172
 
198
173
  def format_line(input, output, delta)
199
174
  sign = delta.negative? ? '-' : '+'
200
- "msg ##{@msg}: ctx=#{format_ctx} Δ#{sign}#{format_k(delta.abs)} ↑#{format_k(input)} ↓#{format_k(output)}"
201
- end
202
-
203
- # +<used>+ with no cap, +<used>/<cap>+ with one. Shared by
204
- # {#format_line} and {#to_s}.
205
- def format_ctx
206
- base = format_k(@context_window_size)
207
- return base if @context_window_cap.nil?
208
-
209
- "#{base}/#{format_k(@context_window_cap)}"
175
+ "msg ##{@msg}: ctx=#{format_k(@context_window_size)} Δ#{sign}#{format_k(delta.abs)} ↑#{format_k(input)} ↓#{format_k(output)}"
210
176
  end
211
177
 
212
178
  # Format a token count as a 1024-scaled +k+-suffixed string
@@ -8,7 +8,7 @@ module Pikuri
8
8
  # {Event} variants it cares about; everything else flows through unobserved.
9
9
  #
10
10
  # These are *pure consumers*: no listener writes back into the stream
11
- # (emission is the +Agent+'s and {Agent::ExtensionContext#emit_event}'s job)
11
+ # (emission is the +Agent+'s and {Agent::Configurator#emit_event}'s job)
12
12
  # or reaches into ruby_llm's callbacks (that's {Agent}'s). Host-facing signal
13
13
  # holders (step budget, cancel flag, input queue) are *controls* under
14
14
  # {Pikuri::Agent::Control}, not listeners — they never appear in a
@@ -29,10 +29,10 @@ module Pikuri
29
29
  #
30
30
  # @param event [Event::UserTurn, Event::Thinking, Event::ThinkingDelta,
31
31
  # Event::Assistant, Event::AssistantDelta, Event::ToolCall,
32
- # Event::ToolResult, Event::Tokens, Event::ContextCap,
33
- # Event::FallbackNotice, Event::Cancelled, Object] a core
32
+ # Event::ToolResult, Event::Tokens, Event::ModelSwitched,
33
+ # Event::Cancelled, Object] a core
34
34
  # loop-narration variant, or a gem domain event via
35
- # {Agent::ExtensionContext#emit_event} (e.g. +Pikuri::Tasks::ListChanged+)
35
+ # {Agent::Configurator#emit_event} (e.g. a task list's +ListChanged+)
36
36
  # @return [void]
37
37
  def on_event(event); end
38
38
  end
@@ -2,30 +2,36 @@
2
2
 
3
3
  module Pikuri
4
4
  class Agent
5
- # Listener-list value object an {Agent} owns: wraps an +Array+ of
6
- # {Listener::Base} and fans {#emit} out to each. {Agent#initialize} stores
7
- # one and is the sole caller of {#emit}.
5
+ # The composite listener an {Agent} owns: fans {#on_event} out to every
6
+ # wrapped {Listener::Base}, in registration order.
8
7
  #
9
- # One job: fan out. The +Agent+ wires ruby_llm's callbacks itself, the
10
- # context cap rides the stream as a one-shot {Event::ContextCap}, and the
11
- # sub-agent derivation rule lives in {#for_sub_agent}. Controls are not
12
- # listeners and don't appear here.
13
- class ListenerList
8
+ # list = ListenerList.new([Listener::Terminal.new, Listener::TokenLog.new])
9
+ # list.on_event(event) # both see it
10
+ # child = list.for_sub_agent(id: 'sub_agent 0') # the sub-agent's list
11
+ #
12
+ # Being a listener itself, a list nests in another like any leaf, and
13
+ # {#for_sub_agent} recurses into it.
14
+ class ListenerList < Listener::Base
14
15
  # @param listeners [Array<Listener::Base>] listeners that
15
16
  # define +on_event(event)+
16
17
  def initialize(listeners)
18
+ super()
17
19
  @listeners = listeners.dup
18
20
  end
19
21
 
20
- # Dispatch one event to every listener, in registration order. Exactly two
21
- # callers: {Agent} (loop-narration {Event}s) and
22
- # {ExtensionContext#emit_event} (domain events); listeners never call it —
23
- # the stream is one-way.
22
+ # @param listener [Listener::Base]
23
+ # @return [void]
24
+ def add(listener)
25
+ @listeners << listener
26
+ nil
27
+ end
28
+
29
+ # Dispatch one event to every listener, in registration order.
24
30
  #
25
31
  # @param event [Object] an {Agent::Event} variant or a gem domain event
26
32
  # (an immutable value, by convention a +Data+)
27
33
  # @return [void]
28
- def emit(event)
34
+ def on_event(event)
29
35
  @listeners.each { |l| l.on_event(event) }
30
36
  end
31
37
 
@@ -0,0 +1,102 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Pikuri
4
+ class Agent
5
+ # Runs an +around_request:+ hook around every LLM HTTP request, by sitting
6
+ # in ruby_llm's +instrumenter+ slot on one +RubyLLM::Context+ — an agent's
7
+ # own, or any other connection that takes the same hook:
8
+ #
9
+ # RubyLLM.context do |c|
10
+ # c.openai_api_base = base
11
+ # RequestInstrumenter.install(c, hook: around_request, api_base: base, cancellable: nil)
12
+ # end
13
+ #
14
+ # What a hook looks like is on {Agent#initialize}. {.install} is the one
15
+ # place the slot is assigned: it holds a single instrumenter, so a second
16
+ # assignment would silently displace the hook.
17
+ #
18
+ # Only +request.ruby_llm+ reaches the hook. Every other event ruby_llm emits
19
+ # (+chat.ruby_llm+, +tool_call.ruby_llm+, ...) passes straight through —
20
+ # +chat.ruby_llm+ wraps ruby_llm's *whole* recursive loop, tool calls
21
+ # included, so hooking it would bracket a turn, and a throttle permit held
22
+ # that long deadlocks a parent against the sub-agent its tool spawns.
23
+ #
24
+ # == Implementation details
25
+ #
26
+ # One +request.ruby_llm+ block is exactly one HTTP request *including its
27
+ # streamed response* — measured, not assumed: every delta chunk of a
28
+ # streamed completion landed inside one block (ruby_llm streams through
29
+ # Faraday's +on_data+, driven from inside the +post+), and a forced
30
+ # +Faraday::TimeoutError+ retried inside that same block. So the hook spans
31
+ # the generation and ruby_llm's +retry_interval+ backoff, never just the
32
+ # first byte. Measurements: +design/decisions.md+ +D_llm_request_throttle+.
33
+ #
34
+ # Blocking inside an *instrumentation* hook is a semantic stretch — the name
35
+ # says observe, a throttle gates — accepted because the contract ruby_llm
36
+ # documents is "yield and return the block's result", which is all a gate
37
+ # needs.
38
+ #
39
+ # Immutable.
40
+ class RequestInstrumenter
41
+ # The one instrumented event that is exactly one HTTP request.
42
+ REQUEST_EVENT = 'request.ruby_llm'
43
+
44
+ # Install +hook+ on +config+'s instrumenter slot, chaining whatever it
45
+ # displaces (see +chain+ on {#initialize}).
46
+ #
47
+ # @param config [RubyLLM::Configuration] a context's config, inside its
48
+ # +RubyLLM.context+ block.
49
+ # @param hook [#call] an +around_request:+ hook.
50
+ # @param api_base [String, nil] the base URL the connection dials.
51
+ # @param cancellable [Control::Cancellable, nil] the turn's token, or
52
+ # +nil+ when no turn owns the requests.
53
+ # @return [RequestInstrumenter] the installed instrumenter.
54
+ def self.install(config, hook:, api_base:, cancellable:)
55
+ config.instrumenter = new(hook: hook, api_base: api_base, cancellable: cancellable,
56
+ chain: config.instrumenter)
57
+ end
58
+
59
+ # @param hook [#call] an +around_request:+ hook
60
+ # @param api_base [String, nil] the base URL the connection dials, handed
61
+ # to +hook+
62
+ # @param cancellable [Control::Cancellable, nil] handed to +hook+; +nil+
63
+ # when no turn owns the requests
64
+ # @param chain [#instrument, nil] the instrumenter this one displaces —
65
+ # +RubyLLM.context+ dups the global config, so a host that installed
66
+ # +ActiveSupport::Notifications+ would otherwise have it silently
67
+ # clobbered. Every event is delegated to it, hooked or not. Anything not
68
+ # answering +#instrument+ is dropped, as ruby_llm itself does.
69
+ def initialize(hook:, api_base:, cancellable:, chain: nil)
70
+ @hook = hook
71
+ @api_base = api_base
72
+ @cancellable = cancellable
73
+ @chain = chain if chain.respond_to?(:instrument)
74
+ freeze
75
+ end
76
+
77
+ # ruby_llm's instrumenter protocol: run the block, return its value —
78
+ # inside the hook when +name+ is {REQUEST_EVENT}.
79
+ #
80
+ # @param name [String] the event name, e.g. +"request.ruby_llm"+
81
+ # @param payload [Hash, nil] ruby_llm's event payload, forwarded verbatim
82
+ # @yield the work being instrumented
83
+ # @return [Object] the block's value, or +nil+ when called without a block
84
+ def instrument(name, payload = nil, &block)
85
+ return pass(name, payload, &block) unless name.to_s == REQUEST_EVENT
86
+
87
+ @hook.call(@api_base, @cancellable) { pass(name, payload, &block) }
88
+ end
89
+
90
+ private
91
+
92
+ # @param name [String]
93
+ # @param payload [Hash, nil]
94
+ # @return [Object] the block's value
95
+ def pass(name, payload, &block)
96
+ return @chain.instrument(name, payload, &block) if @chain
97
+
98
+ block&.call
99
+ end
100
+ end
101
+ end
102
+ end