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
data/lib/pikuri/agent.rb CHANGED
@@ -3,384 +3,422 @@
3
3
  require 'ruby_llm'
4
4
 
5
5
  module Pikuri
6
- # Thin wrapper around +RubyLLM::Chat+: pikuri owns the *extension
7
- # surface* (the event-stream listeners that consume normalized
8
- # chat events, plus the controls that signal back into the loop)
9
- # while ruby_llm owns the loop itself. The Thought / Tool-call /
10
- # Observation iteration lives in +Chat#complete+; pikuri's job
11
- # is wiring ruby_llm's three callbacks at construction time,
12
- # emitting {Event} variants from each, and forwarding control
13
- # signals (step-budget tick, cancellation check, mid-loop input
14
- # drain) to the appropriate {Control}.
6
+ # Thin wrapper around +RubyLLM::Chat+: ruby_llm owns the Thought /
7
+ # Tool-call / Observation loop (+Chat#complete+); pikuri owns the
8
+ # *extension surface* — it wires ruby_llm's three callbacks at
9
+ # construction, emits {Event} variants from each, and forwards control
10
+ # signals to the {Control}s.
15
11
  #
16
- # == Roles in this file
12
+ # Two seams meet here:
17
13
  #
18
- # Two seams are visible:
14
+ # 1. **Listeners** ({ListenerList} + {Listener::Base}) — pure consumers
15
+ # of the event stream, never writing back. The +Agent+ emits every
16
+ # loop-narration {Event}; extensions emit domain events through the
17
+ # {Configurator} handed to {Extension#configure}. No public path leads
18
+ # from an +Agent+ reference to emission (no +listeners+/+chat+ reader,
19
+ # no emit method), so holding an agent grants read access and nothing
20
+ # more. New sinks are added as listeners without touching {Agent}.
21
+ # 2. **Controls** ({Control::Cancellable}, {Control::Interloper}) —
22
+ # host-facing signal holders the +Agent+ reads at fixed boundaries:
23
+ # +check!+ on every +before_tool_call+, +drain!+ once each tool batch
24
+ # is answered. Resetting the cancel flag per turn is the host's job.
19
25
  #
20
- # 1. **Listeners** ({ListenerList} + {Listener::Base} subclasses)
21
- # — pure consumers of the event stream; they never write back.
22
- # The +Agent+ emits every loop-narration {Event} variant;
23
- # extensions emit their own domain events through the
24
- # {ExtensionContext} capability facade handed to
25
- # {Extension#bind}. There is no public path from an +Agent+
26
- # reference to emission — no +listeners+ reader, no +chat+
27
- # reader, no emit method — so holding an agent grants read
28
- # access to its configuration and nothing more. New rendering
29
- # or capture targets (a web sink, a structured log) are added
30
- # as listeners without touching {Agent}.
31
- # 2. **Controls** ({Control::StepLimit}, {Control::Cancellable},
32
- # {Control::Interloper}) — host-facing signal holders. The
33
- # +Agent+ reads from them at well-defined boundaries:
34
- # {Control::StepLimit#tick!} on every +before_tool_call+ (and
35
- # {Control::StepLimit#reset!} at turn start),
36
- # {Control::Cancellable#check!} on every +before_tool_call+
37
- # (and {Control::Cancellable#reset!} at turn start),
38
- # {Control::Interloper#drain!} on every +after_tool_result+.
26
+ # "What fires when" is one grep for +@listeners.on_event+ (loop narration)
27
+ # plus {Configurator#emit_event} (domain events).
39
28
  #
40
- # The two roles are named separately so "what fires when" is a
41
- # single grep for +@listeners.emit+ in this file (loop narration)
42
- # plus the capability calls in {ExtensionContext} (domain events).
29
+ # == One agent, one conversation
43
30
  #
44
- # == Step-exhaustion policy
31
+ # An agent lives exactly as long as its conversation; nothing clears it or
32
+ # loads another conversation into it. To start over or to resume, close it
33
+ # and build a new one — from the same wiring code, with fresh extension
34
+ # instances:
45
35
  #
46
- # If the +step_limit:+ {Control::StepLimit} trips during
47
- # completion, {#run_loop} catches the +Exceeded+ exception and
48
- # applies the budget's {Control::StepLimit#on_exhausted} policy
49
- # (see that class header for how hosts pick):
36
+ # history = agent.export_history
37
+ # agent.close
38
+ # agent = Pikuri::Agent.new(transport: t, system_prompt: p, history: history) { |c| wire(c) }
50
39
  #
51
- # - +:raise+ (the default) — re-raise to the host, same shape as
52
- # the cancellation rescue below. The chat history survives and
53
- # {Control::StepLimit#reset!} fires at the next turn boundary,
54
- # so a REPL user can simply say "continue".
55
- # - +:synthesize+ — emit an {Event::FallbackNotice} and run the
56
- # {Synthesizer} prompt on a nested tools-free +Agent+ (the
57
- # same construction shape the +agent+ tool from
58
- # +pikuri-subagents+ uses for sub-agents): parent's listener
59
- # stream derived via {ListenerList#for_sub_agent} (Terminal
60
- # padded, TokenLog zeroed, recorder shared by reference),
61
- # parent's +cancellable+ shared so a user cancel during
62
- # synthesis still works, a defensive +step_limit+ at +max: 1+
63
- # (the synth has no tools and shouldn't tick it). The synth's
64
- # answer becomes the value reported by
65
- # {#last_assistant_content}, so callers (notably the +agent+
66
- # tool from +pikuri-subagents+) still get a usable reply.
40
+ # A conversation boundary must not carry state across — not the tools an
41
+ # MCP server registered mid-conversation, not the browser session behind
42
+ # them. See +design/decisions.md+ +D_agent_is_one_conversation+. Compaction
43
+ # crosses no boundary, so it rewrites the conversation in place:
44
+ # {Configurator#replace_compacted_history}.
45
+ #
46
+ # == The loop is unbounded
47
+ #
48
+ # Nothing here caps how many tool calls a turn may make. A turn ends when
49
+ # the model stops asking for tools, when {Control::Cancellable} trips, or
50
+ # when the context window fills. Why there is no budget, and what to reach
51
+ # for instead if a runaway loop ever shows up: +design/decisions.md+
52
+ # +D_no_step_limit+.
67
53
  #
68
54
  # == Cancellation rescue
69
55
  #
70
- # If the +cancellable:+ {Control::Cancellable} trips during
71
- # +Chat#ask+, {#run_loop} catches the +Cancelled+ exception,
72
- # emits an {Event::Cancelled} to the listener stream, and
73
- # re-raises. No synthesizer fallback runs: cancellation means
74
- # the user asked the agent to drop everything, so salvaging a
75
- # partial answer would be the wrong move. The caller (typically
76
- # a REPL) rescues the re-raised exception and returns control
77
- # to the user; because {#run_loop} calls
78
- # {Control::Cancellable#reset!} at the start of every turn, the
79
- # same agent instance can take a fresh turn immediately
80
- # afterwards.
56
+ # When +cancellable:+ trips during +Chat#ask+, {#run_loop} emits an
57
+ # {Event::Cancelled} and re-raises. The host calls
58
+ # {Control::Cancellable#reset!} before each turn so the same instance takes a
59
+ # fresh turn afterwards; {#run_loop} itself never clears the flag.
60
+ #
61
+ # == Threading
62
+ #
63
+ # **Thread-unsafe** — and that is the whole guarantee, deliberately no
64
+ # stronger. +@chat+, the message-identity map and the +on_close+ list are
65
+ # plain unguarded state, and {#run_loop} is not re-entrant, so a second
66
+ # thread calling in mid-turn corrupts the conversation rather than raising.
67
+ # Preventing concurrent access is the caller's job, by any means: one thread
68
+ # per agent, a mutex around every call, an actor mailbox. Nothing here is
69
+ # *confined* to a particular thread — an +Agent+ may be driven from a
70
+ # different thread on each turn, so never key anything about it off
71
+ # +Thread.current+.
72
+ #
73
+ # Several agents in one VM is then the easy case, one thread each:
74
+ #
75
+ # agents.map { |a| Thread.new { a.run_loop(user_message: task_for(a)) } }.each(&:join)
76
+ #
77
+ # Thread-safety is not the only question those N agents raise, though: they
78
+ # usually point at *one* inference server, and N simultaneous completions
79
+ # against a llama.cpp started with +--parallel 1+ queue up inside the server,
80
+ # where pikuri can neither cancel nor reorder them. The +around_request:+
81
+ # hook is where a host rations that — one permit per HTTP request, never per
82
+ # turn (see {#initialize}).
83
+ #
84
+ # Two {Control}s are the sanctioned doors *in* from another thread, which is
85
+ # why they carry locks and the agent does not: {Control::Cancellable} (stop
86
+ # the turn) and {Control::Interloper} (queue a mid-turn message, delivered at
87
+ # the next tool-batch boundary). Every other method needs the caller's own
88
+ # serialization.
89
+ #
90
+ # Tools inherit nothing from this: an instance handed to two agents is
91
+ # reachable from both, so each declares its own posture (see
92
+ # {Pikuri::Tool}'s +== Sharing+).
81
93
  class Agent
82
94
  LOGGER = Pikuri.logger_for('Agent')
83
95
  private_constant :LOGGER
84
96
 
