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
@@ -3,152 +3,76 @@
3
3
  module Pikuri
4
4
  class Agent
5
5
  module Listener
6
- # Logs the conversation's context-window consumption per
7
- # assistant turn via +Pikuri.logger_for('Tokens')+. Consumes
8
- # {Event::Tokens} (one log line per emission) and
9
- # {Event::ContextCap} (the cap, picked off and cached —
10
- # refreshed if a later {Event::ContextCap} arrives after a
11
- # model switch); every other event variant is a no-op. A
12
- # switch does not reset the running size or message count: the
13
- # next {Event::Tokens} self-corrects the headline to the new
14
- # model's count.
15
- #
16
- # Existence rationale: catch context-window growth before the
17
- # provider raises +RubyLLM::ContextLengthExceededError+.
18
- # +ctx+ is the headline number — tokens consumed by the
19
- # conversation *through* this turn: this turn's prompt plus
20
- # its reply, both of which the model will re-process on the
21
- # next turn. The +Δ+ field shows the climb between turns;
22
- # +↑+ / +↓+ are the per-turn input / output sizes that drove
23
- # it (matching Claude Code's convention: +↑+ is what's sent
24
- # to the model, +↓+ is what comes back).
25
- #
26
- # == State and scope
27
- #
28
- # The latest snapshot lives on the instance, so one
29
- # +TokenLog+ is per-conversation. Sub-agents (with their own
30
- # +RubyLLM::Chat+) get a fresh instance via {#for_sub_agent}
31
- # (dispatched by {ListenerList#for_sub_agent}) so their
32
- # counts log against their own chat. The synthesizer rescue
33
- # gets a derived list via the same hook because its synth
34
- # chat is also fresh.
6
+ # Logs the conversation's context-window consumption per assistant
7
+ # turn via +Pikuri.logger_for('Tokens')+ — a running headline to catch
8
+ # growth before the provider raises
9
+ # +RubyLLM::ContextLengthExceededError+. Consumes {Event::Tokens} (one
10
+ # line each), {Event::HistoryLoaded} (seed the snapshot, see
11
+ # {#seed_snapshot}) and {Event::HistoryCompacted} (a status line only);
12
+ # every other variant is a no-op.
35
13
  #
36
14
  # == Log line shape
37
15
  #
38
- # Without a cap (no {Event::ContextCap} carrying a value):
39
- #
40
16
  # msg #1: ctx=6.8k Δ+6.8k ↑6.8k ↓0.0k
41
17
  # msg #2: ctx=8.4k Δ+1.6k ↑1.0k ↓0.6k
18
+ # [researcher 0] msg #1: ctx=4.2k ... # sub-agent (Agent#id)
42
19
  #
43
- # With a cap of e.g. 32k (an {Event::ContextCap} with
44
- # +cap: 32_768+ was emitted at {Agent#initialize}):
45
- #
46
- # msg #1: ctx=6.8k/32.0k Δ+6.8k ↑6.8k ↓0.0k
20
+ # +ctx+ is the through-this-turn snapshot (+input + cached +
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
24
+ # (equal to +ctx+ on msg #1); +↑+/+↓+ are this turn's input/output
25
+ # (Claude Code's convention). Sizes are 1024-scaled with a +k+ suffix.
47
26
  #
48
- # When the owning {Agent} has a non-empty {Agent#id} (i.e. a
49
- # sub-agent), the line is prefixed with +[id] +:
50
- #
51
- # [researcher 0] msg #1: ctx=4.2k Δ+4.2k ↑4.2k ↓0.0k
52
- #
53
- # +ctx+ is the snapshot
54
- # (+input + cached + cache_creation + output+; see
55
- # {Event::Tokens}), optionally suffixed with +/<cap>+ when
56
- # {#context_window_cap} is set so the operator can see how
57
- # close the conversation is to the limit. Including +output+
58
- # makes this turn's reply visible immediately — leaving it
59
- # out would hide a long reply in the +ctx=+ headline until
60
- # the next turn pulled it in as cached prompt. +Δ+ is
61
- # signed: +Δ+X+ for growth, +Δ-X+ for shrinkage (legitimate
62
- # if ruby_llm ever prunes between turns). On the first
63
- # message the baseline is implicitly zero, so +Δ+ equals
64
- # +ctx+. Sizes are scaled by 1024 and shown with one
65
- # decimal + a +k+ suffix.
27
+ # One instance per conversation (the snapshot is instance state);
28
+ # sub-agents get a fresh zeroed one via {#for_sub_agent}.
66
29
  class TokenLog < Base
