pikuri-core 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +16 -29
  3. data/lib/pikuri/agent/chat_transport.rb +114 -33
  4. data/lib/pikuri/agent/configurator.rb +191 -110
  5. data/lib/pikuri/agent/control/cancellable.rb +25 -16
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +87 -120
  8. data/lib/pikuri/agent/control.rb +9 -11
  9. data/lib/pikuri/agent/event.rb +73 -61
  10. data/lib/pikuri/agent/extension.rb +45 -81
  11. data/lib/pikuri/agent/history.rb +91 -497
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +115 -108
  14. data/lib/pikuri/agent/listener/token_log.rb +21 -55
  15. data/lib/pikuri/agent/listener.rb +4 -4
  16. data/lib/pikuri/agent/listener_list.rb +19 -13
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +624 -448
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/extractor/passthrough.rb +5 -2
  21. data/lib/pikuri/extractor.rb +43 -12
  22. data/lib/pikuri/file_type.rb +4 -4
  23. data/lib/pikuri/finalizers.rb +2 -2
  24. data/lib/pikuri/paths.rb +1 -1
  25. data/lib/pikuri/sanitizer.rb +4 -3
  26. data/lib/pikuri/subprocess.rb +17 -5
  27. data/lib/pikuri/testing.rb +122 -49
  28. data/lib/pikuri/tool/calculator.rb +134 -30
  29. data/lib/pikuri/tool/execute_context.rb +2 -2
  30. data/lib/pikuri/tool/parameters.rb +10 -0
  31. data/lib/pikuri/tool/result.rb +164 -0
  32. data/lib/pikuri/tool/trifecta_legs.rb +52 -21
  33. data/lib/pikuri/tool.rb +298 -24
  34. data/lib/pikuri/trifecta/report.rb +28 -30
  35. data/lib/pikuri/trifecta.rb +1 -2
  36. data/lib/pikuri/version.rb +1 -1
  37. data/lib/pikuri-core.rb +5 -11
  38. metadata +16 -73
  39. data/lib/pikuri/agent/context_window_detector.rb +0 -181
  40. data/lib/pikuri/agent/control/step_limit.rb +0 -95
  41. data/lib/pikuri/agent/extension_context.rb +0 -120
  42. data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
  43. data/lib/pikuri/agent/synthesizer.rb +0 -129
  44. data/lib/pikuri/extractor/html.rb +0 -256
  45. data/lib/pikuri/ruby_llm_patches.rb +0 -106
  46. data/lib/pikuri/tool/fetch.rb +0 -146
  47. data/lib/pikuri/tool/scraper.rb +0 -144
  48. data/lib/pikuri/tool/search/brave.rb +0 -170
  49. data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
  50. data/lib/pikuri/tool/search/engines.rb +0 -319
  51. data/lib/pikuri/tool/search/exa.rb +0 -195
  52. data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
  53. data/lib/pikuri/tool/search/result.rb +0 -24
  54. data/lib/pikuri/tool/web_scrape.rb +0 -105
  55. data/lib/pikuri/tool/web_search.rb +0 -133
  56. data/lib/pikuri/url_cache.rb +0 -96
data/lib/pikuri/agent.rb CHANGED
@@ -14,38 +14,49 @@ module Pikuri
14
14
  # 1. **Listeners** ({ListenerList} + {Listener::Base}) — pure consumers
15
15
  # of the event stream, never writing back. The +Agent+ emits every
16
16
  # loop-narration {Event}; extensions emit domain events through the
17
- # {ExtensionContext} handed to {Extension#bind}. No public path leads
17
+ # {Configurator} handed to {Extension#configure}. No public path leads
18
18
  # from an +Agent+ reference to emission (no +listeners+/+chat+ reader,
19
19
  # no emit method), so holding an agent grants read access and nothing
20
20
  # more. New sinks are added as listeners without touching {Agent}.
21
- # 2. **Controls** ({Control::StepLimit}, {Control::Cancellable},
22
- # {Control::Interloper}) — host-facing signal holders the +Agent+
23
- # reads at fixed boundaries: +tick!+/+check!+ on every
24
- # +before_tool_call+, +reset!+ at turn start, +drain!+ once each tool
25
- # batch is answered.
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.
26
25
  #
27
- # "What fires when" is one grep for +@listeners.emit+ (loop narration)
28
- # plus the capability calls in {ExtensionContext} (domain events).
26
+ # "What fires when" is one grep for +@listeners.on_event+ (loop narration)
27
+ # plus {Configurator#emit_event} (domain events).
29
28
  #
30
- # == Step-exhaustion policy
29
+ # == One agent, one conversation
31
30
  #
32
- # When +step_limit:+ trips during completion, {#run_loop} applies its
33
- # {Control::StepLimit#on_exhausted} 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:
34
35
  #
35
- # - +:raise+ (default) — re-raise to the host. History survives and
36
- # {Control::StepLimit#reset!} fires next turn, so "continue" works.
37
- # - +:synthesize+ — emit an {Event::FallbackNotice} and run the
38
- # {Synthesizer} prompt on a nested tools-free +Agent+ (listener stream
39
- # via {ListenerList#for_sub_agent}, +cancellable+ shared so a user
40
- # cancel still works, a defensive +step_limit+ at +max: 1+). Its answer
41
- # becomes {#last_assistant_content}, so callers still get a reply.
36
+ # history = agent.export_history
37
+ # agent.close
38
+ # agent = Pikuri::Agent.new(transport: t, system_prompt: p, history: history) { |c| wire(c) }
39
+ #
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+.
42
53
  #
43
54
  # == Cancellation rescue
44
55
  #
45
56
  # When +cancellable:+ trips during +Chat#ask+, {#run_loop} emits an
46
- # {Event::Cancelled} and re-raises — no synthesizer fallback (cancel
47
- # means drop everything). {Control::Cancellable#reset!} at each turn
48
- # start lets the same instance take a fresh turn afterwards.
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.
49
60
  #
50
61
  # == Threading
51
62
  #
@@ -63,6 +74,13 @@ module Pikuri
63
74
  #
64
75
  # agents.map { |a| Thread.new { a.run_loop(user_message: task_for(a)) } }.each(&:join)
65
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
+ #
66
84
  # Two {Control}s are the sanctioned doors *in* from another thread, which is
67
85
  # why they carry locks and the agent does not: {Control::Cancellable} (stop
68
86
  # the turn) and {Control::Interloper} (queue a mid-turn message, delivered at
@@ -83,46 +101,32 @@ module Pikuri
83
101
  REFERENCE_TAG = 'system-reminder'
84
102
  private_constant :REFERENCE_TAG
85
103
 