85
- # @param transport [ChatTransport] the model-resolution bundle
86
- # (+model+ / +provider+ / +assume_model_exists+ and, for a model
87
- # on a non-global server, +api_base+ / +api_key+) the chat is
88
- # built from. Bundled into one value object so every construction
89
- # site — this constructor, the synthesizer rescue below, a
90
- # mid-conversation switch — can forward it with one assignment
91
- # instead of loose kwargs (where dropping one would silently
92
- # route the chat elsewhere or raise
93
- # +RubyLLM::ModelNotFoundError+). If +transport.model+ is
94
- # +nil+, it's filled in from +RubyLLM.config.default_model+.
95
- # @param system_prompt [String] system message prepended to
96
- # the chat. Extensions append their advertisement blocks
97
- # (e.g. +<available_skills>+, +<available_mcps>+) onto this
98
- # base via {Configurator#append_system_prompt} during the
99
- # block.
100
- # @param step_limit [Control::StepLimit, nil] step budget
101
- # control. When set, {Control::StepLimit#tick!} fires on
102
- # every +before_tool_call+ and {Control::StepLimit#reset!}
103
- # at the start of each turn; the budget's
104
- # {Control::StepLimit#on_exhausted} policy decides what
105
- # {#run_loop} does when it trips (see "Step-exhaustion
106
- # policy" in the class header). +nil+ means "no step budget"
107
- # (the agent can loop indefinitely).
108
- # @param cancellable [Control::Cancellable, nil] cancellation
109
- # control. When set, {Control::Cancellable#check!} fires on
110
- # every +before_tool_call+ and
111
- # {Control::Cancellable#reset!} at the start of each turn.
112
- # +nil+ means "not cancellable" (the host has no way to
113
- # stop a running turn except by killing the process).
114
- # @param interloper [Control::Interloper, nil] mid-loop
115
- # user-input queue. When set, the queue is drained at
116
- # every +after_tool_result+ and each item becomes a
117
- # {Event::UserTurn} with +mid_loop: true+. +nil+ means
118
- # "no mid-loop injection" (the bundled CLIs default).
119
- # @param id [String] unique identifier for this agent. Empty
120
- # for the main agent; sub-agents get persona-rooted ids
121
- # like +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+, ...
122
- # generated by the +agent+ tool from +pikuri-subagents+ from
123
- # the persona name + a per-persona counter. Forwarded to
124
- # listeners through {ListenerList#for_sub_agent} so id-aware
125
- # ones (notably {Listener::TokenLog}) can tag their output.
126
- # The word "id" is deliberate — "name" is reserved throughout
127
- # the codebase for the persona-name load (the value the LLM
128
- # picks in the +agent+ tool's +name:+ argument).
129
- # @param streaming [Boolean] opt into chunk-level streaming.
130
- # When +true+, {#run_loop} passes a per-chunk block to
131
- # +Chat#complete+, and ruby_llm requests
132
- # SSE responses from the provider — chunks are normalized
133
- # into {Event::ThinkingDelta} / {Event::AssistantDelta} on
134
- # the listener stream as they arrive. When +false+ (the
135
- # default), +Chat#ask+ runs in single-shot mode and only
136
- # the message-level {Event::Thinking} / {Event::Assistant}
137
- # bookends fire from +after_message+. Read by the +agent+
138
- # tool from +pikuri-subagents+ so spawned sub-agents inherit
139
- # the same mode without an extra kwarg.
140
- # @yield [Configurator] yields a {Configurator} that collects
141
- # tools (via {Configurator#add_tool} / {Configurator#add_tools}),
142
- # listeners (via {Configurator#add_listener} /
143
- # {Configurator#add_listeners}), system-prompt snippets (via
144
- # {Configurator#append_system_prompt}), extension instances
145
- # (via {Configurator#add_extension} — which fires +configure+
146
- # immediately), and close handlers (via
147
- # {Configurator#on_close}). The Configurator is the *only*
148
- # path for adding any of these — there are no parallel ctor
149
- # kwargs. The block is optional; an agent constructed without
150
- # one has no tools, no listeners, no extensions.
97
+ # Envelope wrapped around every injected reference block by
98
+ # {#append_reference_block}. +system-reminder+ is Claude Code's and
99
+ # grok-build's tag, deliberately — an in-distribution envelope the model has
100
+ # seen in training beats a pikuri-flavoured one it has to infer.
101
+ REFERENCE_TAG = 'system-reminder'
102
+ private_constant :REFERENCE_TAG
103
+
104
+ # A turn carried an attachment the model is known not to accept — an image
105
+ # to a llama.cpp model launched without a vision projector:
106
+ #
107
+ # agent.run_loop(user_message: "what's wrong here?", attachments: [png])
108
+ # # => UnsupportedAttachmentError: shot.png (image/png): model
109
+ # # Qwen3.8-Dense-text takes no vision input
110
+ #
111
+ # Raised before the turn is appended, so the conversation is untouched and
112
+ # the host can simply let the user retry. Sending it instead would cost far
113
+ # more than one failed turn: the server answers HTTP 500, ruby_llm retries
114
+ # that three times, and the image then stays in the history, failing every
115
+ # later turn the same way.
116
+ #
117
+ # The verdict is the transport's stated {ChatTransport#modalities}: only a
118
+ # +false+ for the attachment's kind refuses it (+image/*+ → +:vision+,
119
+ # +audio/*+ → +:audio+, +video/*+ → +:video+), so unstated means it goes
120
+ # out. A tool's refused attachment becomes a note in its result instead.
121
+ class UnsupportedAttachmentError < StandardError
122
+ # @return [Pikuri::Attachment] the refused attachment
123
+ attr_reader :attachment
124
+
125
+ # @param attachment [Pikuri::Attachment]
126
+ # @param reason [String] why, e.g. "model X takes no vision input"
127
+ def initialize(attachment, reason)
128
+ @attachment = attachment
129
+ super("#{attachment.filename} (#{attachment.mime}): #{reason}")
130
+ end
131
+ end
132
+
133
+ # What {#run_loop} answers a tool call with when its batch unwound — see
134
+ # +== Repairing an unwound tool batch+. Public so a renderer can tell one
135
+ # from a real observation, as {History::INTERRUPTED_RESULT} is for the
136
+ # on-disk shape.
137
+ #
138
+ # Paired per cause: the first unanswered call is the one that raised or was
139
+ # about to, the rest never started, and telling a skipped call "you failed"
140
+ # invites a pointless retry. A tool failure has no constant — it reports
141
+ # +"Error: <class>: <message>"+, the shape {Tool#run} already returns for a
142
+ # validation failure.
143
+ CANCELLED_RESULT = '[Cancelled by the user]'
144
+ # @see CANCELLED_RESULT
145
+ CANCELLED_SKIPPED_RESULT = '[Not executed — the user cancelled this turn]'
146
+ # @see CANCELLED_RESULT
147
+ FAILED_SKIPPED_RESULT = '[Not executed — a previous tool call in this batch failed]'
148
+
149
+ # Display line ({Event::ToolResult}'s +summary+) for a call answered by a
150
+ # repair rather than by its tool. One word for all three causes above: the
151
+ # *content* says which, and a status line only has to report that no
152
+ # observation came back.
153
+ INTERRUPTED_SUMMARY = 'Interrupted'
154
+
155
+ # @param transport [ChatTransport] model-resolution bundle (+model+ /
156
+ # +provider+ / +assume_model_exists+ and, off the global server,
157
+ # +api_base+ / +api_key+). A +nil+ +transport.model+ is filled from
158
+ # +RubyLLM.config.default_model+.
159
+ # @param system_prompt [String] base system message; the chat sees
160
+ # this plus every extension's {Extension#system_prompt_snippets},
161
+ # assembled once by {#assemble_system_prompt}.
162
+ # @param cancellable [Control::Cancellable, nil] cancellation control,
163
+ # or +nil+ for none (no way to stop a running turn but killing the
164
+ # process).
165
+ # @param around_request [#call, nil] runs around every LLM HTTP request,
166
+ # streamed response and retries included — the seam a host throttles
167
+ # requests against a small server through:
168
+ #
169
+ # around_request: ->(api_base, cancellable, &request) {
170
+ # permits_for(api_base).acquire(cancellable) { request.call }
171
+ # }
172
+ #
173
+ # Called with the base URL the connection dials (+nil+ for a fixed-base
174
+ # provider such as Anthropic) and the agent's +cancellable+; must return
175
+ # the block's value. One request, never a turn: a sub-agent's requests
176
+ # run while its parent's turn is still open. Survives a model switch, so
177
+ # it keys on +api_base+ per call rather than closing over a server. Not
178
+ # inherited by itself — whoever builds a child agent passes
179
+ # {#around_request} on, as the +agent+ tool does. +nil+ for none.
180
+ # @param id [String] unique id; empty for the main agent, persona-rooted
181
+ # for sub-agents (+"researcher 0"+, ...). Distinct from a persona's
182
+ # +name+ (the value the LLM picks in the +agent+ tool's +name:+ arg).
183
+ # @param streaming [Boolean] opt into chunk-level streaming — {#run_loop}
184
+ # passes a per-chunk block to +Chat#complete+ and normalizes chunks
185
+ # into {Event::ThinkingDelta}/{Event::AssistantDelta}. Default +false+
186
+ # (only the +after_message+ bookends fire).
187
+ # @param history [History, nil] a conversation to resume, as
188
+ # {#export_history} handed it out, or +nil+ to start empty. An extension
189
+ # reads it as {Configurator#history}; {Event::HistoryLoaded} is emitted
190
+ # once the agent is built. See {#restore_history} for what comes back
191
+ # and what is repaired on the way in.
192
+ # @yield [Configurator] the sole path for adding tools, listeners,
193
+ # extensions, and +on_close+ handlers — there are no parallel ctor
194
+ # kwargs. Optional; without it the agent has none of those.
151
195
  # @return [Agent]
196
+ # @raise [ArgumentError] if +history+ is neither +nil+ nor a {History}.
152
197
  def initialize(transport:, system_prompt:,
153
- step_limit: nil, cancellable: nil, interloper: nil,
198
+ cancellable: nil,
199
+ around_request: nil,
154
200
  id: '',
155
201
  streaming: false,
202
+ history: nil,
156
203
  &block)
204
+ unless history.nil? || history.is_a?(History)
205
+ raise ArgumentError, "expected a Pikuri::Agent::History, got #{history.class}"
206
+ end
207
+
157
208
  @transport = transport.model ? transport : transport.with(model: RubyLLM.config.default_model)
158
209
  @cancellable = cancellable
210
+ @around_request = around_request
159
211
  @closed = false
160
212
 
213
+ @system_prompt_base = system_prompt
161
214
  @system_prompt = system_prompt
162
- @step_limit = step_limit
163
- @interloper = interloper
215
+ # Built here, never passed in: a queue handed from one agent to the
216
+ # next would carry a stale mid-turn message into the new conversation.
217
+ @interloper = Control::Interloper.new
164
218
  @id = id
165
219
  @streaming = streaming
166
- @synth_answer = nil
167
220
  @on_close_handlers = []
168
- # Stashed for {#run_configure}, which runs the failure-prone
169
- # build phase below out of a separate method.
221
+ # Stashed for {#run_configure}, the failure-prone build phase.
170
222
  @block = block
223
+ @history = history
171
224
 
172
- # Register *before* the build phase so a mid-construction raise
173
- # is still recoverable: extensions arm their cleanup via
174
- # +c.on_close+ (which writes straight to +@on_close_handlers+,
175
- # see {Configurator}), and the rescue below fires whatever was
176
- # armed before the failure. On the happy path this registration
177
- # is the at-exit backstop if the host forgets {#close}; an
178
- # explicit {#close} unregisters, so the agent isn't pinned alive
179
- # until process exit.
225
+ # Register *before* the build phase so a mid-construction raise is
226
+ # recoverable: extensions arm cleanup via +c.on_close+ (straight into
227
+ # +@on_close_handlers+), and the rescue below fires whatever was armed
228
+ # before the failure. On the happy path this is the at-exit backstop
229
+ # if the host forgets {#close}; an explicit {#close} unregisters.
180
230
  Pikuri::Finalizers.register(self)
181
231
 
182
232
  begin
183
233
  run_configure
184
234
  rescue StandardError
185
- # Half-built agent (e.g. an extension's +configure+ raised
186
- # Cancelled mid-spawn). Fire the handlers armed so far, drop
187
- # out of the registry, and re-raise — no partial state leaks.
235
+ # Half-built agent: fire the armed handlers, drop out of the
236
+ # registry, re-raise — no partial state leaks.
188
237
  close
189
238
  raise
190
239
  end
191
240
  end
192
241
 
193
- # @return [ChatTransport] the resolved transport bundle this
194
- # agent was constructed with — same model id / provider /
195
- # assume-model-exists flag passed to every +RubyLLM.chat+
196
- # call originating from this agent (the main chat, the
197
- # synthesizer rescue, the +agent+ tool from
198
- # +pikuri-subagents+). Read by extensions that need to spawn
199
- # their own ruby_llm calls (e.g. MCP description synthesis,
200
- # sub-agent delegation).
242
+ # The model the next turn talks to, and what is stated about it:
243
+ #
244
+ # agent.transport.context_window # => 32768, or nil when unstated
245
+ # agent.transport.modalities # => {vision: false}, or nil when unstated
246
+ #
247
+ # The agent never probes the server, so these are exactly what the host
248
+ # stated, at construction or on a later +run_loop(transport:)+.
249
+ #
250
+ # @return [ChatTransport] with its +model+ filled from
251
+ # +RubyLLM.config.default_model+ when it was +nil+
201
252
  attr_reader :transport
202
253
 
203
- # @return [Array<Tool>] this agent's tool list in declaration
204
- # order. Read by extensions that filter against it (notably
205
- # the +agent+ tool from +pikuri-subagents+, which picks the
206
- # sub-agent's toolset from the parent's instances so any
207
- # already-bound workspace/confirmer wiring travels along).
208
- # Tools listed here are also the ones registered with
209
- # ruby_llm — the parent LLM can call any of them. Compare
210
- # with {#sub_agent_tools}.
254
+ # @return [Array<Tool>] tool list in declaration order. These are the
255
+ # tools registered with ruby_llm — the parent LLM can call any. Cf.
256
+ # {#sub_agent_tools}.
211
257
  attr_reader :tools
212
258
 
213
- # @return [Array<Tool>] tools registered via
214
- # {Configurator#add_sub_agent_tool}, in declaration order.
215
- # Invisible to the parent LLM (never sent to ruby_llm);
216
- # available only to sub-agents whose persona +tool_names+
217
- # match. See {Configurator}'s "Two tool pools" header for
218
- # the trifecta-defense rationale.
259
+ # @return [Array<Tool>] tools added via
260
+ # {Configurator#add_sub_agent_tool}, in declaration order. Never sent
261
+ # to ruby_llm (invisible to the parent LLM); available only to
262
+ # sub-agents whose persona +tool_names+ match — the trifecta defense,
263
+ # see {Configurator}.
219
264
  attr_reader :sub_agent_tools
220
265
 
221
- # @return [String] resolved model id from {#transport}.
222
- # Convenience delegator for callers that don't need the
223
- # full transport bundle.
224
- def model
225
- @transport.model
226
- end
227
-
228
- # @return [String] system prompt actually sent to the chat —
229
- # equal to the constructor's +system_prompt:+ argument plus
230
- # any snippets appended via {Configurator#append_system_prompt}
231
- # (extensions' +<available_skills>+ / +<available_mcps>+ /
232
- # +<available_agents>+, ...). Not inherited by sub-agents —
233
- # each persona owns its own system prompt verbatim.
266
+ # @return [String] system prompt actually sent — the base
267
+ # +system_prompt:+ plus every extension's
268
+ # {Extension#system_prompt_snippets}. Not inherited by sub-agents.
234
269
  attr_reader :system_prompt
235
270
 