67
- # Subsystem logger; the per-turn context-window line is
68
- # emitted at +INFO+ level. Set its level with
69
- # +PIKURI_LOG_TOKENS+ or the global +PIKURI_LOG+.
30
+ # Subsystem logger; the per-turn line is +INFO+. Level via
31
+ # +PIKURI_LOG_TOKENS+ or +PIKURI_LOG+.
70
32
  #
71
33
  # @return [Logger]
72
34
  LOGGER = Pikuri.logger_for('Tokens')
73
35
 
74
- # Tokens consumed by the conversation through the most
75
- # recent turn — this turn's prompt plus its reply, which
76
- # together make up the bulk of what the next turn will
77
- # re-process. Equals +input + cached + cache_creation +
78
- # output+ from the latest {Event::Tokens}. Zero until the
79
- # first {Event::Tokens} arrives.
36
+ # Tokens consumed by the conversation through the most recent turn
37
+ # (+input + cached + cache_creation + output+ from the latest
38
+ # {Event::Tokens}). Zero until the first arrives.
80
39
  #
81
40
  # @return [Integer]
82
41
  attr_reader :context_window_size
83
42
 
84
- # Model's context-window cap, or +nil+ if no source could
85
- # supply one (see {Agent::ContextWindowDetector}). When
86
- # set, the +ctx=+ field renders as +ctx=<used>/<cap>+
87
- # instead of just +ctx=<used>+. {Agent#initialize} emits a
88
- # one-shot {Event::ContextCap} at construction; this
89
- # listener picks the value off it and caches it here. An
90
- # instance constructed bare (e.g. in tests, or by
91
- # {#for_sub_agent}) defaults to +nil+.
92
- #
93
- # @return [Integer, nil]
94
- attr_accessor :context_window_cap
95
-
96
- # @return [String] owning agent's id ({Agent#id}). Empty by
97
- # default (main agent); set by {#for_sub_agent} from the
98
- # sub-agent's generated id so the log lines can be
99
- # prefixed with +[<id>] +. Read-only — for a sub-agent's
100
- # listener you get a fresh instance via {#for_sub_agent}.
43
+ # @return [String] owning agent's id ({Agent#id}); empty for the main
44
+ # agent, set by {#for_sub_agent} so log lines get an +[<id>] + prefix.
101
45
  attr_reader :id
102
46
 
103
- # The most recent status line, *without* the +[<id>] +
104
- # prefix — the prefix is {LOGGER}'s concern (the log
105
- # stream interleaves agents, so its lines must carry the
106
- # id inline); consumers of this reader get the id
107
- # separately ({#id} here, the first callable parameter on
108
- # {#on_status_line}) and decide the presentation
109
- # themselves. Empty until the first {Event::Tokens} has
110
- # been processed. Hosts that
111
- # want to surface the current context-window snapshot in
112
- # their own UI (e.g. a TUI status footer) read this
113
- # instead of re-implementing the formatting. Hosts that
114
- # want to be *pushed* each new line instead of polling
115
- # set {#on_status_line}.
47
+ # The most recent status line, *without* the +[<id>] + prefix (the
48
+ # prefix is {LOGGER}'s concern; consumers get the id separately via
49
+ # {#id} / {#on_status_line} and choose their own presentation). Empty
50
+ # until the first {Event::Tokens}. Hosts surfacing the snapshot in
51
+ # their own UI (a TUI footer) read this; hosts wanting to be pushed set
52
+ # {#on_status_line}. Why these live here: +D_token_log_status_line+.
116
53
  #
117
- # Thread safety: a single instance-variable read of a
118
- # +String+ — safe to read from any thread; readers may
119
- # briefly see the previous turn's line during an in-flight
120
- # {#on_event} call, which is acceptable for a status
121
- # display.
54
+ # Safe to read from any thread (a single +String+ ivar read); a reader
55
+ # may briefly see the previous turn's line mid-{#on_event}, acceptable
56
+ # for a status display.
122
57
  #
123
58
  # @return [String]
124
59
  attr_reader :status_line