86
- # Provider slugs (matched against +@chat.model.provider+) whose wire format
87
- # carries system content in a top-level request field rather than as an
88
- # element of +messages+ — Anthropic's +system+ param, Bedrock's +system+
89
- # blocks. ruby_llm's provider splits it out at payload-render time
90
- # (+messages.partition { |m| m.role == :system }+), so a conversation
91
- # holding nothing but the system prompt renders +messages: []+ and the API
92
- # 400s — see {EmptyTurnError}. Everywhere else +:system+ is an ordinary
93
- # array element (OpenAI, Gemini) and that same conversation is a legal
94
- # one-message request.
95
- #
96
- # Only +:system+ moves — a placement difference in the payload, not a
97
- # rewrite of what pikuri appended, so the +:user+ blocks of
98
- # {#append_reference_block} ride through untouched on every provider here.
99
- SEPARATE_SYSTEM_FIELD_PROVIDERS = %w[anthropic bedrock].freeze
100
- private_constant :SEPARATE_SYSTEM_FIELD_PROVIDERS
101
-
102
- # A blank turn was requested against a conversation holding nothing but the
103
- # assembled system prompt, on a provider that would render that as
104
- # +messages: []+ (see {SEPARATE_SYSTEM_FIELD_PROVIDERS}):
105
- #
106
- # agent.run_loop(user_message: nil) # fresh chat, backend Anthropic
107
- # # => EmptyTurnError; the host catches it and prompts for a real message
108
- #
109
- # Narrow by construction: every *injected* block lands as +role: :user+
110
- # ({#append_reference_block}), so a skill-only or memory-only bare load has
111
- # a message to complete against and never reaches here. What remains is a
112
- # genuinely empty conversation.
113
- #
114
- # Content-neutral: {#provider} is all it carries — the host owns any
115
- # user-facing wording.
116
- class EmptyTurnError < StandardError
117
- # @return [String] the resolved provider slug that can't complete the turn
118
- attr_reader :provider
119
-
120
- # @param provider [String] the resolved provider slug (e.g. +"anthropic"+)
121
- def initialize(provider)
122
- @provider = provider
123
- super("#{provider} cannot complete a turn whose conversation holds only " \
124
- ':system content (no user or assistant message): it would send an ' \
125
- 'empty messages array. Add a user message.')
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}")
126
130
  end
127
131
  end
128
132
 
@@ -140,27 +144,39 @@ module Pikuri
140
144
  # @see CANCELLED_RESULT
141
145
  CANCELLED_SKIPPED_RESULT = '[Not executed — the user cancelled this turn]'
142
146
  # @see CANCELLED_RESULT
143
- STEP_BUDGET_RESULT = '[Not executed — step budget exhausted]'
144
- # @see CANCELLED_RESULT
145
147
  FAILED_SKIPPED_RESULT = '[Not executed — a previous tool call in this batch failed]'
146
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
+
147
155
  # @param transport [ChatTransport] model-resolution bundle (+model+ /
148
156
  # +provider+ / +assume_model_exists+ and, off the global server,
149
157
  # +api_base+ / +api_key+). A +nil+ +transport.model+ is filled from
150
158
  # +RubyLLM.config.default_model+.
151
159
  # @param system_prompt [String] base system message; the chat sees
152
160
  # this plus every extension's {Extension#system_prompt_snippets},
153
- # assembled by {#assemble_system_prompt} at construction and on each
154
- # {#clear_conversation}.
155
- # @param step_limit [Control::StepLimit, nil] step budget, or +nil+ for
156
- # no budget (unbounded looping). Its {Control::StepLimit#on_exhausted}
157
- # policy drives {#run_loop} on trip (see the class header).
161
+ # assembled once by {#assemble_system_prompt}.
158
162
  # @param cancellable [Control::Cancellable, nil] cancellation control,
159
163
  # or +nil+ for none (no way to stop a running turn but killing the
160
164
  # process).
161
- # @param interloper [Control::Interloper, nil] mid-loop user-input queue
162
- # drained once each tool batch is answered (each item becomes an
163
- # {Event::UserTurn} with +mid_loop: true+), or +nil+ for none.
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.
164
180
  # @param id [String] unique id; empty for the main agent, persona-rooted
165
181
  # for sub-agents (+"researcher 0"+, ...). Distinct from a persona's
166
182
  # +name+ (the value the LLM picks in the +agent+ tool's +name:+ arg).
@@ -168,33 +184,43 @@ module Pikuri
168
184
  # passes a per-chunk block to +Chat#complete+ and normalizes chunks
169
185
  # into {Event::ThinkingDelta}/{Event::AssistantDelta}. Default +false+
170
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.
171
192
  # @yield [Configurator] the sole path for adding tools, listeners,
172
193
  # extensions, and +on_close+ handlers — there are no parallel ctor
173
194
  # kwargs. Optional; without it the agent has none of those.
174
195
  # @return [Agent]
196
+ # @raise [ArgumentError] if +history+ is neither +nil+ nor a {History}.
175
197
  def initialize(transport:, system_prompt:,
176
- step_limit: nil, cancellable: nil, interloper: nil,
198
+ cancellable: nil,
199
+ around_request: nil,
177
200
  id: '',
178
201
  streaming: false,
202
+ history: nil,
179
203
  &block)
204
+ unless history.nil? || history.is_a?(History)
205
+ raise ArgumentError, "expected a Pikuri::Agent::History, got #{history.class}"
206
+ end
207
+
180
208
  @transport = transport.model ? transport : transport.with(model: RubyLLM.config.default_model)
181
209
  @cancellable = cancellable
210
+ @around_request = around_request
182
211
  @closed = false
183
212
 
184
- # Kept separate from the assembled +@system_prompt+ so
185
- # {#assemble_system_prompt} can recompute (base + extensions'
186
- # snippets) from scratch at construction and on each
187
- # {#clear_conversation}, refreshing dynamic sections.
188
213
  @system_prompt_base = system_prompt
189
214
  @system_prompt = system_prompt
190
- @step_limit = step_limit
191
- @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
192
218
  @id = id
193
219
  @streaming = streaming
194
- @synth_answer = nil
195
220
  @on_close_handlers = []
196
221
  # Stashed for {#run_configure}, the failure-prone build phase.
197
222
  @block = block
223
+ @history = history
198
224
 
199
225
  # Register *before* the build phase so a mid-construction raise is
200
226
  # recoverable: extensions arm cleanup via +c.on_close+ (straight into
@@ -213,9 +239,16 @@ module Pikuri
213
239
  end
214
240
  end
215
241
 
216
- # @return [ChatTransport] the resolved transport this agent was built
217
- # with — the model/provider/connection every +RubyLLM.chat+ from this
218
- # agent uses (main chat, synthesizer, sub-agents).
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+
219
252
  attr_reader :transport
220
253
 
221
254
  # @return [Array<Tool>] tool list in declaration order. These are the