236
- # @return [Control::StepLimit, nil] the step-budget control
237
- # this agent was constructed with, or +nil+ when none.
238
- attr_reader :step_limit
239
-
240
- # @return [Control::Cancellable, nil] the cancellation
241
- # control this agent was constructed with, or +nil+ when
242
- # none. Read by extensions that propagate cancellation to
243
- # their own LLM calls (e.g. the +agent+ tool from
244
- # +pikuri-subagents+ shares it with spawned sub-agents so
245
- # one Ctrl+C stops the tree).
271
+ # @return [Control::Cancellable, nil] the cancellation control, or
272
+ # +nil+. Extensions read it to propagate cancellation to their own
273
+ # LLM calls (the +agent+ tool shares it so one Ctrl+C stops the tree).
246
274
  attr_reader :cancellable
247
275
 
248
- # @return [Control::Interloper, nil] the mid-loop user-input
249
- # control this agent was constructed with, or +nil+ when
250
- # none.
276
+ # @return [#call, nil] the +around_request:+ hook (see {#initialize}), for
277
+ # whoever builds a child agent to pass on.
278
+ attr_reader :around_request
279
+
280
+ # The agent's own mid-loop input queue — the door a host uses to reach a
281
+ # running turn from another thread:
282
+ #
283
+ # agent.interloper.inject_user_message('also check the tests') # lands after this tool batch
284
+ #
285
+ # Drained at turn start and once each tool batch is answered.
286
+ #
287
+ # @return [Control::Interloper]
251
288
  attr_reader :interloper
252
289
 
253
- # @return [String] this agent's unique identifier — empty for
254
- # the main agent; for sub-agents, the persona-rooted id
255
- # assigned by the +agent+ tool from +pikuri-subagents+ (e.g.
256
- # +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+).
257
- # Propagated to listeners via {ListenerList#for_sub_agent(id:)}
258
- # so id-aware ones can tag output. Distinct from the persona's
259
- # +name+ (the value the LLM picks in the +agent+ tool's
260
- # +name:+ argument).
290
+ # @return [String] this agent's id — empty for the main agent,
291
+ # persona-rooted for sub-agents (+"researcher 0"+). Distinct from the
292
+ # persona +name+; propagated to listeners via
293
+ # {ListenerList#for_sub_agent} so id-aware ones tag their output.
261
294
  attr_reader :id
262
295
 
263
- # @return [Boolean] +true+ when this agent opted into
264
- # chunk-level streaming (see the +streaming:+ kwarg on
265
- # {#initialize}); +false+ otherwise. Read by extensions that
266
- # spawn their own ruby_llm calls (notably the +agent+ tool
267
- # from +pikuri-subagents+, so spawned sub-agents inherit the
268
- # same mode).
296
+ # @return [Boolean] whether this agent opted into chunk-level streaming
297
+ # (see {#initialize}'s +streaming:+).
269
298
  attr_reader :streaming
270
299
 
271
- # @return [Array<Extension>] extension instances bound to this
272
- # agent — added via {Configurator#add_extension} inside the
273
- # +Agent.new+ block. Each instance's +configure+ runs during
274
- # the block and its +bind+ runs at the end of
275
- # {#initialize}, once per registration (so once per parent
276
- # agent in the typical setup; sub-agents do not inherit
277
- # extensions).
300
+ # @return [Array<Extension>] extensions added to this agent, whose
301
+ # +configure+ ran during the +Agent.new+ block. Not inherited by
302
+ # sub-agents.
278
303
  attr_reader :extensions
279
304
 
280
- # @return [Integer, nil] resolved context-window cap — the
281
- # {ChatTransport#context_window} if one was given, else what
282
- # {ContextWindowDetector} probed. +nil+ when neither produced
283
- # a value (a non-llama server with no explicit cap). Re-resolved
284
- # on every model switch (see {#run_loop}'s +transport:+). Read by
285
- # extensions that spawn their own ruby_llm calls (notably the
286
- # +agent+ tool from +pikuri-subagents+, which hands a sub-agent
287
- # +parent.transport.with(context_window: this)+ so the resolved
288
- # cap rides along without a re-probe).
289
- attr_reader :context_window_cap
290
-
291
- # Final assistant message content for the most recent
292
- # {#run_loop}. When the synthesizer rescue fired, returns its
293
- # answer; otherwise walks the underlying chat's history.
294
- # Returns +nil+ if neither source has produced an assistant
295
- # turn yet.
305
+ # Final assistant message content for the most recent {#run_loop} — the
306
+ # last +:assistant+ message in the underlying chat's history. +nil+ until
307
+ # one has been produced.
296
308
  #
297
309
  # @return [String, nil]
298
310
  def last_assistant_content
299
- return @synth_answer if @synth_answer
300
-
301
311
  last = @chat.messages.reverse.find { |m| m.role == :assistant }
302
312
  last&.content
303
313
  end
304
314
 
305
- # Run the agent loop for a single user turn. Emits an
306
- # {Event::UserTurn} with +mid_loop: false+, resets the
307
- # step-budget and cancellation controls (so a stale state
308
- # from a prior turn doesn't poison this one), and forwards
309
- # +user_message+ to {#chat} via +ask+. Returns nil; rendering
310
- # and any other observable output is the listeners'
311
- # responsibility.
312
- #
313
- # If the +step_limit+ control trips during completion, the
314
- # rescue branch applies its {Control::StepLimit#on_exhausted}
315
- # policy: +:raise+ re-raises the +Exceeded+ exception to the
316
- # host (chat history intact — the next turn's +reset!+
317
- # refreshes the budget, so "continue" just works);
318
- # +:synthesize+ emits an {Event::FallbackNotice} and runs the
319
- # {Synthesizer} prompt on a nested tools-free agent, capturing
320
- # its answer for {#last_assistant_content}. See
321
- # "Step-exhaustion policy" in the class header.
322
- #
323
- # If the +cancellable+ control trips during +ask+, the rescue
324
- # branch emits an {Event::Cancelled} and re-raises the
325
- # +Cancelled+ exception. No synthesizer fallback runs — see
326
- # the "Cancellation rescue" section in the class header.
327
- #
328
- # Subsequent calls keep building on the same chat history, so
329
- # the model sees full multi-turn context.
315
+ # Run the agent loop for one turn. With a +user_message+ or +attachments+,
316
+ # emits an {Event::UserTurn} (+mid_loop: false+) and appends it; with
317
+ # neither, runs a *bare* turn against whatever the conversation + drained injections
318
+ # already hold — the case a host uses after loading a skill on its own
319
+ # initiative, so the agent reacts to it, or for a mid-turn message that
320
+ # arrived after the last tool batch (+D_mid_turn_user_message+). Drains any pending
321
+ # {Control::Interloper} injections, then +complete+s the chat. Output is
322
+ # the listeners' job; subsequent calls build on the same history.
323
+ #
324
+ # agent.run_loop(user_message: "what's wrong here?",
325
+ # attachments: [Pikuri::Attachment.new(mime: 'image/png', filename: 'shot.png', bytes: png)])
326
+ #
327
+ # An attachment-only turn is not blank: it goes out with no text part
328
+ # at all, since Anthropic refuses an empty one. {Extension#on_user_message}
329
+ # still fires, with +""+ and the attachments.
330
+ #
331
+ # Cancellation trips are handled per the class header's "Cancellation
332
+ # rescue". A cancel sent before this call — the host already counts the
333
+ # turn as running, its worker hasn't got here yet — ends the turn once the
334
+ # user message is recorded, before any request: the message stays in the
335
+ # history, unanswered, as after a cancel during the prefill.
330
336
  #
331
337
  # == Switching models mid-conversation
332
338
  #
333
- # Passing a +transport:+ that differs from the current one
334
- # switches the underlying chat to that model — via
335
- # +Chat#with_model+, so the history and the registered
336
- # callbacks survive — re-resolves the context-window cap, and
337
- # emits an {Event::ModelSwitched} followed by a fresh
338
- # {Event::ContextCap}. The switch is deliberately confined to
339
- # the top of this method (a private +apply_transport!+) rather
340
- # than exposed as a standalone setter: the chat is
341
- # single-thread-confined, so doing it here serializes the swap
342
- # with the turn on the loop's own thread — a background thread
343
- # mutating +with_model+'s connection mid-completion would tear
344
- # an in-flight stream. A +nil+ +transport:+ (the default) keeps
345
- # the current model. The conversation is *not* re-baselined: a
346
- # switch is the same conversation under a new model, so the
347
- # message count and running context size carry over (the next
348
- # turn's token report self-corrects to the new model's count).
349
- #
350
- # @param user_message [String] the user's request for this
351
- # turn; must not be +nil+, empty, or whitespace-only
352
- # @param transport [ChatTransport, nil] when non-+nil+ and
353
- # structurally different from the current transport, switch to
354
- # it before running the turn (see above); +nil+ keeps the
355
- # current model
356
- # @raise [ArgumentError] if +user_message+ is +nil+, empty,
357
- # or contains only whitespace — an empty turn would poison
358
- # the chat history and burn a step budget on nothing
359
- # @raise [Control::Cancellable::Cancelled] if the registered
360
- # {Control::Cancellable} was triggered during the turn;
361
- # the listener stream sees an {Event::Cancelled} first
362
- # @raise [Control::StepLimit::Exceeded] if the step budget
363
- # tripped and its policy is +:raise+ (the default)
364
- # @return [nil]
365
- def run_loop(user_message:, transport: nil)
366
- raise ArgumentError, "user_message must not be blank, got #{user_message.inspect}" \
367
- if user_message.nil? || user_message.to_s.strip.empty?
339
+ # A +transport:+ naming another model or connection switches the chat to
340
+ # it (via {#apply_transport!}) and emits {Event::ModelSwitched}. One that
341
+ # differs only in its stated facts — +context_window+, +modalities+ — is
342
+ # the same model, newly described: the agent adopts it silently, emitting
343
+ # nothing. That is how a host that probes the server hands the agent what
344
+ # it learnt:
345
+ #
346
+ # agent.run_loop(user_message: text, transport: transport.with(context_window: 32_768))
347
+ #
348
+ # The switch is confined to the top of this method because the chat is
349
+ # single-thread-confined — a background thread mutating the connection
350
+ # mid-completion would tear an in-flight stream. The conversation is
351
+ # *not* re-baselined: same conversation, new model, so message count and
352
+ # running context size carry over. +nil+ keeps the current model.
353
+ #
354
+ # == Repairing an unwound tool batch
355
+ #
356
+ # ruby_llm appends the assistant +tool_calls+ message *before* running any
357
+ # of them, so anything unwinding out of the batch — a tool raising, a
358
+ # {Control::Cancellable::Cancelled}, an untrapped +Interrupt+ — leaves
359
+ # calls no +:tool+ message answers. OpenAI and Anthropic 400 on that; a
360
+ # local llama.cpp feeds it to the chat template and the model improvises.
361
+ # So an +ensure+ answers each dangling call
362
+ # ({#repair_dangling_tool_calls!}) and the exception then propagates: a
363
+ # host that keeps the conversation gets one it can still send.
364
+ #
365
+ # +ensure+ rather than a clause per +rescue+, because it also catches what
366
+ # nobody enumerated (+Interrupt+ is no +StandardError+) and it is a no-op
367
+ # on the success path.
368
+ #
369
+ # Unlike {History#repair_interrupted_tool_calls} — the resume path, where a
370
+ # killed process leaves no clue and {History::INTERRUPTED_RESULT} has to be
371
+ # generic — the cause is in hand here and picks the wording.
372
+ #
373
+ # @param user_message [String, nil] the turn's request; +nil+/blank with
374
+ # no +attachments+ runs a bare turn (see above)
375
+ # @param attachments [Array<Pikuri::Attachment>] files shown to the model
376
+ # with the request, e.g. a screenshot
377
+ # @param transport [ChatTransport, nil] the transport this turn and later
378
+ # ones use (see above); +nil+ keeps the current one
379
+ # @raise [Control::Cancellable::Cancelled] if cancelled mid-turn (an
380
+ # {Event::Cancelled} is emitted first)
381
+ # @raise [ArgumentError] if an attachment is not a {Pikuri::Attachment}
382
+ # @raise [UnsupportedAttachmentError] if the transport's stated
383
+ # modalities refuse an attachment; nothing is appended
384
+ # @return [nil] after a turn runs
385
+ def run_loop(user_message: nil, attachments: [], transport: nil)
386
+ unless attachments.all?(Pikuri::Attachment)
387
+ raise ArgumentError, "attachments must be Pikuri::Attachments, got #{attachments.map(&:class)}"
388
+ end
368
389
 
369
390
  apply_transport!(transport) if transport