125
60
 
126
- # Optional status-line observer, +nil+ by default. When
127
- # set to a callable, it is invoked with the owning
128
- # agent's {#id} and the freshly formatted {#status_line}
129
- # after every {Event::Tokens} — the push counterpart to
130
- # polling {#status_line}, for hosts that stream the line
131
- # onward (a Sinatra SSE endpoint pushing it to the
132
- # browser, a websocket, a TUI redraw trigger). Fires on
133
- # whatever thread runs the owning agent's loop, so the
134
- # callable must hand off to its sink thread-safely; and
135
- # like any listener it sits on the loop's path — an
136
- # exception it raises propagates into the conversation,
137
- # so handle dead connections inside the callable.
61
+ # Optional status-line observer, +nil+ by default. When callable, it's
62
+ # invoked with the owning agent's {#id} and the freshly formatted
63
+ # {#status_line} after every {Event::Tokens} — the push counterpart to
64
+ # polling {#status_line}. Fires on the agent's loop thread, so the
65
+ # callable must hand off to its sink thread-safely; it sits on the
66
+ # loop's path, so an exception it raises propagates into the
67
+ # conversation (handle dead connections inside it).
138
68
  #
139
- # Instances derived via {#for_sub_agent} copy the
140
- # observer set at derivation time, so one callable
141
- # receives parent and sub-agent lines alike; the +id+
142
- # parameter (+""+ for the main agent, the generated id
143
- # for a sub-agent) is what lets the UI route each line to
144
- # the right status row — the line itself is unprefixed
145
- # (see {#status_line}). An observer assigned *after*
146
- # a sub-agent spawned doesn't reach that sub-agent's
147
- # instance.
69
+ # {#for_sub_agent} copies the observer by reference, so one callable
70
+ # receives parent and sub-agent lines alike — the +id+ parameter routes
71
+ # each to the right row. An observer assigned *after* a sub-agent
72
+ # spawned doesn't reach that sub-agent's instance.
148
73
  #
149
- # @return [Proc, nil] called with +(id, status_line)+ —
150
- # the owning agent's id +String+ and the unprefixed
151
- # {#status_line} +String+
74
+ # @return [Proc, nil] called with +(id, status_line)+ — the agent's id
75
+ # and the unprefixed {#status_line}
152
76
  attr_accessor :on_status_line
153
77
 
154
78
  # @param id [String] owning agent's id, prepended to each
@@ -159,23 +83,14 @@ module Pikuri
159
83
  @id = id
160
84
  @msg = 0
161
85
  @context_window_size = 0
162
- @context_window_cap = nil
163
86
  @status_line = ''
164
87
  @on_status_line = nil
165
88
  end
166
89
 
167
- # Sub-agent variant: a fresh +TokenLog+ with a zeroed
168
- # snapshot so the sub-agent's context-window readings
169
- # track its own +RubyLLM::Chat+ rather than continuing the
170
- # parent's. Picks the sub-agent's +id:+ out of the
171
- # forwarded params so its log lines carry the +[<id>] +
172
- # prefix; defaults to +""+ when absent. The cap is left
173
- # +nil+ here; the sub-agent's {Agent#initialize} emits a
174
- # fresh {Event::ContextCap} immediately after construction
175
- # and this listener picks it up off the stream. The
176
- # {#on_status_line} observer carries over by reference, so
177
- # a host streaming the parent's lines sees the sub-agent's
178
- # too — distinguished by the +id+ the callable receives.
90
+ # Sub-agent variant: a fresh +TokenLog+ with a zeroed snapshot so the
91
+ # sub-agent tracks its own +RubyLLM::Chat+, carrying the sub-agent's
92
+ # +id:+ (for the +[<id>] + prefix) and the {#on_status_line} observer
93
+ # by reference.
179
94
  #
180
95
  # @param id [String] sub-agent's id
181
96
  # @return [TokenLog]
@@ -191,22 +106,48 @@ module Pikuri
191
106
  case event
192
107
  in Event::Tokens => tokens
193
108
  log_tokens(tokens)
194
- in Event::ContextCap(cap:)
195
- @context_window_cap = cap
109
+ in Event::HistoryLoaded(tokens:)
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)
196
116
  else
197
117
  # Every other variant: no-op.
198
118
  end
199
119
  end
200
120
 