@@ -230,28 +263,28 @@ module Pikuri
230
263
  # see {Configurator}.
231
264
  attr_reader :sub_agent_tools
232
265
 
233
- # @return [String] resolved model id from {#transport}.
234
- def model
235
- @transport.model
236
- end
237
-
238
266
  # @return [String] system prompt actually sent — the base
239
267
  # +system_prompt:+ plus every extension's
240
- # {Extension#system_prompt_snippets}, re-assembled on
241
- # {#clear_conversation} (so a dynamic section may differ from its
242
- # construction value). Not inherited by sub-agents.
268
+ # {Extension#system_prompt_snippets}. Not inherited by sub-agents.
243
269
  attr_reader :system_prompt
244
270
 
245
- # @return [Control::StepLimit, nil] the step budget, or +nil+.
246
- attr_reader :step_limit
247
-
248
271
  # @return [Control::Cancellable, nil] the cancellation control, or
249
272
  # +nil+. Extensions read it to propagate cancellation to their own
250
273
  # LLM calls (the +agent+ tool shares it so one Ctrl+C stops the tree).
251
274
  attr_reader :cancellable
252
275
 
253
- # @return [Control::Interloper, nil] the mid-loop user-input control, or
254
- # +nil+.
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]
255
288
  attr_reader :interloper
256
289
 
257
290
  # @return [String] this agent's id — empty for the main agent,
@@ -264,55 +297,55 @@ module Pikuri
264
297
  # (see {#initialize}'s +streaming:+).
265
298
  attr_reader :streaming
266
299
 
267
- # @return [Array<Extension>] extensions bound to this agent. Each one's
268
- # +configure+ ran during the +Agent.new+ block, its +bind+ at the end
269
- # of {#initialize}. Not inherited by sub-agents.
300
+ # @return [Array<Extension>] extensions added to this agent, whose
301
+ # +configure+ ran during the +Agent.new+ block. Not inherited by
302
+ # sub-agents.
270
303
  attr_reader :extensions
271
304
 
272
- # @return [Integer, nil] resolved context-window cap — the
273
- # {ChatTransport#context_window} if given, else the
274
- # {ContextWindowDetector} probe; +nil+ when neither yields one.
275
- # Re-resolved on every model switch.
276
- attr_reader :context_window_cap
277
-
278
- # Final assistant message content for the most recent
279
- # {#run_loop}. When the synthesizer rescue fired, returns its
280
- # answer; otherwise walks the underlying chat's history.
281
- # Returns +nil+ if neither source has produced an assistant
282
- # 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.
283
308
  #
284
309
  # @return [String, nil]
285
310
  def last_assistant_content
286
- return @synth_answer if @synth_answer
287
-
288
311
  last = @chat.messages.reverse.find { |m| m.role == :assistant }
289
312
  last&.content
290
313
  end
291
314
 
292
- # Run the agent loop for one turn. With a +user_message+, emits an
293
- # {Event::UserTurn} (+mid_loop: false+) and appends it; with none, runs a
294
- # *bare* turn against whatever the conversation + drained injections
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
295
318
  # already hold — the case a host uses after loading a skill on its own
296
- # initiative, so the agent reacts to it. Resets the step/cancellation
297
- # controls, drains any pending {Control::Interloper} injections, then
298
- # +complete+s the chat. Output is the listeners' job; subsequent calls
299
- # build on the same history.
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)])
300
326
  #
301
- # A blank +user_message+ against a conversation holding nothing but the
302
- # system prompt is provider-split: providers that can't complete it raise
303
- # {EmptyTurnError}, the rest run the turn against that history. A blank turn
304
- # *mid-conversation* always proceeds — real turns remain to answer, and a
305
- # drained injection is itself one.
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.
306
330
  #
307
- # Step-limit and cancellation trips are handled per the class header's
308
- # "Step-exhaustion policy" / "Cancellation rescue".
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.
309
336
  #
310
337
  # == Switching models mid-conversation
311
338
  #
312
- # A +transport:+ differing from the current one switches the chat to it
313
- # (via {#apply_transport!}), re-resolves the cap, and emits
314
- # {Event::ModelSwitched} + a fresh {Event::ContextCap}. The switch is
315
- # confined to the top of this method because the chat is
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
316
349
  # single-thread-confined — a background thread mutating the connection
317
350
  # mid-completion would tear an in-flight stream. The conversation is
318
351
  # *not* re-baselined: same conversation, new model, so message count and
@@ -322,66 +355,69 @@ module Pikuri
322
355
  #
323
356
  # ruby_llm appends the assistant +tool_calls+ message *before* running any
324
357
  # of them, so anything unwinding out of the batch — a tool raising, a
325
- # {Control::Cancellable::Cancelled}, a tripped budget, an untrapped
326
- # +Interrupt+ — leaves calls no +:tool+ message answers. OpenAI and
327
- # Anthropic 400 on that; a local llama.cpp feeds it to the chat template
328
- # and the model improvises. So an +ensure+ answers each dangling call
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
329
362
  # ({#repair_dangling_tool_calls!}) and the exception then propagates: a
330
363
  # host that keeps the conversation gets one it can still send.
331
364
  #
332
365
  # +ensure+ rather than a clause per +rescue+, because it also catches what
333
- # nobody enumerated (+Interrupt+ is no +StandardError+) and it runs *after*
334
- # the +:synthesize+ rescue body, leaving {Synthesizer.build_prompt} the
335
- # unrepaired history its drop-calls-with-no-result pass expects.
366
+ # nobody enumerated (+Interrupt+ is no +StandardError+) and it is a no-op
367
+ # on the success path.
336
368
  #
337
- # Unlike {History#repair_interrupted_tool_calls} — the load path, where a
369
+ # Unlike {History#repair_interrupted_tool_calls} — the resume path, where a
338
370
  # killed process leaves no clue and {History::INTERRUPTED_RESULT} has to be
339
371
  # generic — the cause is in hand here and picks the wording.
340
372
  #
341
- # @param user_message [String, nil] the turn's request; +nil+/blank runs a
342
- # bare turn (see above)
343
- # @param transport [ChatTransport, nil] when non-+nil+ and structurally
344
- # different, switch to it before the turn; +nil+ keeps the model
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
345
379
  # @raise [Control::Cancellable::Cancelled] if cancelled mid-turn (an
346
380
  # {Event::Cancelled} is emitted first)
347
- # @raise [Control::StepLimit::Exceeded] if the budget tripped under the
348
- # +:raise+ policy
349
- # @raise [EmptyTurnError] on a blank turn against a prompt-only
350
- # conversation when the provider carries +:system+ outside +messages+
351
- # (see above)
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
352
384
  # @return [nil] after a turn runs