370
- @synth_answer = nil
371
- @step_limit&.reset!
372
- @cancellable&.reset!
373
- # Append the user turn, emit it, then run the memory dispatch — so
374
- # any <memory-context> the dispatch injects lands as a :system
375
- # message *after* the user turn it annotates (append-only at the
376
- # tail; see {#dispatch_ext_on_user_message}). `ask` would bundle the
377
- # user-message append with completion atomically, leaving no seam to
378
- # inject between them, so the two halves run explicitly here:
379
- # add_message + complete (the exact pair `ask` is sugar for). A raw
380
- # String content matches the interloper drain path.
381
- @chat.add_message(role: :user, content: user_message)
382
- @listeners.emit(Event::UserTurn.new(content: user_message, mid_loop: false))
383
- dispatch_ext_on_user_message(user_message)
391
+
392
+ # Deliver host-scheduled injections (e.g. a UI-loaded skill) before the
393
+ # first complete, so a freshly-scheduled block lands this turn rather
394
+ # than only after the next tool batch — ordered ahead of the user
395
+ # message appended below.
396
+ drain_interloper
397
+
398
+ text = user_message.to_s.strip.empty? ? nil : user_message
399
+ blank = text.nil? && attachments.empty?
400
+
401
+ attachments.each do |a|
402
+ reason = attachment_refusal(a)
403
+ raise UnsupportedAttachmentError.new(a, reason) if reason
404
+ end
405
+
406
+ # Append and emit the user turn before the extension dispatch, so any
407
+ # <memory-context> it injects lands *after* the turn it annotates (as a
408
+ # :user turn like every reference block, see {#append_reference_block}).
409
+ # (+ask+ bundles append+complete atomically, leaving no seam to inject
410
+ # between; the halves run explicitly instead.)
411
+ unless blank
412
+ message = { role: :user, content: text }
413
+ message[:attachments] = attachments.map(&:to_ruby_llm) unless attachments.empty?
414
+ track_message(@chat.add_message(message))
415
+ @listeners.on_event(Event::UserTurn.new(content: text.to_s, attachments: attachments, mid_loop: false))
416
+ end
417
+ # The turn's first cancellation point: a plain non-streaming turn with no
418
+ # +around_request+ has no other before its request goes out.
419
+ @cancellable&.check!
420
+ dispatch_ext_on_user_message(text.to_s, attachments) unless blank
421
+
384
422
  if @streaming
385
423
  @chat.complete(&streaming_block)
386
424
  else
@@ -388,33 +426,55 @@ module Pikuri
388
426
  end
389
427
  nil
390
428
  rescue Control::Cancellable::Cancelled
391
- @listeners.emit(Event::Cancelled.new)
429
+ @listeners.on_event(Event::Cancelled.new)
392
430
  raise
393
- rescue Control::StepLimit::Exceeded => e
394
- raise unless @step_limit&.on_exhausted == :synthesize
431
+ ensure
432
+ repair_dangling_tool_calls!($!)
433
+ end
395
434
 
396
- @synth_answer = Synthesizer.run_synthesizer(@extension_context, @chat.messages, user_message)
397
- nil
435
+ # Snapshot the conversation as a {History} — the round-trip partner of
436
+ # +Agent.new(history:)+, and the only way a conversation leaves the agent;
437
+ # storing it is the host's.
438
+ #
439
+ # history = agent.export_history
440
+ #
441
+ # The system prompt is excluded — the resuming agent assembles its own, so
442
+ # a resumed conversation gets today's, not the one that was current when
443
+ # it was exported.
444
+ #
445
+ # Attachment bytes are read here, eagerly, so the snapshot still shows
446
+ # what the model saw after the file has changed on disk.
447
+ #
448
+ # A thinking block withheld from the conversation because another model
449
+ # produced it is restored here from the message's metadata, so the record
450
+ # survives any number of resumes under a switched model.
451
+ #
452
+ # @return [History]
453
+ def export_history
454
+ exported = @chat.messages.reject { |m| m.role == :system }.map do |msg|
455
+ meta = @message_meta[msg] || { id: History.mint_id, kind: 'user' }
456
+ exported_msg = History::Message.from_ruby_llm(
457
+ msg, id: meta[:id], kind: meta[:kind],
458
+ summary: meta[:summary], tool_call_lines: meta[:tool_calls] || {}
459
+ )
460
+ meta[:thinking] ? exported_msg.with(thinking: meta[:thinking]) : exported_msg
461
+ end
462
+ History.new(messages: exported)
398
463
  end
399
464
 
400
- # Release agent-owned resources. Fires every handler registered
401
- # via {Configurator#on_close} (during the +Agent.new+ block) and
402
- # {ExtensionContext#on_close} (during {Extension#bind} or any
403
- # later hook), in LIFO order — matches Ruby +ensure+-block semantics
404
- # so handlers registered later (which may depend on handlers
405
- # registered earlier) tear down first. Each handler runs inside
406
- # its own +rescue+; an exception is logged via
407
- # +Pikuri.logger_for+ but doesn't abort the rest. Idempotent —
408
- # subsequent calls are no-ops.
465
+ # Release agent-owned resources: fire every handler registered via
466
+ # {Configurator#on_close} in LIFO order,
467
+ # so a handler that depends on an earlier one tears down first. Each runs
468
+ # in its own +rescue+ (an exception is logged, not propagated).
469
+ # Idempotent.
409
470
  #
410
471
  # @return [void]
411
472
  def close
412
473
  return if @closed
413
474
 
414
475
  @closed = true
415
- # Drop out of the process-global registry first: a deliberate
416
- # close means this agent no longer needs the at-exit fallback,
417
- # and removing the reference lets it be garbage-collected.
476
+ # Drop out of the registry first: a deliberate close no longer needs
477
+ # the at-exit fallback, and dropping the reference frees it for GC.
418
478
  Pikuri::Finalizers.unregister(self)
419
479
  @on_close_handlers.reverse_each do |handler|
420
480
  handler.call
@@ -423,197 +483,342 @@ module Pikuri
423
483
  end
424
484
  end
425
485
 
426
- # Short, single-line config dump suitable for a startup
427
- # banner or a debug print.
486
+ # This agent's lethal-trifecta picture: which legs it holds, which its
487
+ # sub-agents hold, the verdict at every node.
428
488
  #
429
- # @example
430
- # agent.to_s
431
- # # => "Agent(id=, model=qwen3-35b, tools=4, listeners=[Terminal])"
489
+ # puts agent.trifecta.render # the map a bin script prints
490
+ # agent.trifecta.tree_verdict # => :soft
432
491
  #
433
- # @return [String]
434
- def to_s
435
- "Agent(id=#{@id}, model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
492
+ # Memoized and pure, so a UI may call it as often as it likes. Nothing
493
+ # reports this for you: an Agent computes the picture and stops, because a
494
+ # library writing to a log its embedder never asked for is noise. Surfacing
495
+ # it is the host's job — the bundled +bin/pikuri-*+ scripts print
496
+ # {Trifecta::Report#render} at boot.
497
+ #
498
+ # Valid only after construction (it reads the wired tool list), and it
499
+ # reflects the tools present *then*.
500
+ #
501
+ # @return [Trifecta::Report] root of the walked tree
502
+ def trifecta
503
+ @trifecta ||= Trifecta.walk(Trifecta.build(self))
436
504
  end
437
505
 
438
506
  private
439
507
 
440
508
  # The failure-prone build phase, split out of {#initialize} so the
441
- # constructor can wrap it in a rescue and self-heal. Funnels the
442
- # +Agent.new+ block through a single {Configurator} — tools,
443
- # listeners, system-prompt snippets, extensions, and +on_close+
444
- # handlers — then wires the chat and runs the extension +bind+
445
- # sweep. The Configurator's +on_close_sink:+ is +@on_close_handlers+
446
- # itself, so a handler an extension arms via +c.on_close+ is live on
447
- # the agent the instant it's registered — that's what lets the
448
- # constructor's rescue close a half-built agent.
509
+ # constructor can wrap it in a rescue and self-heal. The chat and the
510
+ # listener list exist before the +Agent.new+ block runs, so the
511
+ # {Configurator} it receives can already act on them; the block's tools
512
+ # and system-prompt snippets are wired once it returns. The
513
+ # Configurator's +on_close_sink:+ is +@on_close_handlers+ itself, so a
514
+ # handler armed via +c.on_close+ is live the instant it's registered —
515
+ # what lets the rescue close a half-built agent.
449
516
  #
450
517
  # @return [void]
451
518
  def run_configure
452
- configurator = Configurator.new(
453
- transport: @transport,
454
- system_prompt_base: @system_prompt,
455
- id: @id,
456
- streaming: @streaming,
457
- step_limit: @step_limit,
458
- cancellable: @cancellable,
459
- interloper: @interloper,
460
- on_close_sink: @on_close_handlers
461
- )
519
+ @chat = build_chat(@transport)
520
+ @listeners = ListenerList.new([])
521
+ configurator = Configurator.new(agent: self, chat: @chat, listeners: @listeners,
522
+ history: @history, on_close_sink: @on_close_handlers)
462
523
 
463
524
  @block&.call(configurator)
464
525
 
465
526
  @tools = configurator.tools.dup
466
527
  @sub_agent_tools = configurator.sub_agent_tools.dup
467
- @listeners = ListenerList.new(configurator.listeners)
468
- configurator.system_prompt_additions.each do |snippet|
469
- @system_prompt = "#{@system_prompt}\n\n#{snippet}"
470
- end
471
528
  @extensions = configurator.extensions.dup
472
-
473
- @chat = build_chat(@transport)
529
+ # Assemble now that every extension's +configure+ has run (their
530
+ # snippets read populated state).
531
+ @system_prompt = assemble_system_prompt
474
532
  @chat.with_instructions(@system_prompt)
475
- @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool) }
476
-
477
- # Wire @chat for pikuri's event stream and controls — the
478
- # three message-level registered callbacks (+after_message+,
479
- # +before_tool_call+, +after_tool_result+). The per-chunk
480
- # streaming callback is separate because ruby_llm takes it as
481
- # a block to +Chat#complete+ rather than a registered hook —
482
- # see {#streaming_block}. Together with the +@listeners.emit+
483
- # calls in {#run_loop} / {#dispatch_ext_on_user_message} this
484
- # is the complete "which callback emits which event" map.
533
+ # One context per agent, so an opting-in +execute+ never has to nil-check
534
+ # what it was handed.
535
+ context = Tool::ExecuteContext.new(cancellable: @cancellable || Control::Cancellable::NEVER)
536
+ refusal = ->(attachment) { attachment_refusal(attachment) }
537
+ @tools.each { |t| @chat.with_tools(t.to_ruby_llm_tool(context: context, refusal: refusal)) }
538
+
539
+ # Wire @chat for the event stream and controls via ruby_llm's three
540
+ # registered callbacks. (The per-chunk streaming callback is separate
541
+ # — {#streaming_block} — since ruby_llm takes it as a block to
542
+ # +Chat#complete+, not a registered hook.) With the +@listeners.on_event+
543
+ # calls in {#run_loop}/{#dispatch_ext_on_user_message}, this is the
544
+ # complete callback→event map.
545
+ # Identity-keyed, so nothing can drift out of alignment with
546
+ # +@chat.messages+ the way a parallel array would: a message pikuri
547
+ # never saw is simply absent here, and {#export_history} mints it an id
548
+ # rather than silently pairing it with someone else's.
549
+ @message_meta = {}.compare_by_identity
550
+ # The call ruby_llm is running right now, so +after_tool_result+ — which
551
+ # receives the result *alone* — can name it, and so +after_message+ can
552
+ # put the summary on the +:tool+ message. A single slot, i.e. the
553
+ # ordering assumption, is valid only while +tool_concurrency+ stays off,
554
+ # which {Pikuri::Tool}'s +== Sharing+ asks for on separate grounds. Turn
555
+ # it on and the fix is ruby_llm's +tool_call.ruby_llm+ instrumenter
556
+ # event, whose payload carries +tool_call+ and +result+ together —
557
+ # reachable through the +instrumenter+ slot {RequestInstrumenter} already
558
+ # chains.
559
+ @pending_tool_call = nil
560
+
485
561
  @chat.after_message do |msg|
562
+ # A +:tool+ message is the one the summary computed just above belongs to.
563
+ summary = @pending_tool_call[:summary] if msg.role == :tool && @pending_tool_call
564
+ track_message(msg, summary: summary)
486
565
  emit_after_message(msg)
566
+ drain_interloper if tool_batch_complete?(msg)
487
567
  end
488
568
  @chat.before_tool_call do |tc|