201
- # @return [String] short label for {Agent#to_s}, including
202
- # the current context-window size (with cap suffix when
203
- # set)
121
+ # @return [String] short label for {ListenerList#to_s}, including
122
+ # the current context-window size
204
123
  def to_s
205
- "TokenLog(ctx=#{format_ctx})"
124
+ "TokenLog(ctx=#{format_k(@context_window_size)})"
206
125
  end
207
126
 
208
127
  private
209
128
 
129
+ # Restore the running size from a conversation just loaded off disk
130
+ # ({Event::HistoryLoaded}). Without this the footer reads +0.0k+
131
+ # against 40k of restored history until the next reply corrects it.
132
+ #
133
+ # The message counter deliberately stays at zero: it counts replies
134
+ # *this* session, and restored turns did not happen here. A history
135
+ # exported without usage (+tokens+ +nil+) leaves the zeroed snapshot
136
+ # alone rather than inventing a number.
137
+ #
138
+ # @param tokens [Event::Tokens, nil] usage of the last restored
139
+ # assistant message.
140
+ # @return [void]
141
+ def seed_snapshot(tokens)
142
+ return if tokens.nil?
143
+
144
+ @context_window_size = tokens.input.to_i + tokens.cached.to_i +
145
+ tokens.cache_creation.to_i + tokens.output.to_i
146
+ @status_line = "restored: ctx=#{format_k(@context_window_size)}"
147
+ @on_status_line&.call(@id, @status_line)
148
+ nil
149
+ end
150
+
210
151
  # Update the snapshot, write one +INFO+ line to the
211
152
  # subsystem logger, and push the line to the status-line
212
153
  # observer (when one was given at construction).
@@ -231,25 +172,11 @@ module Pikuri
231
172
 
232
173
  def format_line(input, output, delta)
233
174
  sign = delta.negative? ? '-' : '+'
234
- "msg ##{@msg}: ctx=#{format_ctx} Δ#{sign}#{format_k(delta.abs)} ↑#{format_k(input)} ↓#{format_k(output)}"
235
- end
236
-
237
- # +<used>+ when no cap is set, +<used>/<cap>+ when one is.
238
- # Shared between {#format_line} and {#to_s} so the headline
239
- # reads the same in the log stream and in {Agent#to_s}
240
- # banners.
241
- def format_ctx
242
- base = format_k(@context_window_size)
243
- return base if @context_window_cap.nil?
244
-
245
- "#{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)}"
246
176
  end
247
177
 
248
- # Format a token count as a 1024-scaled +k+-suffixed
249
- # string. +nil+ → +0.0k+; +0+ → +0.0k+; 12_453 → +12.2k+.
250
- # Uniform format keeps lines easy to scan at the cost of
251
- # looking odd for very small per-turn outputs (+↓0.0k+ on
252
- # tool-call acks).
178
+ # Format a token count as a 1024-scaled +k+-suffixed string
179
+ # (+nil+/+0+ → +0.0k+, 12_453 → +12.2k+).
253
180
  #
254
181
  # @param n [Integer, nil]
255
182
  # @return [String]
@@ -3,56 +3,36 @@
3
3
  module Pikuri
4
4
  class Agent
5
5
  # Namespace for the +Agent+'s pure event consumers — {Terminal},
6
- # {InMemoryEventList}, {TokenLog}, and any host- or test-defined
7
- # consumer. Each subclasses {Base} and overrides {Base#on_event}
8
- # to pattern-match on the {Event} variants it cares about;
9
- # everything else flows through unobserved.
6
+ # {InMemoryEventList}, {TokenLog}, and any host/test consumer. Each
7
+ # subclasses {Base} and overrides {Base#on_event} to pattern-match the
8
+ # {Event} variants it cares about; everything else flows through unobserved.
10
9
  #
