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.
- checksums.yaml +4 -4
- data/README.md +16 -29
- data/lib/pikuri/agent/chat_transport.rb +114 -33
- data/lib/pikuri/agent/configurator.rb +191 -110
- data/lib/pikuri/agent/control/cancellable.rb +25 -16
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +87 -120
- data/lib/pikuri/agent/control.rb +9 -11
- data/lib/pikuri/agent/event.rb +73 -61
- data/lib/pikuri/agent/extension.rb +45 -81
- data/lib/pikuri/agent/history.rb +91 -497
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +115 -108
- data/lib/pikuri/agent/listener/token_log.rb +21 -55
- data/lib/pikuri/agent/listener.rb +4 -4
- data/lib/pikuri/agent/listener_list.rb +19 -13
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +624 -448
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/extractor/passthrough.rb +5 -2
- data/lib/pikuri/extractor.rb +43 -12
- data/lib/pikuri/file_type.rb +4 -4
- data/lib/pikuri/finalizers.rb +2 -2
- data/lib/pikuri/paths.rb +1 -1
- data/lib/pikuri/sanitizer.rb +4 -3
- data/lib/pikuri/subprocess.rb +17 -5
- data/lib/pikuri/testing.rb +122 -49
- data/lib/pikuri/tool/calculator.rb +134 -30
- data/lib/pikuri/tool/execute_context.rb +2 -2
- data/lib/pikuri/tool/parameters.rb +10 -0
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +52 -21
- data/lib/pikuri/tool.rb +298 -24
- data/lib/pikuri/trifecta/report.rb +28 -30
- data/lib/pikuri/trifecta.rb +1 -2
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +5 -11
- metadata +16 -73
- data/lib/pikuri/agent/context_window_detector.rb +0 -181
- data/lib/pikuri/agent/control/step_limit.rb +0 -95
- data/lib/pikuri/agent/extension_context.rb +0 -120
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
- data/lib/pikuri/agent/synthesizer.rb +0 -129
- data/lib/pikuri/extractor/html.rb +0 -256
- data/lib/pikuri/ruby_llm_patches.rb +0 -106
- data/lib/pikuri/tool/fetch.rb +0 -146
- data/lib/pikuri/tool/scraper.rb +0 -144
- data/lib/pikuri/tool/search/brave.rb +0 -170
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
- data/lib/pikuri/tool/search/engines.rb +0 -319
- data/lib/pikuri/tool/search/exa.rb +0 -195
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
- data/lib/pikuri/tool/search/result.rb +0 -24
- data/lib/pikuri/tool/web_scrape.rb +0 -105
- data/lib/pikuri/tool/web_search.rb +0 -133
- data/lib/pikuri/url_cache.rb +0 -96
|
@@ -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
|
|
11
|
-
# fallback notice, red cancelled, magenta
|
|
12
|
-
#
|
|
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.
|
|
17
|
-
# {
|
|
18
|
-
#
|
|
19
|
-
#
|
|
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
|
-
#
|
|
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
|
|
40
|
-
#
|
|
41
|
-
#
|
|
42
|
-
|
|
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(
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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::
|
|
107
|
-
println(indent(Rainbow("
|
|
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::
|
|
111
|
-
|
|
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 {
|
|
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
|
|
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
|
-
#
|
|
267
|
-
#
|
|
268
|
-
#
|
|
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
|
-
#
|
|
271
|
-
#
|
|
272
|
-
#
|
|
273
|
-
|
|
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
|
|
276
|
-
# @return [String]
|
|
277
|
-
def
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
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
|
-
|
|
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::
|
|
11
|
-
#
|
|
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
|
|
17
|
-
# msg #2: ctx=8.4k
|
|
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}),
|
|
22
|
-
#
|
|
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
|
|
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.
|
|
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 {
|
|
131
|
-
# the current context-window size
|
|
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=#{
|
|
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})
|
|
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=#{
|
|
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=#{
|
|
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::
|
|
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::
|
|
33
|
-
# Event::
|
|
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::
|
|
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
|
-
#
|
|
6
|
-
# {Listener::Base}
|
|
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
|
-
#
|
|
10
|
-
#
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
|
|
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
|
-
#
|
|
21
|
-
#
|
|
22
|
-
|
|
23
|
-
|
|
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
|
|
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
|