489
- @listeners.emit(Event::ToolCall.new(name: tc.name, arguments: tc.arguments))
490
- @step_limit&.tick!
569
+ tool = pikuri_tool_for(tc.name)
570
+ display_name = tool ? tool.display_name : Tool.display_name_for(tc.name)
571
+ argument = tool ? tool.describe_call(tc.arguments) : Tool.describe_arguments(tc.arguments)
572
+ # Everything that leaves the agent names a call by the server's id,
573
+ # the one {History} stores (+D_history_wire_call_ids+).
574
+ call_id = tc.provider_call_id
575
+ @pending_tool_call = { tool_call_id: call_id, name: tc.name, summary: nil }
576
+ record_tool_call_lines(call_id, display_name: display_name, argument: argument)
577
+ @listeners.on_event(Event::ToolCall.new(
578
+ tool_call_id: call_id, name: tc.name, arguments: tc.arguments,
579
+ display_name: display_name, argument: argument
580
+ ))
491
581
  @cancellable&.check!
492
582
  end
493
583
  @chat.after_tool_result do |result|
494
- @listeners.emit(Event::ToolResult.new(content: result))
495
- drain_interloper if @interloper
584
+ pending = @pending_tool_call || {}
585
+ summary = summarize_tool_result(result)
586
+ pending[:summary] = summary
587
+ @listeners.on_event(Event::ToolResult.new(
588
+ tool_call_id: pending[:tool_call_id], name: pending[:name],
589
+ content: tool_result_content(result), summary: summary
590
+ ))
591
+ end
592
+
593
+ @listeners.on_event(restore_history(@history)) if @history
594
+ end
595
+
596
+ # Put a saved conversation into the chat — freshly built, or emptied by
597
+ # {#replace_compacted_history}. Restored:
598
+ # messages, tool calls and their results, thinking, attachments,
599
+ # per-message usage. **Not** state living outside the conversation — a
600
+ # workspace's read-before-edit marks, promoted skills, a task list, what an
601
+ # MCP server held: a resumed conversation whose transcript says a file was
602
+ # read is still asked to read it again before editing, which is right,
603
+ # since the file may have changed while the conversation sat on disk.
604
+ # Nothing replays the recorded calls; see +design/decisions.md+
605
+ # +D_history_load_repairs+.
606
+ #
607
+ # Two repairs happen on the way in, each because a stored conversation
608
+ # can describe something a provider will not accept or a model would
609
+ # misread:
610
+ #
611
+ # - A tool call whose result never arrived gets a synthesized one
612
+ # ({History#repair_interrupted_tool_calls}).
613
+ # - A turn produced by a *different* model loses its whole thinking block
614
+ # — a foreign one lands in a slot the receiving model reads as its own
615
+ # scratchpad. Withheld from the conversation only; {#export_history}
616
+ # still carries it. {#apply_transport!} repeats this for a switch that
617
+ # happens later. See +design/decisions.md+ +D_thinking_block_replay+.
618
+ #
619
+ # @param history [History]
620
+ # @return [Event::HistoryLoaded] for the caller to emit once the agent is
621
+ # bound — the conversation is in place before any extension sees it.
622
+ def restore_history(history)
623
+ current_model = @chat.model&.id
624
+ repaired = history.repair_interrupted_tool_calls
625
+ repaired.messages.each do |m|
626
+ keep = keep_thinking?(m.thinking, m.model_id, current_model)
627
+ track_message(@chat.add_message(m.to_ruby_llm(keep_thinking: keep)),
628
+ kind: m.kind, id: m.id, thinking: (m.thinking unless keep),
629
+ summary: m.summary, tool_calls: restored_tool_call_lines(m))
496
630
  end
497
631
 