11
- # == What lives here, what doesn't
12
- #
13
- # The directory holds *pure consumers*: code whose only side
14
- # effect is to react to events already emitted. No listener
15
- # writes back into the stream — emission belongs to the +Agent+
16
- # (loop narration) and to extensions via
17
- # {Agent::ExtensionContext#emit_event} (domain events) — and no
18
- # listener reaches into ruby_llm's chat callbacks (that wiring
19
- # lives in {Agent}).
20
- #
21
- # Host-facing signal holders — step budget, cancellation flag,
22
- # mid-loop user input queue — are *controls*, not listeners.
23
- # They live under {Pikuri::Agent::Control} and reach {Agent}
24
- # through dedicated kwargs on {Agent#initialize}; they never
25
- # appear in the {ListenerList} and they never receive events.
10
+ # These are *pure consumers*: no listener writes back into the stream
11
+ # (emission is the +Agent+'s and {Agent::Configurator#emit_event}'s job)
12
+ # or reaches into ruby_llm's callbacks (that's {Agent}'s). Host-facing signal
13
+ # holders (step budget, cancel flag, input queue) are *controls* under
14
+ # {Pikuri::Agent::Control}, not listeners — they never appear in a
15
+ # {ListenerList} or receive events.
26
16
  module Listener
27
- # Abstract base for event-stream consumers. Subclasses override
28
- # {#on_event} with a +case+ on the {Event} variant; the default
29
- # implementation is a no-op so a listener that cares about a
30
- # single variant doesn't have to enumerate the rest.
17
+ # Abstract base for event-stream consumers. Subclasses override {#on_event}
18
+ # with a +case+ on the {Event} variant; the default is a no-op so a
19
+ # listener caring about one variant needn't enumerate the rest.
31
20
  #
32
- # Subclasses optionally define +for_sub_agent(**params)+ to
33
- # return a variant suitable for a spawned sub-agent — a fresh
34
- # zeroed instance, the same instance shared by reference, or
35
- # +nil+ to opt out of propagation. See
36
- # {ListenerList#for_sub_agent} for the dispatch and the
37
- # per-listener semantics.
21
+ # Subclasses optionally define +for_sub_agent(**params)+ for a spawned
22
+ # sub-agent — a fresh instance, the same shared by reference, or +nil+ to
23
+ # opt out. See {ListenerList#for_sub_agent}.
38
24
  class Base
39
25
  # Single entry point for every event in the normalized stream.
40
- # Concrete subclasses override this and dispatch on the
41
- # variant (typically with a +case event in Event::X(...)+
42
- # pattern). The default implementation is a no-op so a
43
- # listener that only cares about a subset can match
44
- # selectively and let everything else fall through.
26
+ # Subclasses override and dispatch on the variant (a +case event in
27
+ # Event::X(...)+); the default no-op lets a listener match a subset and
28
+ # ignore the rest.
45
29
  #
46
- # @param event [Event::UserTurn, Event::Thinking,
47
- # Event::ThinkingDelta, Event::Assistant,
48
- # Event::AssistantDelta, Event::ToolCall,
49
- # Event::ToolResult, Event::Tokens, Event::ContextCap,
50
- # Event::FallbackNotice, Event::Cancelled, Object] one of
51
- # the core loop-narration variants, or a gem-defined
52
- # domain event emitted via
53
- # {Agent::ExtensionContext#emit_event} (e.g.
54
- # +Pikuri::Tasks::ListChanged+) — match the variants you
55
- # know, let everything else fall through
30
+ # @param event [Event::UserTurn, Event::Thinking, Event::ThinkingDelta,
31
+ # Event::Assistant, Event::AssistantDelta, Event::ToolCall,
32
+ # Event::ToolResult, Event::Tokens, Event::ModelSwitched,
33
+ # Event::Cancelled, Object] a core
34
+ # loop-narration variant, or a gem domain event via
35
+ # {Agent::Configurator#emit_event} (e.g. a task list's +ListChanged+)
56
36
  # @return [void]
57
37
  def on_event(event); end
58
38
  end
@@ -2,46 +2,42 @@
2
2
 
3
3
  module Pikuri
4
4
  class Agent
5
- # Listener-list value object that an {Agent} owns. Wraps an
6
- # +Array+ of {Listener::Base} instances and fans {#emit} out to
7
- # each; {Agent#initialize} stores one of these and is the sole
8
- # caller of {#emit}.
5
+ # The composite listener an {Agent} owns: fans {#on_event} out to every
6
+ # wrapped {Listener::Base}, in registration order.
9
7
  #
10
- # == What this is, what it isn't
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
11
  #