353
- def run_loop(user_message: nil, transport: nil)
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
389
+
354
390
  apply_transport!(transport) if transport
355
- @synth_answer = nil
356
- @step_limit&.reset!
357
- @cancellable&.reset!
358
391
 
359
392
  # Deliver host-scheduled injections (e.g. a UI-loaded skill) before the
360
393
  # first complete, so a freshly-scheduled block lands this turn rather
361
394
  # than only after the next tool batch — ordered ahead of the user
362
395
  # message appended below.
363
- drain_interloper if @interloper
364
-
365
- blank = user_message.nil? || user_message.to_s.strip.empty?
366
- # These providers would send `messages: []` here (see EmptyTurnError).
367
- # The drain above is what usually saves this case: an injected block is a
368
- # :user message, so a skill-only bare load has something to complete
369
- # against and falls through.
370
- if blank && @chat.messages.all? { |m| m.role == :system } &&
371
- SEPARATE_SYSTEM_FIELD_PROVIDERS.include?(@chat.model.provider.to_s)
372
- raise EmptyTurnError, @chat.model.provider
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
373
404
  end
374
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.)
375
411
  unless blank
376
- # Append the user turn, emit it, then run the memory dispatch — so any
377
- # <memory-context> the dispatch injects lands as a :system message
378
- # *after* the user turn it annotates. (+ask+ bundles append+complete
379
- # atomically, leaving no seam to inject between; the halves run
380
- # explicitly instead.)
381
- track_message(@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)
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))
384
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
385
421
 
386
422
  if @streaming
387
423
  @chat.complete(&streaming_block)
@@ -390,148 +426,44 @@ module Pikuri
390
426
  end
391
427
  nil
392
428
  rescue Control::Cancellable::Cancelled
393
- @listeners.emit(Event::Cancelled.new)
429
+ @listeners.on_event(Event::Cancelled.new)
394
430
  raise
395
- rescue Control::StepLimit::Exceeded => e
396
- raise unless @step_limit&.on_exhausted == :synthesize
397
-
398
- # Ruby restores +$!+ once a rescue clause completes normally, so the
399
- # +ensure+ below would see no cause for this one unwind. Assigned before
400
- # the synth runs, so a synth that raises doesn't displace the real reason.
401
- exhausted = e
402
- @synth_answer = Synthesizer.run_synthesizer(@extension_context, @chat.messages, user_message)
403
- nil
404
431
  ensure
405
- repair_dangling_tool_calls!(exhausted || $!)
406
- end
407
-
408
- # Return the agent to a fresh-conversation state without tearing down
409
- # its wiring — the host "/clear". Unlike {#close} (which fires the
410
- # teardown handlers), everything stays alive; nothing is re-probed or
411
- # re-connected. Resets, in order:
412
- #
413
- # 1. Chat history (+Chat#reset_messages!+, which also drops every injected
414
- # reference block), then re-applies a freshly **re-assembled** prompt —
415
- # {#assemble_system_prompt} re-pulls every extension's snippets, so
416
- # dynamic sections refresh (a resident memory persona, a re-read
417
- # +MACHINE.md+). Callbacks and tool registrations on the reused +@chat+
418
- # are untouched.
419
- # 2. Controls — step/cancellation reset, interloper queue drained (stale
420
- # mid-loop input must not leak forward), cached synth answer dropped.
421
- # 3. Listeners — a single {Event::Reset} so they reset display state.
422
- # 4. Extension state — {Extension#on_conversation_reset} on each.
423
- #
424
- # Model/transport are left as-is (a clear is not a model switch). Runs on
425
- # the agent's own thread; not designed to race an in-flight {#run_loop}.
426
- #
427
- # @return [void]
428
- def clear_conversation
429
- @chat.reset_messages!
430
- @message_meta.clear
431
- @system_prompt = assemble_system_prompt
432
- @chat.with_instructions(@system_prompt)
433
- @synth_answer = nil
434
- @step_limit&.reset!
435
- @cancellable&.reset!
436
- @interloper&.drain!
437
- @listeners.emit(Event::Reset.new)
438
- @extensions.each { |ext| ext.on_conversation_reset(@extension_context) }
439
- nil
432
+ repair_dangling_tool_calls!($!)
440
433
  end
441
434
 
442
435
  # Snapshot the conversation as a {History} — the round-trip partner of
443
- # {#load_history!}, and the supported way for a host to persist a
444
- # conversation without reaching into the underlying chat.
436
+ # +Agent.new(history:)+, and the only way a conversation leaves the agent;
437
+ # storing it is the host's.
445
438
  #
446
- # agent.export_history.save(dir) # a folder per conversation
447
- # File.write(f, agent.export_history.to_json) # or one self-contained file
439
+ # history = agent.export_history
448
440
  #
449
- # The system prompt is excluded — {#load_history!} re-assembles it, so a
450
- # resumed conversation gets today's, not the one that was current when it
451
- # was saved.
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.
452
444
  #
453
445
  # Attachment bytes are read here, eagerly, so the snapshot still shows
454
446
  # what the model saw after the file has changed on disk.
455
447
  #
456
448
  # A thinking block withheld from the conversation because another model
457
449
  # produced it is restored here from the message's metadata, so the record
458
- # survives any number of load/save cycles under a switched model.
450
+ # survives any number of resumes under a switched model.
459
451
  #
460
452
  # @return [History]
461
453
  def export_history
462
454
  exported = @chat.messages.reject { |m| m.role == :system }.map do |msg|
463
455
  meta = @message_meta[msg] || { id: History.mint_id, kind: 'user' }
464
- exported_msg = History::Message.from_ruby_llm(msg, id: meta[:id], kind: meta[:kind])
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
+ )
465
460
  meta[:thinking] ? exported_msg.with(thinking: meta[:thinking]) : exported_msg
466
461
  end
467
462
  History.new(messages: exported)
468
463
  end
469
464
 