498
- # Context-window cap: lets every listener that cares (notably
499
- # TokenLog) pick the value off the stream before any Tokens
500
- # event arrives. Re-fires on each model switch (see
501
- # {#apply_transport!}).
502
- detect_and_emit_context_cap!
503
-
504
- # The runtime capability facade — constructed once, after the
505
- # chat and listener list are final, and handed to every
506
- # extension's #bind / #on_user_message. The ONLY object that
507
- # grants emission / raw-tool-registration / close-handler
508
- # capabilities; the Agent itself exposes no public path to
509
- # them. See {ExtensionContext}.
510
- @extension_context = ExtensionContext.new(
511
- agent: self, chat: @chat, listeners: @listeners,
512
- on_close_sink: @on_close_handlers
632
+ last = repaired.messages.reverse.find { |m| m.role == 'assistant' && m.tokens }
633
+ Event::HistoryLoaded.new(
634
+ messages: repaired.messages.size,
635
+ tokens: last && Event::Tokens.new(**last.tokens.to_h, model_id: last.model_id)
513
636
  )
637
+ end
514
638
 
515
- # Bind sweep — each extension gets its chance to install
516
- # per-agent state (dynamic tools via
517
- # {ExtensionContext#add_raw_tool}, per-agent close hooks via
518
- # {ExtensionContext#on_close}, domain-event wiring via
519
- # {ExtensionContext#emit_event}, etc.) now that the chat is
520
- # fully wired. See IDEAS.md §"Extension protocol design" for
521
- # what #configure vs #bind are each for.
522
- @extensions.each { |ext| ext.bind(@extension_context) }
523
- end
524
-
525
- # Resolve the context-window cap and announce it on the listener
526
- # stream as an {Event::ContextCap}. The transport's explicit
527
- # +context_window+ wins verbatim; otherwise {ContextWindowDetector}
528
- # probes the server (yielding +nil+ for a non-llama one). Because the
529
- # cap rides {ChatTransport}, a model switch resolves the *new*
530
- # transport's cap — explicit caps don't bleed across models. Shared
531
- # by {#run_configure} (construction) and {#apply_transport!} (each
532
- # model switch) so "how the cap is resolved and emitted" lives in
533
- # one place.
639
+ # Swap the conversation for +history+, a compacted rendering of it, and
640
+ # emit {Event::HistoryCompacted}. The contract, and why nothing else is
641
+ # reset: {Configurator#replace_compacted_history}.
534
642
  #
643
+ # @param history [History]
535
644
  # @return [void]
536
- def detect_and_emit_context_cap!
537
- # Probe the server this transport actually targets — after a
538
- # cross-server switch the chat's connection points at
539
- # +@transport.api_base+, but the process-global config the
540
- # detector defaults to still names the *old* server, so derive the
541
- # base from the transport (falling back to the global base for a
542
- # transport that rides it).
543
- @context_window_cap = @transport.context_window ||
544
- ContextWindowDetector.detect(
545
- @transport,
546
- openai_base: @transport.api_base || RubyLLM.config.openai_api_base
547
- )
548
- @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
549
- end
550
-
551
- # Switch the underlying chat to +transport+ when it differs from
552
- # the current one. Called only from the top of {#run_loop} — see
553
- # that method's "Switching models mid-conversation" section for why
554
- # the swap is confined to the loop's own thread.
555
- #
556
- # Mirrors {#initialize}'s +nil+-model fill before the structural
557
- # comparison, so a +transport+ that defers its model to the default
558
- # doesn't read as "different" and switch spuriously.
559
- # +Chat#with_model+ swaps only the model / provider / connection,
560
- # leaving +@chat+'s message history and registered callbacks
561
- # intact, so the conversation continues seamlessly under the new
562
- # model. Emits {Event::ModelSwitched} (the narration: old → new
563
- # transport, unformatted, for the chrome to present) then re-resolves
564
- # and re-emits the cap via {#detect_and_emit_context_cap!}.
565
- #
566
- # == Cross-server switches
567
- #
568
- # +with_model+ alone re-resolves against the chat's *existing*
569
- # connection, so it can only move between models on one server. When
570
- # either the new or the old transport overrides the connection
571
- # (+ChatTransport#connection_overrides?+ — a different +api_base+ /
572
- # +api_key+), the swap first installs a fresh +RubyLLM::Context+ via
573
- # +Chat#with_context+ (which re-points the connection and re-resolves
574
- # the model in place, again preserving history + callbacks) before
575
- # +with_model+ lands the new model id. The "old overrode" half of
576
- # the guard handles switching *back* to a global-config model: the
577
- # rebuilt context dups the process-global config, resetting the
578
- # connection the previous override installed.
645
+ # @raise [ArgumentError] if +history+ is not a {History}, drops the
646
+ # conversation's last message, or holds a tool result with no call
647
+ # @raise [RuntimeError] inside the +Agent.new+ block, or while a tool
648
+ # batch is open
649
+ def replace_compacted_history(history)
650
+ raise ArgumentError, "expected a Pikuri::Agent::History, got #{history.class}" unless history.is_a?(History)
651
+ # Set right after the block returns: inside it there is no conversation
652
+ # to compact yet, and resuming one is +history:+'s job.
653
+ raise 'replace_compacted_history called before Agent.new returned' unless @message_meta
654
+
655
+ open = unanswered_tool_calls
656
+ unless open.empty?
657
+ # ruby_llm still holds the batch's calls and appends their results
658
+ # after whatever the chat holds by then.
659
+ raise 'cannot replace the history while a tool batch is open: ' \
660
+ "#{open.map { |c| "#{c.name}(#{c.provider_call_id})" }.join(', ')}"
661
+ end
662
+ refuse_bad_compaction(history)
663
+
664
+ before = @chat.messages.count { |m| m.role != :system }
665
+ @chat.messages.select! { |m| m.role == :system }
666
+ @message_meta.clear
667
+ @pending_tool_call = nil
668
+ loaded = restore_history(history)
669
+ @listeners.on_event(Event::HistoryCompacted.new(messages_before: before, messages_after: loaded.messages))
670
+ nil
671
+ end
672
+
673
+ # The two cuts a compactor can get wrong that no provider reports
674
+ # clearly.
675
+ #
676
+ # Dropping the last message strands whatever ruby_llm does next: from a
677
+ # listener at the end of a turn, a history ending on a user message draws
678
+ # a request nobody asked for.
679
+ #
680
+ # A tool result whose call was cut away is a 400 on OpenAI and Anthropic,
681
+ # and on llama.cpp a template that improvises.
682
+ #
683
+ # @param history [History]
684
+ # @return [void]
685
+ # @raise [ArgumentError] on either
686
+ def refuse_bad_compaction(history)
687
+ last = @chat.messages.reverse.find { |m| m.role != :system }
688
+ last_id = last && @message_meta.dig(last, :id)
689
+ if last_id && history.messages.last&.id != last_id
690
+ raise ArgumentError, "a compacted history must end with the conversation's last message #{last_id}, " \
691
+ "got #{history.messages.last&.id.inspect}"
692
+ end
693
+
694
+ calls = []
695
+ history.messages.each do |m|
696
+ unless m.role == 'tool'
697
+ calls = m.tool_calls.map(&:id)
698
+ next
699
+ end
700
+ next if calls.include?(m.tool_call_id)
701
+
702
+ raise ArgumentError, "tool result #{m.id} answers #{m.tool_call_id.inspect}, " \
703
+ 'a call the assistant turn before it did not make'
704
+ end
705
+ end
706
+
707
+ # Build the full prompt: base plus every extension's
708
+ # {Extension#system_prompt_snippets}, in registration order, joined by
709
+ # blank lines. Blank/nil sections drop (an extension contributing
710
+ # nothing leaves no stray separator). Runs once, at construction.
711
+ #
712
+ # That one call site is a *price* rather than a missing feature: a stable prefix is free after turn one
713
+ # (llama.cpp slot prefix-reuse, Anthropic's prompt cache), where amending
714
+ # one invalidates every cached token after the change point and
715
+ # re-prefills. Hence there is no amend-the-prompt seam — mid-conversation
716
+ # blocks go through {#append_reference_block}, which appends and
717
+ # invalidates nothing. See `design/decisions.md` `D_reference_text_as_user_turn`.
718
+ #
719
+ # @return [String]
720
+ def assemble_system_prompt
721
+ sections = @extensions.flat_map(&:system_prompt_snippets)
722
+ [@system_prompt_base, *sections]
723
+ .reject { |s| s.nil? || s.to_s.strip.empty? }
724
+ .join("\n\n")
725
+ end
726
+
727
+ # The {ChatTransport#modalities} key an attachment's MIME family needs, in
728
+ # llama.cpp's vocabulary. A family not listed here (a PDF) is never refused.
729
+ MODALITY_BY_MEDIA_TYPE = { 'image' => :vision, 'audio' => :audio, 'video' => :video }.freeze
730
+ private_constant :MODALITY_BY_MEDIA_TYPE
731
+
732
+ # Why the model can't take +attachment+, per the transport's stated
733
+ # modalities.
734
+ #
735
+ # @param attachment [Pikuri::Attachment]
736
+ # @return [String, nil] the reason, e.g. "model X takes no vision input";
737
+ # +nil+ when it may go out, including whenever acceptance is unstated
738
+ def attachment_refusal(attachment)
739
+ modality = MODALITY_BY_MEDIA_TYPE[attachment.mime.to_s.split('/').first]
740
+ return nil unless modality && @transport.modalities&.[](modality) == false
741
+
742
+ "model #{@transport.model} takes no #{modality} input"
743
+ end
744
+
745
+ # Adopt +transport+ for this turn on: a switch when it names another model
746
+ # or connection, a fact update when only +context_window+ / +modalities+
747
+ # differ. Called only from the top of {#run_loop} (see its "Switching
748
+ # models" section for the thread-confinement reason). Mirrors
749
+ # {#initialize}'s +nil+-model fill before comparing, so a transport
750
+ # deferring to the default model doesn't switch spuriously.
751
+ #
752
+ # A fact update touches nothing but +@transport+ and emits nothing: the
753
+ # chat, its connection and the history's thinking all belong to the same
754
+ # model as before, and the host that made the update already knows it.
755
+ #
756
+ # A switch rebuilds the connection the way {#build_chat} built the first
757
+ # one — a fresh +RubyLLM::Context+ via +Chat#with_context+, then
758
+ # +Chat#with_model+, both of which keep history and callbacks — and emits
759
+ # {Event::ModelSwitched}. The context is rebuilt on every switch, not only
760
+ # a cross-server one, so nothing of the old transport's connection can
761
+ # linger: its base URL and key, its +faraday_adapter+, the base URL the
762
+ # {RequestInstrumenter} reports. The new transport's +params+ replace the
763
+ # old one's, so a switch cannot leave a thinking-off kwarg on a connection
764
+ # that never asked for one.
765
+ #
766
+ # Because the history is kept, every turn in it is now potentially from
767
+ # another model, so {#strip_foreign_thinking!} runs before the event —
768
+ # {#restore_history}'s repair only covers a conversation that arrives stale.
769
+ #
770
+ # Why switch in place rather than have the host rebuild the agent around
771
+ # {#export_history}: +design/decisions.md+ +D_model_switch_in_place+.
579
772
  #
580
773
  # @param transport [ChatTransport] the model to switch to
581
774
  # @return [void]
582
775
  def apply_transport!(transport)
583
776
  filled = transport.model ? transport : transport.with(model: RubyLLM.config.default_model)
584
- return if filled == @transport
585
-
586
777
  old = @transport
587
- @chat.with_context(build_context(filled)) if filled.connection_overrides? || old.connection_overrides?
588
- @chat.with_model(filled.model, provider: filled.provider, assume_exists: filled.assume_model_exists)
589
778
  @transport = filled
590
- @listeners.emit(Event::ModelSwitched.new(from: old, to: filled))
591
- detect_and_emit_context_cap!
779
+ return if filled.with(context_window: old.context_window, modalities: old.modalities) == old
780
+
781
+ @chat.with_context(build_context(filled))
782
+ @chat.with_model(filled.model, provider: filled.provider, assume_model_exists: filled.assume_model_exists)
783
+ @chat.with_provider_options(filled.params)
784
+ strip_foreign_thinking!
785
+ @listeners.on_event(Event::ModelSwitched.new(from: old, to: filled))
592
786
  end
593
787
 
594
- # Build the chat for +transport+: through a dedicated
595
- # +RubyLLM::Context+ when it overrides the connection, else through
596
- # the process-global +RubyLLM.chat+ (which the construction-time
597
- # path has always used).
788
+ # Build the chat for +transport+ — always through a dedicated
789
+ # +RubyLLM::Context+, never +RubyLLM.chat+, so every chat this agent builds
790
+ # carries the +around_request+ hook and any +faraday_adapter+. A no-override
791
+ # transport gets a plain dup of the global config, which resolves the model
792
+ # exactly as +RubyLLM.chat+ would.
793
+ #
794
+ # A transport's +params+ ride the *chat* rather than the context, because
795
+ # ruby_llm deep-merges them into the completion payload — see
796
+ # {ChatTransport}'s +== Extra request parameters+.
598
797
  #
599
798
  # @param transport [ChatTransport]
600
799
  # @return [RubyLLM::Chat]
601
800
  def build_chat(transport)
602
- if transport.connection_overrides?
603
- build_context(transport).chat(**transport.chat_kwargs)
604
- else
605
- RubyLLM.chat(**transport.chat_kwargs)
606
- end
801
+ build_context(transport).chat(**transport.chat_kwargs).with_provider_options(transport.params)
607
802
  end
608
803
 
609
- # A +RubyLLM::Context+ carrying +transport+'s connection overrides
610
- # mapped onto the provider's ruby_llm config slots
611
- # (+#{provider}_api_base+ / +#{provider}_api_key+). +RubyLLM.context+
612
- # dups the process-global config, so an absent override inherits the
613
- # global value; a transport with no overrides yields a plain dup
614
- # (used by {#apply_transport!} to reset a prior override). The
615
- # +ChatTransport+ guarantees a non-+nil+ +provider+ whenever an
616
- # override is set, so the slot name is always resolvable.
804
+ # A +RubyLLM::Context+ carrying +transport+'s connection overrides on the
805
+ # provider's config slots (+#{provider}_api_base+ / +_api_key+).
806
+ # +RubyLLM.context+ dups the global config, so an absent override inherits
807
+ # the global value and a no-override transport yields a plain dup — which
808
+ # is how a switch back to a global-config model drops a prior override.
809
+ # +ChatTransport+
810
+ # guarantees a non-+nil+ +provider+ whenever an override is set.
811
+ #
812
+ # A transport's +faraday_adapter+ (if any) is installed here too: the
813
+ # adapter rides *this* context's config, not the process-global
814
+ # +RubyLLM.config+, so it stays per-agent — the seam
815
+ # {Pikuri::Testing.fake_transport} uses to run the real ruby_llm loop
816
+ # against a scripted HTTP backend.
817
+ #
818
+ # So does the {RequestInstrumenter}, on the same config's +instrumenter+
819
+ # slot, when the agent has an +around_request+ hook: global config
820
+ # untouched, and handed the base URL the connection will actually dial —
821
+ # which is why it is read *after* the override assignments.
617
822
  #
618
823
  # @param transport [ChatTransport]
619
824
  # @return [RubyLLM::Context]
@@ -622,75 +827,343 @@ module Pikuri
622
827
  RubyLLM.context do |c|
623
828
  c.public_send("#{slug}_api_base=", transport.api_base) unless transport.api_base.nil?
624
829
  c.public_send("#{slug}_api_key=", transport.api_key) unless transport.api_key.nil?
830
+ c.faraday_adapter = transport.faraday_adapter if transport.faraday_adapter
831
+ # ruby_llm defaults an OpenAI-family `:system` message to the newer
832
+ # `developer` role. OpenAI treats the two alike, but a local
833
+ # llama.cpp hands the role straight to the model's chat template,
834
+ # and a Qwen/Llama template has never seen `developer` — the system
835
+ # prompt then arrives under a role token the model was not trained
836
+ # on. pikuri targets local servers first, so ask for `system`.
837
+ c.openai_use_system_role = true if c.respond_to?(:openai_use_system_role=)
838
+ # ruby_llm defaults :openai to OpenAI's Responses API (+/v1/responses+);
839
+ # llama.cpp and the other OpenAI-compatible servers pikuri targets speak
840
+ # Chat Completions, which OpenAI itself still serves too.
841
+ c.openai_protocol = :chat_completions
842
+ # llama.cpp with +--reasoning-format none+ leaves reasoning inline as
843
+ # +<think>…</think>+; a server sending +reasoning_content+ is untouched.
844
+ c.split_think_tags = true
845
+ if @around_request
846
+ RequestInstrumenter.install(c, hook: @around_request, api_base: dialed_api_base(slug, c),
847
+ cancellable: @cancellable)
848
+ end
625
849
  end
626
850
  end
627
851
 
628
- # Fire the per-turn {Extension#on_user_message} hook on every
629
- # extension that defines it, appending any returned
630
- # String text block to the chat as a +role: :system+
631
- # message right after the user turn it annotates (callers append
632
- # the +:user+ message first; this runs last). The system role is
633
- # load-bearing — it tags the block as recalled reference (not new
634
- # input) and keeps it excludable from a later extraction pass.
635
- # See {Extension#on_user_message}.
636
- #
637
- # Each injected block also emits an {Event::SystemInjected} at
638
- # this site, so the listener stream mirrors the log growth (the
639
- # Terminal renders it; otherwise an injection would be invisible
640
- # except as a downstream echo in the assistant's reasoning).
641
- #
642
- # Private and the single place the chat log grows by a memory
643
- # block — keeps "what mutates the log, when" one grep in this
644
- # file. Fired from {#run_loop} (initial turn) and from
645
- # {#drain_interloper} (mid-loop interlopers). Called on every
646
- # extension unconditionally — same as {Extension#configure} /
647
- # {Extension#bind}: the hook is part of the protocol and the
648
- # {Extension} module supplies a no-op default, so any extension
649
- # that includes the module responds. An extension is "opted out"
650
- # by leaving the default in place (it returns +nil+, injecting
651
- # nothing), not by omitting the method.
652
- #
653
- # @param content [String] the incoming user message
852
+ # The base URL the connection dials, read off the context config the chat
853
+ # is about to use rather than re-derived, so it can't drift from the
854
+ # connection.
855
+ #
856
+ # @param slug [Symbol, nil] the transport's provider.
857
+ # @param config [RubyLLM::Configuration] this context's config, connection
858
+ # overrides already applied.
859
+ # @return [String, nil] the base URL, or +nil+ when the provider names no
860
+ # +_api_base+ slot (a fixed-base provider like Anthropic) or has none
861
+ # configured.
862
+ def dialed_api_base(slug, config)
863
+ return nil if slug.nil?
864
+
865
+ reader = "#{slug}_api_base"
866
+ config.respond_to?(reader) ? config.public_send(reader) : nil
867
+ end
868
+
869
+ # Fire {Extension#on_user_message} on every extension, appending any
870
+ # returned text via {#append_reference_block} right after the user turn it
871
+ # annotates (the caller appends the +:user+ message first).
872
+ #
873
+ # Called unconditionally — the {Extension} no-op default returns +nil+
874
+ # (injects nothing), so opting out means leaving the default, not omitting
875
+ # the method.
876
+ #
877
+ # @param content [String] the incoming user message's text; +""+ when it
878
+ # carries only attachments
879
+ # @param attachments [Array<Pikuri::Attachment>] what went out with it
654
880
  # @return [void]
655
- def dispatch_ext_on_user_message(content)
881
+ def dispatch_ext_on_user_message(content, attachments)
656
882
  @extensions.each do |ext|
657
- message = ext.on_user_message(@extension_context, content)
883
+ message = ext.on_user_message(content, attachments)
658
884
  next unless message.is_a?(String) && !message.strip.empty?
659
885
 
660
- block = message.strip
661
- @chat.add_message(role: :system, content: block)
662
- @listeners.emit(Event::SystemInjected.new(content: block))
886
+ append_reference_block(message.strip)
887
+ end
888
+ nil
889
+ end
890
+
891
+ # Append host-originated reference text — a memory block, a loaded skill, a
892
+ # path-activation promotion, retrieved context — and emit
893
+ # {Event::SystemInjected}. Lands as a +role: :user+ message wrapped in
894
+ # +<system-reminder>+:
895
+ #
896
+ # append_reference_block('<memory-context>…</memory-context>')
897
+ # # the chat log grows by one :user message:
898
+ # # <system-reminder>
899
+ # # <memory-context>…</memory-context>
900
+ # # </system-reminder>
901
+ #
902
+ # The event carries the block *unwrapped* — the envelope is wire plumbing,
903
+ # and a listener rendering the tag would be showing the reader framing they
904
+ # did not write.
905
+ #
906
+ # == Implementation details
907
+ #
908
+ # +:user+ rather than +:system+ because a mid-conversation +:system+ message
909
+ # is not portable: Qwen3.6's chat template silently drops every one past the
910
+ # leading header, and providers carrying +:system+ in a separate field
911
+ # (Anthropic's +system+ param, Bedrock's +system+ blocks) merge it into
912
+ # the standing system prompt, so the block is presented as though it had
913
+ # always been there and stays in force. Neither failure is visible from
914
+ # anything pikuri can observe: the message is in the payload, the listener
915
+ # stream renders it, the history holds it. See +design/decisions.md+
916
+ # +D_reference_text_as_user_turn+.
917
+ #
918
+ # A closing tag inside +content+ is escaped, so injected text (a file, a web
919
+ # page, an MCP tool's description) cannot close the envelope early and have
920
+ # what follows read as conversation.
921
+ #
922
+ # @param content [String] the block to inject, already stripped; callers
923
+ # with their own semantic tag (+<memory-context>+) keep it — the envelope
924
+ # nests around it
925
+ # @return [void]
926
+ def append_reference_block(content)
927
+ close = "</#{REFERENCE_TAG}>"
928
+ # Block form, not a replacement String: gsub reads `\&`, `\1` etc. out of
929
+ # the latter, so a tag carrying one would be mangled rather than escaped.
930
+ body = content.gsub(close) { "<\\/#{REFERENCE_TAG}>" }
931
+ # Tagged +reference+ so a restored conversation can tell pikuri's own
932
+ # injection from something the human typed — both land as +:user+.
933
+ track_message(@chat.add_message(role: :user, content: "<#{REFERENCE_TAG}>\n#{body}\n#{close}"),
934
+ kind: 'reference')
935
+ @listeners.on_event(Event::SystemInjected.new(content: content))
936
+ nil
937
+ end
938
+
939
+ # Remember pikuri's own identity for a message just added to the chat, so
940
+ # {#export_history} can hand out a stable id, say whether a +:user+ message
941
+ # was typed or injected, and put back a thinking block the conversation is
942
+ # not replaying. None of it ever reaches a provider.
943
+ #
944
+ # Keyed on the message *object*, so a caller that rebuilds one must move
945
+ # its entry across — see {#strip_foreign_thinking!}.
946
+ #
947
+ # @param msg [RubyLLM::Message] as returned by +Chat#add_message+.
948
+ # @param kind [String] one of {History::KINDS}.
949
+ # @param id [String, nil] an existing id to preserve (restoring a saved
950
+ # conversation); +nil+ mints a fresh one.
951
+ # @param thinking [History::Thinking, nil] a block withheld from +msg+
952
+ # because another model produced it, kept so the export stays faithful.
953
+ # @param summary [String, nil] a +:tool+ message's display line (see
954
+ # {Pikuri::Tool::Result}); nothing can recompute one after the fact, so
955
+ # the export carries it.
956
+ # @param tool_calls [Hash{String=>Hash}, nil] per-call display strings for
957
+ # an assistant turn, +{call_id => {display_name:, argument:}}+.
958
+ # @return [RubyLLM::Message] +msg+, so call sites can wrap in place.
959
+ def track_message(msg, kind: 'user', id: nil, thinking: nil, summary: nil, tool_calls: nil)
960
+ unless msg.role == :system
961
+ @message_meta[msg] = { id: id || History.mint_id, kind: kind, thinking: thinking,
962
+ summary: summary, tool_calls: tool_calls }
963
+ end
964
+ msg
965
+ end
966
+
967
+ # @param msg [History::Message] a message being restored.
968
+ # @return [Hash{String=>Hash}, nil] its calls' persisted display strings,
969
+ # in {#track_message}'s shape, so a re-export round-trips them; +nil+
970
+ # when the message asked for no tools.
971
+ def restored_tool_call_lines(msg)
972
+ return nil if msg.tool_calls.empty?
973
+
974
+ msg.tool_calls.to_h { |c| [c.id, { display_name: c.display_name, argument: c.argument }] }
975
+ end
976
+
977
+ # The {Pikuri::Tool} behind a registered tool name, or +nil+ for one that
978
+ # never was a +Pikuri::Tool+ (an MCP tool) or a name ruby_llm has no tool
979
+ # for (its unavailable-tool error).
980
+ #
981
+ # Read off ruby_llm's own +Chat#tools+ table rather than {#tools}: the
982
+ # +agent+ and +mcp_connect+ tools register through
983
+ # {Configurator#add_raw_tool}, which deliberately keeps them out of
984
+ # that list, and an index over it would miss their overrides.
985
+ #
986
+ # @param name [String] the tool name ruby_llm is calling.
987
+ # @return [Pikuri::Tool, nil]
988
+ def pikuri_tool_for(name)
989
+ wrapper = @chat.tools[name.to_sym]
990
+ wrapper.respond_to?(:pikuri_tool) ? wrapper.pikuri_tool : nil
991
+ end
992
+
993
+ # Record one call's display strings on the assistant message that asked for
994
+ # it, so {#export_history} can persist them — a later wiring may no longer
995
+ # have the tool (a removed extension, a renamed MCP server), and then
996
+ # nothing could recompute the line.
997
+ #
998
+ # @param call_id [String] the provider's tool-call id.
999
+ # @param display_name [String] see {Pikuri::Tool#display_name}.
1000
+ # @param argument [String] see {Pikuri::Tool#describe_call}.
1001
+ # @return [void]
1002
+ def record_tool_call_lines(call_id, display_name:, argument:)
1003
+ opener = @chat.messages.reverse.find do |m|
1004
+ m.role == :assistant && m.tool_calls&.each_value&.any? { |c| c.provider_call_id == call_id }
1005
+ end
1006
+ meta = opener && @message_meta[opener]
1007
+ return unless meta
1008
+
1009
+ (meta[:tool_calls] ||= {})[call_id] = { display_name: display_name, argument: argument }
1010
+ nil
1011
+ end
1012
+
1013
+ # A {Pikuri::Tool} answers its own summary; everything else is derived. The
1014
+ # +else+ is not a pikuri tool falling back — it is the three payloads that
1015
+ # never went through {Pikuri::Tool#run}: an MCP tool's String, ruby_llm's
1016
+ # unavailable-tool +Hash+, and the +[note, *attachments]+ Array the wrapper
1017
+ # unwrapped an attachment {Pikuri::Tool::Result} into
1018
+ # ({Pikuri::Tool#to_ruby_llm_tool}).
1019
+ #
1020
+ # @param result [Pikuri::Tool::Result, String, Array<String,
1021
+ # RubyLLM::Attachment>, Hash] what ruby_llm handed +after_tool_result+.
1022
+ # @return [String] the one-line result summary for the listener stream.
1023
+ def summarize_tool_result(result)
1024
+ result.is_a?(Tool::Result) ? result.summary : Tool.describe_content(result)
1025
+ end
1026
+
1027
+ # {Event::ToolResult#content} for +result+: an attachment observation
1028
+ # arrives as its text note, so a listener never holds the bytes.
1029
+ #
1030
+ # @param result [Pikuri::Tool::Result, String, Array<String,
1031
+ # RubyLLM::Attachment>, Hash] what ruby_llm handed +after_tool_result+.
1032
+ # @return [String, Hash] the observation text; ruby_llm's unavailable-tool
1033
+ # +Hash+ passes through.
1034
+ def tool_result_content(result)
1035
+ case result
1036
+ when Tool::Result then result.content
1037
+ when Array then result.grep(String).join("\n\n")
1038
+ else result
1039
+ end
1040
+ end
1041
+
1042
+ # Whether a turn's thinking may be replayed to +current+ — true only where
1043
+ # this model demonstrably produced it.
1044
+ #
1045
+ # Unknown provenance counts as foreign: a +model_id+ nobody recorded is
1046
+ # indistinguishable from another model's, and attributing one model's
1047
+ # reasoning to another is the failure this guards against.
1048
+ #
1049
+ # The two ids come from different places — +current+ is what pikuri
1050
+ # *requested*, +model_id+ what the server *reported* — so a backend that
1051
+ # does not echo the requested id back makes every turn look foreign. That
1052
+ # only ever over-drops (a model loses its own reasoning; none is ever
1053
+ # attributed to another), which is why the weaker test is tolerated; the
1054
+ # fakes in +Pikuri::Testing+ are themselves such a backend. Measured
1055
+ # echoing verbatim on llama.cpp — see +design/decisions.md+
1056
+ # +D_thinking_block_replay+.
1057
+ #
1058
+ # @param thinking [History::Thinking, RubyLLM::Thinking, nil]
1059
+ # @param model_id [String, nil] who produced the turn.
1060
+ # @param current [String, nil] the agent's model now.
1061
+ # @return [Boolean]
1062
+ def keep_thinking?(thinking, model_id, current)
1063
+ thinking.nil? || (!model_id.nil? && model_id == current)
1064
+ end
1065
+
1066
+ # Withhold every thinking block the current model did not produce from the
1067
+ # live conversation, parking it in +@message_meta+ so {#export_history}
1068
+ # still writes it.
1069
+ #
1070
+ # {#restore_history} covers a conversation that arrives stale; this covers
1071
+ # one that goes stale under a running agent, which +Chat#with_model+ leaves
1072
+ # untouched. +RubyLLM::Message+ has no thinking writer, so a stripped turn
1073
+ # is a rebuilt object and its metadata is re-keyed onto the replacement.
1074
+ #
1075
+ # @return [void]
1076
+ def strip_foreign_thinking!
1077
+ current = @chat.model&.id
1078
+ @chat.messages.map! do |msg|
1079
+ next msg if keep_thinking?(msg.thinking, msg.model, current)
1080
+
1081
+ meta = @message_meta.delete(msg) || { id: History.mint_id, kind: 'user' }
1082
+ stripped = RubyLLM::Message.new(
1083
+ role: msg.role, content: msg.content, tool_calls: msg.tool_calls,
1084
+ tool_call_id: msg.tool_call_id, model: msg.model, attachments: msg.attachments,
1085
+ tokens: msg.tokens, raw: msg.raw, thinking: nil
1086
+ )
1087
+ @message_meta[stripped] = meta.merge(
1088
+ thinking: History::Thinking.new(text: msg.thinking.text, signature: msg.thinking.signature)
1089
+ )
1090
+ stripped
1091
+ end
1092
+ end
1093
+
1094
+ # Answer every call the last assistant turn left unanswered, emitting each
1095
+ # synthesized observation as an {Event::ToolResult} so a host can show what
1096
+ # it appended. Rationale in {#run_loop}'s +== Repairing an unwound tool
1097
+ # batch+.
1098
+ #
1099
+ # Order carries the first-vs-rest split ({CANCELLED_RESULT}): +tool_calls+
1100
+ # is insertion-ordered and ruby_llm runs it with +each_value+, so the first
1101
+ # gap is the culprit — true only while +tool_concurrency+ stays off, which
1102
+ # {Pikuri::Tool}'s +== Sharing+ asks for on separate grounds.
1103
+ #
1104
+ # Not {History#repair_interrupted_tool_calls}: damage here is always the
1105
+ # tail, and that walk is over +History::Message+, whose +role+ is a +String+
1106
+ # where ruby_llm's is a +Symbol+.
1107
+ #
1108
+ # @param cause [Exception, nil] what the turn is unwinding with; +nil+ on
1109
+ # the success path, where nothing dangles.
1110
+ # @return [void]
1111
+ # @raise [RuntimeError] if calls dangle with no +cause+ — pikuri lost a
1112
+ # batch on a turn that succeeded. Safe to raise from an +ensure+ here
1113
+ # precisely because there is no in-flight exception to clobber.
1114
+ def repair_dangling_tool_calls!(cause)
1115
+ dangling = unanswered_tool_calls
1116
+ return if dangling.empty?
1117
+
1118
+ if cause.nil?
1119
+ raise 'unanswered tool calls on a turn that did not unwind: ' \
1120
+ "#{dangling.map { |c| "#{c.name}(#{c.provider_call_id})" }.join(', ')}"
663
1121
  end
1122
+
1123
+ culprit, skipped = unanswered_results(cause)
1124
+ dangling.each_with_index do |call, i|
1125
+ content = i.zero? ? culprit : skipped
1126
+ # +call.id+ is ruby_llm's own; it maps the answer back to the server's
1127
+ # id on the wire. The event names the server's, like every other one.
1128
+ track_message(@chat.add_message(role: :tool, content: content, tool_call_id: call.id),
1129
+ summary: INTERRUPTED_SUMMARY)
1130
+ @listeners.on_event(Event::ToolResult.new(tool_call_id: call.provider_call_id, name: call.name,
1131
+ content: content, summary: INTERRUPTED_SUMMARY))
1132
+ end
1133
+ LOGGER.warn { "answered #{dangling.size} dangling tool call(s) after #{cause.class}" }
664
1134
  nil
665
1135
  end
666
1136
 
667
- # Build the per-chunk streaming block passed to +Chat#complete+.
668
- # Each invocation of the returned proc converts one
669
- # +RubyLLM::Chunk+ into zero, one, or two delta events
670
- # ({Event::ThinkingDelta} / {Event::AssistantDelta}) on
671
- # +@listeners+. Tool-call chunks are intentionally ignored —
672
- # partial JSON has no useful rendering; the assembled
673
- # +tool_calls+ surface through {Event::ToolCall} once the
674
- # message completes.
1137
+ # @param cause [Exception]
1138
+ # @return [Array(String, String)] what the call that raised (or was about
1139
+ # to) is told, then what the calls behind it that never started are told.
1140
+ # See {CANCELLED_RESULT}.
1141
+ def unanswered_results(cause)
1142
+ case cause
1143
+ when Control::Cancellable::Cancelled then [CANCELLED_RESULT, CANCELLED_SKIPPED_RESULT]
1144
+ # Deliberately unsanitized: the message can carry untrusted bytes (a
1145
+ # filename off a scraped page), which {Tool#run}'s own +"Error: ..."+
1146
+ # already puts in the conversation — and a model cannot react to a
1147
+ # failure it is not told about.
1148
+ else ["Error: #{cause.class}: #{cause.message}", FAILED_SKIPPED_RESULT]
1149
+ end
1150
+ end
1151
+
1152
+ # Build the per-chunk block passed to +Chat#complete+. Each call converts
1153
+ # one +RubyLLM::Chunk+ into zero, one, or two delta events
1154
+ # ({Event::ThinkingDelta}/{Event::AssistantDelta}). Tool-call chunks are
1155
+ # ignored — partial JSON has no useful rendering; the assembled call
1156
+ # surfaces via {Event::ToolCall} once the message completes.
675
1157
  #
676
1158
  # == Cancellation polling
677
1159
  #
678
- # When +@cancellable+ is non-nil, {Control::Cancellable#check!}
679
- # fires *before* each chunk's emit. The +before_tool_call+
680
- # wiring in {#run_configure} only fires when the model requests a
681
- # tool, which leaves a no-tool turn (e.g. a plain greeting)
682
- # with zero cancellation points — Ctrl+C trips the flag but
683
- # nothing reads it. Polling on every streamed chunk closes
684
- # that gap: an in-flight Cancellation+check! raises on the
685
- # next chunk delivered after the flag flips, the exception
686
- # propagates out through ruby_llm's streaming path
687
- # (+Chat#complete+ doesn't rescue), and {#run_loop} catches it,
688
- # emits {Event::Cancelled}, and re-raises. The pre-emit
689
- # ordering is deliberate: a chunk that arrives after a cancel
690
- # request shouldn't render — the user has said stop.
691
- #
692
- # @return [Proc] a +-> (chunk) { ... }+ proc suitable for
693
- # passing to +Chat#complete+ with +&+
1160
+ # When +@cancellable+ is set, {Control::Cancellable#check!} fires *before*
1161
+ # each chunk's emit. The +before_tool_call+ wiring only fires on a tool
1162
+ # request, so a no-tool turn (a plain greeting) has zero cancellation
1163
+ # points; polling per chunk closes that gap. Pre-emit ordering is
1164
+ # deliberate — a chunk arriving after a cancel request shouldn't render.
1165
+ #
1166
+ # @return [Proc] a +->(chunk) { ... }+ for +Chat#complete+
694
1167
  def streaming_block
695
1168
  ->(chunk) {
696
1169
  @cancellable&.check!
@@ -698,18 +1171,41 @@ module Pikuri
698
1171
  }
699
1172
  end
700
1173
 
701
- # Normalize a +RubyLLM::Chat+ +after_message+ payload into
702
- # zero, one, or two {Event} variants (+Thinking+ and/or
703
- # +Assistant+) plus one {Event::Tokens} for the usage block.
704
- # Empty thinking / empty content are filtered here so
705
- # listeners never see vacuous events. Non-assistant roles
706
- # (e.g. tool-role messages echoed back through
707
- # +after_message+) are skipped entirely.
1174
+ # Whether +msg+ closed a tool batch — the only mid-turn moment an injected
1175
+ # message may be appended.
708
1176
  #
709
- # +msg+ is a +RubyLLM::Message+. Beyond +role+, +content+,
710
- # +thinking+, and the +*_tokens+ accessors used here, it also
711
- # carries +msg.tool_calls+ on assistant turns that requested
712
- # one and +msg.raw+ for the unparsed provider payload.
1177
+ # An assistant message carrying +tool_calls+ and the +:tool+ messages
1178
+ # answering it are one indivisible unit on the wire: OpenAI rejects a
1179
+ # +tool+ message that does not follow its call, Anthropic requires the
1180
+ # results to open the very next message, and a local chat template groups
1181
+ # them into one block. Anything appended between the two halves is
1182
+ # therefore either an error or, worse, silently mangled prose — which is
1183
+ # what draining at ruby_llm's +after_tool_result+ did, since that fires
1184
+ # *before* the result message is added.
1185
+ #
1186
+ # @param msg [RubyLLM::Message]
1187
+ # @return [Boolean] true when +msg+ is the last tool result its assistant
1188
+ # message was waiting for (so parallel calls drain once, at the end)
1189
+ def tool_batch_complete?(msg)
1190
+ msg.role == :tool && unanswered_tool_calls.empty?
1191
+ end
1192
+
1193
+ # @return [Array<RubyLLM::ToolCall>] the calls of the last assistant
1194
+ # turn that asked for tools which no +:tool+ message answers yet, in
1195
+ # the order ruby_llm runs them; empty when no batch is open.
1196
+ def unanswered_tool_calls
1197
+ messages = @chat.messages
1198
+ opener_index = messages.rindex { |m| m.role == :assistant && m.tool_calls&.any? }
1199
+ return [] if opener_index.nil?
1200
+
1201
+ answered = messages[(opener_index + 1)..].filter_map { |m| m.tool_call_id if m.role == :tool }
1202
+ messages[opener_index].tool_calls.each_value.reject { |c| answered.include?(c.id) }
1203
+ end
1204
+
1205
+ # Normalize an +after_message+ payload into zero, one, or two {Event}s
1206
+ # (+Thinking+ and/or +Assistant+) plus one {Event::Tokens}. Empty
1207
+ # thinking/content are filtered here so listeners never see vacuous
1208
+ # events; non-assistant roles are skipped.
713
1209
  #
714
1210
  # @param msg [RubyLLM::Message]
715
1211
  # @return [void]
@@ -717,63 +1213,85 @@ module Pikuri
717
1213
  return unless msg.role == :assistant
718
1214
 
719
1215
  text = msg.thinking&.text
720
- @listeners.emit(Event::Thinking.new(content: text)) if text && !text.empty?
1216
+ @listeners.on_event(Event::Thinking.new(content: text)) if text && !text.empty?
721
1217
 
722
1218
  content = msg.content
723
- @listeners.emit(Event::Assistant.new(content: content)) if content.is_a?(String) && !content.empty?
724
-
725
- @listeners.emit(Event::Tokens.new(
726
- input: msg.input_tokens,
727
- output: msg.output_tokens,
728
- cached: msg.cached_tokens,
729
- cache_creation: msg.cache_creation_tokens,
730
- thinking: msg.thinking_tokens,
731
- model_id: msg.model_id
1219
+ @listeners.on_event(Event::Assistant.new(content: content)) if content.is_a?(String) && !content.empty?
1220
+
1221
+ @listeners.on_event(Event::Tokens.new(
1222
+ input: msg.tokens.input,
1223
+ output: msg.tokens.output,
1224
+ cached: msg.tokens.cache_read,
1225
+ cache_creation: msg.tokens.cache_write,
1226
+ thinking: msg.tokens.thinking,
1227
+ model_id: msg.model
732
1228
  ))
733
1229
  end
734
1230
 
735
- # Normalize a +RubyLLM::Chunk+ from a streaming completion
736
- # into zero, one, or two delta events
737
- # ({Event::ThinkingDelta} / {Event::AssistantDelta}). Empty
738
- # +thinking.text+ and empty +content+ are filtered here so
739
- # listeners never see vacuous fragments. Tool-call deltas are
740
- # intentionally skipped — see {#streaming_block}.
741
- #
742
- # +chunk+ is a +RubyLLM::Chunk+ (subclass of +RubyLLM::Message+),
743
- # so the same +.thinking+ / +.content+ accessors used in
744
- # {#emit_after_message} apply.
1231
+ # Normalize a streaming +RubyLLM::Chunk+ into delta events
1232
+ # ({Event::ThinkingDelta}/{Event::AssistantDelta}). Empty fragments are
1233
+ # filtered; tool-call deltas skipped (see {#streaming_block}).
745
1234
  #
746
1235
  # @param chunk [RubyLLM::Chunk]
747
1236
  # @return [void]
748
1237
  def emit_chunk(chunk)
749
1238
  thinking = chunk.thinking&.text
750
- @listeners.emit(Event::ThinkingDelta.new(content: thinking)) if thinking && !thinking.empty?
751
-
1239
+ @listeners.on_event(Event::ThinkingDelta.new(content: thinking)) if thinking && !thinking.empty?
752
1240
  content = chunk.content
753
- @listeners.emit(Event::AssistantDelta.new(content: content)) if content.is_a?(String) && !content.empty?
1241
+ @listeners.on_event(Event::AssistantDelta.new(content: content)) if content.is_a?(String) && !content.empty?
754
1242
  end
755
1243
 
756
- # Drain the interloper queue: for each pending item, append a
757
- # +role: :user+ message to the chat history so the next
758
- # round-trip sees it, emit an {Event::UserTurn} with
759
- # +mid_loop: true+ to the listener stream so renderers see the
760
- # injection, then run the per-turn {Extension#on_user_message}
761
- # dispatch (so mid-loop injections are prefetched + recorded
762
- # exactly like initial turns).
1244
+ # Drain the interloper queue, landing each item per its
1245
+ # {Control::Interloper::Item#kind}:
1246
+ #
1247
+ # - +:user+ — append +role: :user+ verbatim, emit {Event::UserTurn}
1248
+ # (+mid_loop: true+), then run the {Extension#on_user_message} dispatch
1249
+ # (so mid-loop injections are prefetched + recorded like initial turns).
1250
+ # The dispatch runs *after* the append so an injected +<memory-context>+
1251
+ # lands right behind the turn it annotates. An attachment the stated
1252
+ # {ChatTransport#modalities} refuse is withheld with a {Pikuri::Attachment#withheld_note} in the
1253
+ # text, never raised: this runs inside the turn, which a raise would end.
1254
+ # The +UserTurn+ carries what was sent, notes included; the extension
1255
+ # dispatch gets the user's own text (+""+ on an attachment-only item)
1256
+ # and the attachments that went out.
1257
+ # - +:system+ — {#append_reference_block}: reference text, so no
1258
+ # +on_user_message+ dispatch and no +UserTurn+.
763
1259
  #
764
- # The dispatch runs *after* the +:user+ append so any
765
- # +<memory-context>+ it injects lands as a +:system+ message
766
- # right behind the user turn it annotates — the same
767
- # append-at-the-tail ordering {#run_loop} produces for initial
768
- # turns.
1260
+ # Both kinds reach the wire as +role: :user+ and differ in dispatch and in
1261
+ # the envelope — only the +:system+ kind is wrapped. That is the whole
1262
+ # distinction, and it is why the queue keeps two kinds rather than a
1263
+ # +wrap:+ flag.
769
1264
  #
770
1265
  # @return [void]
1266
+ # @raise [RuntimeError] on an unknown item kind (a bug — only the two
1267
+ # +inject_*+ producers exist)
771
1268
  def drain_interloper
772
- @interloper.drain!.each do |content|
773
- @chat.add_message(role: :user, content: content)
774
- @listeners.emit(Event::UserTurn.new(content: content, mid_loop: true))
775
- dispatch_ext_on_user_message(content)
1269
+ @interloper.drain!.each do |item|
1270
+ case item.kind
1271
+ when :user
1272
+ drain_user_item(item)
1273
+ when :system
1274
+ append_reference_block(item.content)
1275
+ else
1276
+ raise "unknown interloper item kind: #{item.kind.inspect}"
1277
+ end
776
1278
  end
777
1279
  end
1280
+
1281
+ # Land one +:user+ {Control::Interloper::Item}; see {#drain_interloper}.
1282
+ #
1283
+ # @param item [Control::Interloper::Item]
1284
+ # @return [void]
1285
+ def drain_user_item(item)
1286
+ refused, sent = item.attachments.map { |a| [a, attachment_refusal(a)] }.partition(&:last)
1287
+ sent = sent.map(&:first)
1288
+ text = [item.content, *refused.map { |a, reason| a.withheld_note(reason) }]
1289
+ .reject { |t| t.to_s.strip.empty? }.join("\n\n")
1290
+ message = { role: :user, content: text.empty? ? nil : text }
1291
+ message[:attachments] = sent.map(&:to_ruby_llm) unless sent.empty?
1292
+ track_message(@chat.add_message(message))
1293
+ @listeners.on_event(Event::UserTurn.new(content: text, attachments: sent, mid_loop: true))
1294
+ dispatch_ext_on_user_message(item.content, sent)
1295
+ end
778
1296
  end
779
1297
  end