12
- # One job: fan out. The +Agent+ wires ruby_llm's callbacks
13
- # itself, the context-window cap rides the event stream as a
14
- # one-shot {Event::ContextCap}, and the sub-agent derivation
15
- # rule lives in {#for_sub_agent}. Controls (step budget,
16
- # cancellation flag, mid-loop input queue) are not listeners
17
- # and do not appear in this list; their sub-agent derivation
18
- # lives on each control class instead.
19
- class ListenerList
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
20
15
  # @param listeners [Array<Listener::Base>] listeners that
21
16
  # define +on_event(event)+
22
17
  def initialize(listeners)
18
+ super()
23
19
  @listeners = listeners.dup
24
20
  end
25
21
 
22
+ # @param listener [Listener::Base]
23
+ # @return [void]
24
+ def add(listener)
25
+ @listeners << listener
26
+ nil
27
+ end
28
+
26
29
  # Dispatch one event to every listener, in registration order.
27
- # Exactly two callers: {Agent} (loop-narration {Event}
28
- # variants) and {ExtensionContext#emit_event} (extension
29
- # domain events). Listeners themselves never call this; the
30
- # stream is one-way.
31
30
  #
32
- # @param event [Object] an {Agent::Event} variant or a
33
- # gem-defined domain event (an immutable value, by
34
- # convention a +Data+ instance)
31
+ # @param event [Object] an {Agent::Event} variant or a gem domain event
32
+ # (an immutable value, by convention a +Data+)
35
33
  # @return [void]
36
- def emit(event)
34
+ def on_event(event)
37
35
  @listeners.each { |l| l.on_event(event) }
38
36
  end
39
37
 
40
- # Iterate over the wrapped listeners in registration order. The
41
- # method exists so a ListenerList can be passed directly to
42
- # {Configurator#add_listeners} (used by the +agent+ tool from
43
- # +pikuri-subagents+ when seeding a sub-agent's Configurator
44
- # from the parent's list).
38
+ # Iterate the wrapped listeners in registration order — so a ListenerList
39
+ # can be passed to {Configurator#add_listeners} (the +agent+ tool seeds a
40
+ # sub-agent's Configurator from the parent's list).
45
41
  #
46
42
  # @yield [listener]
47
43
  # @yieldparam listener [Listener::Base]
@@ -50,28 +46,17 @@ module Pikuri
50
46
  @listeners.each(&block)
51
47
  end
52
48
 
53
- # Return a new {ListenerList} in which every listener has been
54
- # asked for its sub-agent variant. Each listener that defines
55
- # +for_sub_agent(**params)+ receives the forwarded +params+
56
- # and returns either +self+, a replacement instance, or +nil+
57
- # to opt out of propagation entirely — the resulting list
58
- # compacts +nil+ entries away. Listeners that don't define the
59
- # method are kept by reference (structured capture and other
60
- # stateful sinks continue to flow into the parent's instances).
61
- #
62
- # The dispatch lives on each listener so adding a new
63
- # listener type with sub-agent-specific behavior doesn't
64
- # change this class — see {Listener::Terminal#for_sub_agent}
65
- # (fresh padded instance) and
66
- # {Listener::TokenLog#for_sub_agent} (fresh, zeroed snapshot
67
- # with the forwarded +id:+).
49
+ # A new {ListenerList} where every listener has been asked for its
50
+ # sub-agent variant: a listener defining +for_sub_agent(**params)+ returns
51
+ # +self+, a replacement, or +nil+ to opt out (compacted away); listeners
52
+ # without the method are kept by reference (stateful sinks keep flowing
53
+ # into the parent's instances). The dispatch lives on each listener so a
54
+ # new listener type needs no change here — see
55
+ # {Listener::Terminal#for_sub_agent} / {Listener::TokenLog#for_sub_agent}.
68
56
  #
69
- # +params+ is a flat hash forwarded as kwargs to every
70
- # listener's hook; each listener picks the keys it cares about
71
- # and ignores the rest. The only key currently consumed by
72
- # bundled listeners is +id:+ (used by {Listener::TokenLog} to
73
- # prefix its log lines with the sub-agent's id). Calling with
74
- # no params is always valid.
57
+ # +params+ is forwarded as kwargs; each listener picks what it needs. The
58
+ # only key bundled listeners consume is +id:+ ({Listener::TokenLog}); no
59
+ # params is valid.
75
60
  #
76
61
  # @param params [Hash{Symbol => Object}]
77
62
  # @return [ListenerList]
@@ -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