470
- # Replace the conversation with a saved one, keeping every bit of wiring
471
- # — tools, listeners, extensions, model — in place.
472
- #
473
- # agent.load_history!(History.load(dir))
474
- #
475
- # Runs {#clear_conversation} first, so controls reset and extensions see
476
- # {Extension#on_conversation_reset} exactly as they would on a host
477
- # "/clear"; the system prompt is re-assembled from current state. Then
478
- # emits {Event::HistoryLoaded} — {Event::Reset} alone would tell listeners
479
- # the conversation is empty, which it no longer is.
480
- #
481
- # Safe to call repeatedly on a long-lived agent: switching conversations
482
- # in a shell is exactly this, once per switch, and nothing survives across
483
- # one. Like the rest of {Agent}, it must not race a running {#run_loop}.
484
- #
485
- # == What is restored, and what is not
486
- #
487
- # Messages, tool calls and their results, thinking, attachments, per-message
488
- # usage. **Not** state living outside the conversation: a workspace's
489
- # read-before-edit marks, promoted skills, a task list. A resumed
490
- # conversation whose transcript says a file was read will still be asked
491
- # to read it again before editing — which is right, since the file may
492
- # have changed while the conversation sat on disk.
493
- #
494
- # Two repairs happen on the way in, both because a stored conversation can
495
- # describe something a provider will not accept:
496
- #
497
- # - A tool call whose result never arrived gets a synthesized one
498
- # ({History#repair_interrupted_tool_calls}).
499
- # - A turn produced by a *different* model loses its whole thinking block
500
- # — a foreign one lands in a slot the receiving model reads as its own
501
- # scratchpad. Withheld from the conversation only; {#export_history}
502
- # still writes it. {#apply_transport!} repeats this for a switch that
503
- # happens later. See +DECISIONS.md+ +D_thinking_block_replay+.
504
- #
505
- # @param history [History] from {#export_history}, {History.parse} or
506
- # {History.load} — already validated by whichever door it came through.
507
- # @return [Integer] how many messages were restored.
508
- # @raise [ArgumentError] if given anything but a {History}; the parsing
509
- # doors are where untrusted input belongs.
510
- def load_history!(history)
511
- unless history.is_a?(History)
512
- raise ArgumentError, "expected a Pikuri::Agent::History, got #{history.class} — " \
513
- 'use History.parse / History.load to build one from stored bytes'
514
- end
515
-
516
- clear_conversation
517
- current_model = @chat.model&.id
518
- repaired = history.repair_interrupted_tool_calls
519
- repaired.messages.each do |m|
520
- keep = keep_thinking?(m.thinking, m.model_id, current_model)
521
- track_message(@chat.add_message(m.to_ruby_llm(keep_thinking: keep)),
522
- kind: m.kind, id: m.id, thinking: (m.thinking unless keep))
523
- end
524
-
525
- last = repaired.messages.reverse.find { |m| m.role == 'assistant' && m.tokens }
526
- @listeners.emit(Event::HistoryLoaded.new(
527
- messages: repaired.messages.size,
528
- tokens: last && Event::Tokens.new(**last.tokens.to_h, model_id: last.model_id)
529
- ))
530
- repaired.messages.size
531
- end
532
-
533
465
  # Release agent-owned resources: fire every handler registered via
534
- # {Configurator#on_close} and {ExtensionContext#on_close} in LIFO order,
466
+ # {Configurator#on_close} in LIFO order,
535
467
  # so a handler that depends on an earlier one tears down first. Each runs
536
468
  # in its own +rescue+ (an exception is logged, not propagated).
537
469
  # Idempotent.
@@ -551,18 +483,6 @@ module Pikuri
551
483
  end
552
484
  end
553
485
 
554
- # Short, single-line config dump suitable for a startup
555
- # banner or a debug print.
556
- #
557
- # @example
558
- # agent.to_s
559
- # # => "Agent(id=, model=qwen3-35b, tools=4, listeners=[Terminal])"
560
- #
561
- # @return [String]
562
- def to_s
563
- "Agent(id=#{@id}, model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
564
- end
565
-
566
486
  # This agent's lethal-trifecta picture: which legs it holds, which its
567
487
  # sub-agents hold, the verdict at every node.
568
488
  #
@@ -586,48 +506,40 @@ module Pikuri
586
506
  private
587
507
 
588
508
  # The failure-prone build phase, split out of {#initialize} so the
589
- # constructor can wrap it in a rescue and self-heal. Funnels the
590
- # +Agent.new+ block through one {Configurator} (tools, listeners,
591
- # snippets, extensions, +on_close+), wires the chat, then runs the
592
- # extension +bind+ sweep. The Configurator's +on_close_sink:+ is
593
- # +@on_close_handlers+ itself, so a handler armed via +c.on_close+ is
594
- # live the instant it's registered — what lets the rescue close a
595
- # 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.
596
516
  #
597
517
  # @return [void]
598
518
  def run_configure
599
- configurator = Configurator.new(
600
- transport: @transport,
601
- system_prompt_base: @system_prompt,
602
- id: @id,
603
- streaming: @streaming,
604
- step_limit: @step_limit,
605
- cancellable: @cancellable,
606
- interloper: @interloper,
607
- on_close_sink: @on_close_handlers
608
- )
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)
609
523
 
610
524
  @block&.call(configurator)
611
525
 
612
526
  @tools = configurator.tools.dup
613
527
  @sub_agent_tools = configurator.sub_agent_tools.dup
614
- @listeners = ListenerList.new(configurator.listeners)
615
528
  @extensions = configurator.extensions.dup
616
529
  # Assemble now that every extension's +configure+ has run (their
617
- # snippets read populated state); re-runs on {#clear_conversation}.
530
+ # snippets read populated state).
618
531
  @system_prompt = assemble_system_prompt
619
-
620
- @chat = build_chat(@transport)
621
532
  @chat.with_instructions(@system_prompt)
622
533
  # One context per agent, so an opting-in +execute+ never has to nil-check
623
534
  # what it was handed.
624
535
  context = Tool::ExecuteContext.new(cancellable: @cancellable || Control::Cancellable::NEVER)
625
- @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool(context: context)) }
536
+ refusal = ->(attachment) { attachment_refusal(attachment) }
537
+ @tools.each { |t| @chat.with_tools(t.to_ruby_llm_tool(context: context, refusal: refusal)) }
626
538
 
627
539
  # Wire @chat for the event stream and controls via ruby_llm's three
628
540
  # registered callbacks. (The per-chunk streaming callback is separate
629
541
  # — {#streaming_block} — since ruby_llm takes it as a block to
630
- # +Chat#complete+, not a registered hook.) With the +@listeners.emit+
542
+ # +Chat#complete+, not a registered hook.) With the +@listeners.on_event+
631
543
  # calls in {#run_loop}/{#dispatch_ext_on_user_message}, this is the
632
544
  # complete callback→event map.
633
545
  # Identity-keyed, so nothing can drift out of alignment with
@@ -635,54 +547,174 @@ module Pikuri
635
547
  # never saw is simply absent here, and {#export_history} mints it an id
636
548
  # rather than silently pairing it with someone else's.
637
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
638
560
 
639
561
  @chat.after_message do |msg|
640
- track_message(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)
641
565
  emit_after_message(msg)
642
- drain_interloper if @interloper && tool_batch_complete?(msg)
566
+ drain_interloper if tool_batch_complete?(msg)
643
567
  end
644
568
  @chat.before_tool_call do |tc|
645
- @listeners.emit(Event::ToolCall.new(name: tc.name, arguments: tc.arguments))
646
- @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
+ ))
647
581
  @cancellable&.check!
648
582
  end
649
583
  @chat.after_tool_result do |result|
650
- @listeners.emit(Event::ToolResult.new(content: result))
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))
651
630
  end
652
631
 
653
- # Context-window cap on the stream before any Tokens event; re-fires
654
- # on each model switch (see {#apply_transport!}).
655
- detect_and_emit_context_cap!
656
-
657
- # The runtime capability facade — the ONLY object granting
658
- # emission / raw-tool / close-handler capabilities; the Agent exposes
659
- # no public path to them. Handed to every extension's #bind /
660
- # #on_user_message. See {ExtensionContext}.
661
- @extension_context = ExtensionContext.new(
662
- agent: self, chat: @chat, listeners: @listeners,
663
- 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)
664
636
  )
637
+ end
638
+
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}.
642
+ #
643
+ # @param history [History]
644
+ # @return [void]
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)
665
663
 
666
- # Bind sweep — each extension installs per-agent state now the chat is
667
- # fully wired (dynamic tools, close hooks, domain-event wiring). See
668
- # {Extension} for #configure vs #bind.
669
- @extensions.each { |ext| ext.bind(@extension_context) }
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
670
705
  end
671
706
 
672
707
  # Build the full prompt: base plus every extension's
673
708
  # {Extension#system_prompt_snippets}, in registration order, joined by
674
709
  # blank lines. Blank/nil sections drop (an extension contributing
675
- # nothing leaves no stray separator). Pure function of the base + the
676
- # extensions' current state, so it serves both construction and
677
- # {#clear_conversation} (the latter refreshing dynamic sections).
710
+ # nothing leaves no stray separator). Runs once, at construction.
678
711
  #
679
- # Those two call sites are the whole list, and that is a *price* rather
680
- # than a missing feature: a stable prefix is free after turn one
712
+ # That one call site is a *price* rather than a missing feature: a stable prefix is free after turn one
681
713
  # (llama.cpp slot prefix-reuse, Anthropic's prompt cache), where amending
682
714
  # one invalidates every cached token after the change point and
683
715
  # re-prefills. Hence there is no amend-the-prompt seam — mid-conversation
684
716
  # blocks go through {#append_reference_block}, which appends and
685
- # invalidates nothing. See `DECISIONS.md` `D_reference_text_as_user_turn`.
717
+ # invalidates nothing. See `design/decisions.md` `D_reference_text_as_user_turn`.
686
718
  #
687
719
  # @return [String]
688
720
  def assemble_system_prompt
@@ -692,81 +724,89 @@ module Pikuri
692
724
  .join("\n\n")
693
725
  end
694
726
 
695
- # Resolve the context-window cap and announce it as an
696
- # {Event::ContextCap}. The transport's explicit +context_window+ wins;
697
- # else {ContextWindowDetector} probes the server (+nil+ for a non-llama
698
- # one). The cap rides {ChatTransport}, so a switch resolves the *new*
699
- # transport's cap. Shared by {#run_configure} and {#apply_transport!}.
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.
700
734
  #
701
- # @return [void]
702
- def detect_and_emit_context_cap!
703
- # Probe the server this transport targets: after a cross-server switch
704
- # the chat points at +@transport.api_base+, but the global config still
705
- # names the old server — so derive the base from the transport.
706
- @context_window_cap = @transport.context_window ||
707
- ContextWindowDetector.detect(
708
- @transport,
709
- openai_base: @transport.api_base || RubyLLM.config.openai_api_base
710
- )
711
- @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
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"
712
743
  end
713
744
 
714
- # Switch the chat to +transport+ when it differs from the current one.
715
- # Called only from the top of {#run_loop} (see its "Switching models"
716
- # section for the thread-confinement reason). Mirrors {#initialize}'s
717
- # +nil+-model fill before the structural compare, so a transport
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
718
750
  # deferring to the default model doesn't switch spuriously.
719
- # +Chat#with_model+ keeps history and callbacks. Emits
720
- # {Event::ModelSwitched}, then re-resolves and re-emits the cap.
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.
721
765
  #
722
766
  # Because the history is kept, every turn in it is now potentially from
723
767
  # another model, so {#strip_foreign_thinking!} runs before the event —
724
- # {#load_history!}'s repair only covers a conversation that arrives stale.
768
+ # {#restore_history}'s repair only covers a conversation that arrives stale.
725
769
  #
726
- # == Cross-server switches
727
- #
728
- # +with_model+ re-resolves against the chat's existing connection, so it
729
- # only moves between models on one server. When either transport
730
- # overrides the connection (+ChatTransport#connection_overrides?+), a
731
- # fresh +RubyLLM::Context+ is installed via +Chat#with_context+ first
732
- # (re-pointing the connection, preserving history + callbacks). The "old
733
- # overrode" half handles switching *back* to a global-config model: the
734
- # rebuilt context dups the global config, resetting the prior override.
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+.
735
772
  #
736
773
  # @param transport [ChatTransport] the model to switch to
737
774
  # @return [void]
738
775
  def apply_transport!(transport)
739
776
  filled = transport.model ? transport : transport.with(model: RubyLLM.config.default_model)
740
- return if filled == @transport
741
-
742
777
  old = @transport
743
- @chat.with_context(build_context(filled)) if filled.connection_overrides? || old.connection_overrides?
744
- @chat.with_model(filled.model, provider: filled.provider, assume_exists: filled.assume_model_exists)
745
778
  @transport = filled
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)
746
784
  strip_foreign_thinking!
747
- @listeners.emit(Event::ModelSwitched.new(from: old, to: filled))
748
- detect_and_emit_context_cap!
785
+ @listeners.on_event(Event::ModelSwitched.new(from: old, to: filled))
749
786
  end
750
787
 
751
- # Build the chat for +transport+: through a dedicated +RubyLLM::Context+
752
- # when it overrides the connection, else through the process-global
753
- # +RubyLLM.chat+.
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+.
754
797
  #
755
798
  # @param transport [ChatTransport]
756
799
  # @return [RubyLLM::Chat]
757
800
  def build_chat(transport)
758
- if transport.connection_overrides?
759
- build_context(transport).chat(**transport.chat_kwargs)
760
- else
761
- RubyLLM.chat(**transport.chat_kwargs)
762
- end
801
+ build_context(transport).chat(**transport.chat_kwargs).with_provider_options(transport.params)
763
802
  end
764
803
 
765
804
  # A +RubyLLM::Context+ carrying +transport+'s connection overrides on the
766
805
  # provider's config slots (+#{provider}_api_base+ / +_api_key+).
767
806
  # +RubyLLM.context+ dups the global config, so an absent override inherits
768
- # the global value and a no-override transport yields a plain dup (used by
769
- # {#apply_transport!} to reset a prior override). +ChatTransport+
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+
770
810
  # guarantees a non-+nil+ +provider+ whenever an override is set.
771
811
  #
772
812
  # A transport's +faraday_adapter+ (if any) is installed here too: the
@@ -775,6 +815,11 @@ module Pikuri
775
815
  # {Pikuri::Testing.fake_transport} uses to run the real ruby_llm loop
776
816
  # against a scripted HTTP backend.
777
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.
822
+ #
778
823
  # @param transport [ChatTransport]
779
824
  # @return [RubyLLM::Context]
780
825
  def build_context(transport)
@@ -790,9 +835,37 @@ module Pikuri
790
835
  # prompt then arrives under a role token the model was not trained
791
836
  # on. pikuri targets local servers first, so ask for `system`.
792
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
793
849
  end
794
850
  end
795
851
 
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
+
796
869
  # Fire {Extension#on_user_message} on every extension, appending any
797
870
  # returned text via {#append_reference_block} right after the user turn it
798
871
  # annotates (the caller appends the +:user+ message first).
@@ -801,11 +874,13 @@ module Pikuri
801
874
  # (injects nothing), so opting out means leaving the default, not omitting
802
875
  # the method.
803
876
  #
804
- # @param content [String] the incoming user message
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
805
880
  # @return [void]
806
- def dispatch_ext_on_user_message(content)
881
+ def dispatch_ext_on_user_message(content, attachments)
807
882
  @extensions.each do |ext|
808
- message = ext.on_user_message(@extension_context, content)
883
+ message = ext.on_user_message(content, attachments)
809
884
  next unless message.is_a?(String) && !message.strip.empty?
810
885
 
811
886
  append_reference_block(message.strip)
@@ -833,11 +908,11 @@ module Pikuri
833
908
  # +:user+ rather than +:system+ because a mid-conversation +:system+ message
834
909
  # is not portable: Qwen3.6's chat template silently drops every one past the
835
910
  # leading header, and providers carrying +:system+ in a separate field
836
- # (Anthropic, Bedrock — see {SEPARATE_SYSTEM_FIELD_PROVIDERS}) merge it into
911
+ # (Anthropic's +system+ param, Bedrock's +system+ blocks) merge it into
837
912
  # the standing system prompt, so the block is presented as though it had
838
913
  # always been there and stays in force. Neither failure is visible from
839
914
  # anything pikuri can observe: the message is in the payload, the listener
840
- # stream renders it, the history holds it. See +DECISIONS.md+
915
+ # stream renders it, the history holds it. See +design/decisions.md+
841
916
  # +D_reference_text_as_user_turn+.
842
917
  #
843
918
  # A closing tag inside +content+ is escaped, so injected text (a file, a web
@@ -857,7 +932,7 @@ module Pikuri
857
932
  # injection from something the human typed — both land as +:user+.
858
933
  track_message(@chat.add_message(role: :user, content: "<#{REFERENCE_TAG}>\n#{body}\n#{close}"),
859
934
  kind: 'reference')
860
- @listeners.emit(Event::SystemInjected.new(content: content))
935
+ @listeners.on_event(Event::SystemInjected.new(content: content))
861
936
  nil
862
937
  end
863
938
 
@@ -875,14 +950,95 @@ module Pikuri
875
950
  # conversation); +nil+ mints a fresh one.
876
951
  # @param thinking [History::Thinking, nil] a block withheld from +msg+
877
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:}}+.
878
958
  # @return [RubyLLM::Message] +msg+, so call sites can wrap in place.
879
- def track_message(msg, kind: 'user', id: nil, thinking: nil)
959
+ def track_message(msg, kind: 'user', id: nil, thinking: nil, summary: nil, tool_calls: nil)
880
960
  unless msg.role == :system
881
- @message_meta[msg] = { id: id || History.mint_id, kind: kind, thinking: thinking }
961
+ @message_meta[msg] = { id: id || History.mint_id, kind: kind, thinking: thinking,
962
+ summary: summary, tool_calls: tool_calls }
882
963
  end
883
964
  msg
884
965
  end
885
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
+
886
1042
  # Whether a turn's thinking may be replayed to +current+ — true only where
887
1043
  # this model demonstrably produced it.
888
1044
  #
@@ -896,7 +1052,7 @@ module Pikuri
896
1052
  # only ever over-drops (a model loses its own reasoning; none is ever
897
1053
  # attributed to another), which is why the weaker test is tolerated; the
898
1054
  # fakes in +Pikuri::Testing+ are themselves such a backend. Measured
899
- # echoing verbatim on llama.cpp — see +DECISIONS.md+
1055
+ # echoing verbatim on llama.cpp — see +design/decisions.md+
900
1056
  # +D_thinking_block_replay+.
901
1057
  #
902
1058
  # @param thinking [History::Thinking, RubyLLM::Thinking, nil]
@@ -911,7 +1067,7 @@ module Pikuri
911
1067
  # live conversation, parking it in +@message_meta+ so {#export_history}
912
1068
  # still writes it.
913
1069
  #
914
- # {#load_history!} covers a conversation that arrives stale; this covers
1070
+ # {#restore_history} covers a conversation that arrives stale; this covers
915
1071
  # one that goes stale under a running agent, which +Chat#with_model+ leaves
916
1072
  # untouched. +RubyLLM::Message+ has no thinking writer, so a stripped turn
917
1073
  # is a rebuilt object and its metadata is re-keyed onto the replacement.
@@ -920,12 +1076,12 @@ module Pikuri
920
1076
  def strip_foreign_thinking!
921
1077
  current = @chat.model&.id
922
1078
  @chat.messages.map! do |msg|
923
- next msg if keep_thinking?(msg.thinking, msg.model_id, current)
1079
+ next msg if keep_thinking?(msg.thinking, msg.model, current)
924
1080
 
925
1081
  meta = @message_meta.delete(msg) || { id: History.mint_id, kind: 'user' }
926
1082
  stripped = RubyLLM::Message.new(
927
1083
  role: msg.role, content: msg.content, tool_calls: msg.tool_calls,
928
- tool_call_id: msg.tool_call_id, model_id: msg.model_id,
1084
+ tool_call_id: msg.tool_call_id, model: msg.model, attachments: msg.attachments,
929
1085
  tokens: msg.tokens, raw: msg.raw, thinking: nil
930
1086
  )
931
1087
  @message_meta[stripped] = meta.merge(
@@ -956,24 +1112,23 @@ module Pikuri
956
1112
  # batch on a turn that succeeded. Safe to raise from an +ensure+ here
957
1113
  # precisely because there is no in-flight exception to clobber.
958
1114
  def repair_dangling_tool_calls!(cause)
959
- messages = @chat.messages
960
- opener_index = messages.rindex { |m| m.role == :assistant && m.tool_calls&.any? }
961
- return if opener_index.nil?
962
-
963
- answered = messages[(opener_index + 1)..].filter_map { |m| m.tool_call_id if m.role == :tool }
964
- dangling = messages[opener_index].tool_calls.each_value.reject { |c| answered.include?(c.id) }
1115
+ dangling = unanswered_tool_calls
965
1116
  return if dangling.empty?
966
1117
 
967
1118
  if cause.nil?
968
1119
  raise 'unanswered tool calls on a turn that did not unwind: ' \
969
- "#{dangling.map { |c| "#{c.name}(#{c.id})" }.join(', ')}"
1120
+ "#{dangling.map { |c| "#{c.name}(#{c.provider_call_id})" }.join(', ')}"
970
1121
  end
971
1122
 
972
1123
  culprit, skipped = unanswered_results(cause)
973
1124
  dangling.each_with_index do |call, i|
974
1125
  content = i.zero? ? culprit : skipped
975
- track_message(@chat.add_message(role: :tool, content: content, tool_call_id: call.id))
976
- @listeners.emit(Event::ToolResult.new(content: content))
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))
977
1132
  end
978
1133
  LOGGER.warn { "answered #{dangling.size} dangling tool call(s) after #{cause.class}" }
979
1134
  nil
@@ -986,8 +1141,6 @@ module Pikuri
986
1141
  def unanswered_results(cause)
987
1142
  case cause
988
1143
  when Control::Cancellable::Cancelled then [CANCELLED_RESULT, CANCELLED_SKIPPED_RESULT]
989
- # An exhausted budget singles no call out.
990
- when Control::StepLimit::Exceeded then [STEP_BUDGET_RESULT, STEP_BUDGET_RESULT]
991
1144
  # Deliberately unsanitized: the message can carry untrusted bytes (a
992
1145
  # filename off a scraped page), which {Tool#run}'s own +"Error: ..."+
993
1146
  # already puts in the conversation — and a model cannot react to a
@@ -1018,13 +1171,6 @@ module Pikuri
1018
1171
  }
1019
1172
  end
1020
1173
 
1021
- # Normalize an +after_message+ payload into zero, one, or two {Event}s
1022
- # (+Thinking+ and/or +Assistant+) plus one {Event::Tokens}. Empty
1023
- # thinking/content are filtered here so listeners never see vacuous
1024
- # events; non-assistant roles are skipped.
1025
- #
1026
- # @param msg [RubyLLM::Message]
1027
- # @return [void]
1028
1174
  # Whether +msg+ closed a tool batch — the only mid-turn moment an injected
1029
1175
  # message may be appended.
1030
1176
  #
@@ -1041,47 +1187,58 @@ module Pikuri
1041
1187
  # @return [Boolean] true when +msg+ is the last tool result its assistant
1042
1188
  # message was waiting for (so parallel calls drain once, at the end)
1043
1189
  def tool_batch_complete?(msg)
1044
- return false unless msg.role == :tool
1190
+ msg.role == :tool && unanswered_tool_calls.empty?
1191
+ end
1045
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
1046
1197
  messages = @chat.messages
1047
1198
  opener_index = messages.rindex { |m| m.role == :assistant && m.tool_calls&.any? }
1048
- return true if opener_index.nil?
1199
+ return [] if opener_index.nil?
1049
1200
 
1050
1201
  answered = messages[(opener_index + 1)..].filter_map { |m| m.tool_call_id if m.role == :tool }
1051
- messages[opener_index].tool_calls.each_key.all? { |id| answered.include?(id) }
1202
+ messages[opener_index].tool_calls.each_value.reject { |c| answered.include?(c.id) }
1052
1203
  end
1053
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.
1209
+ #
1210
+ # @param msg [RubyLLM::Message]
1211
+ # @return [void]
1054
1212
  def emit_after_message(msg)
1055
1213
  return unless msg.role == :assistant
1056
1214
 
1057
1215
  text = msg.thinking&.text
1058
- @listeners.emit(Event::Thinking.new(content: text)) if text && !text.empty?
1216
+ @listeners.on_event(Event::Thinking.new(content: text)) if text && !text.empty?
1059
1217
 
1060
1218
  content = msg.content
1061
- @listeners.emit(Event::Assistant.new(content: content)) if content.is_a?(String) && !content.empty?
1062
-
1063
- @listeners.emit(Event::Tokens.new(
1064
- input: msg.input_tokens,
1065
- output: msg.output_tokens,
1066
- cached: msg.cached_tokens,
1067
- cache_creation: msg.cache_creation_tokens,
1068
- thinking: msg.thinking_tokens,
1069
- 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
1070
1228
  ))
1071
1229
  end
1072
1230
 
1073
- # Normalize a streaming +RubyLLM::Chunk+ into zero, one, or two delta
1074
- # events ({Event::ThinkingDelta}/{Event::AssistantDelta}). Empty
1075
- # fragments are filtered; tool-call deltas skipped (see {#streaming_block}).
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}).
1076
1234
  #
1077
1235
  # @param chunk [RubyLLM::Chunk]
1078
1236
  # @return [void]
1079
1237
  def emit_chunk(chunk)
1080
1238
  thinking = chunk.thinking&.text
1081
- @listeners.emit(Event::ThinkingDelta.new(content: thinking)) if thinking && !thinking.empty?
1082
-
1239
+ @listeners.on_event(Event::ThinkingDelta.new(content: thinking)) if thinking && !thinking.empty?
1083
1240
  content = chunk.content
1084
- @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?
1085
1242
  end
1086
1243
 
1087
1244
  # Drain the interloper queue, landing each item per its
@@ -1091,7 +1248,12 @@ module Pikuri
1091
1248
  # (+mid_loop: true+), then run the {Extension#on_user_message} dispatch
1092
1249
  # (so mid-loop injections are prefetched + recorded like initial turns).
1093
1250
  # The dispatch runs *after* the append so an injected +<memory-context>+
1094
- # lands right behind the turn it annotates.
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.
1095
1257
  # - +:system+ — {#append_reference_block}: reference text, so no
1096
1258
  # +on_user_message+ dispatch and no +UserTurn+.
1097
1259
  #
@@ -1107,9 +1269,7 @@ module Pikuri
1107
1269
  @interloper.drain!.each do |item|
1108
1270
  case item.kind
1109
1271
  when :user
1110
- @chat.add_message(role: :user, content: item.content)
1111
- @listeners.emit(Event::UserTurn.new(content: item.content, mid_loop: true))
1112
- dispatch_ext_on_user_message(item.content)
1272
+ drain_user_item(item)
1113
1273
  when :system
1114
1274
  append_reference_block(item.content)
1115
1275
  else
@@ -1117,5 +1277,21 @@ module Pikuri
1117
1277
  end
1118
1278
  end
1119
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
1120
1296
  end
1121
1297
  end