pikuri-core 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +16 -29
- data/lib/pikuri/agent/chat_transport.rb +114 -33
- data/lib/pikuri/agent/configurator.rb +191 -110
- data/lib/pikuri/agent/control/cancellable.rb +25 -16
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +87 -120
- data/lib/pikuri/agent/control.rb +9 -11
- data/lib/pikuri/agent/event.rb +73 -61
- data/lib/pikuri/agent/extension.rb +45 -81
- data/lib/pikuri/agent/history.rb +91 -497
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +115 -108
- data/lib/pikuri/agent/listener/token_log.rb +21 -55
- data/lib/pikuri/agent/listener.rb +4 -4
- data/lib/pikuri/agent/listener_list.rb +19 -13
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +624 -448
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/extractor/passthrough.rb +5 -2
- data/lib/pikuri/extractor.rb +43 -12
- data/lib/pikuri/file_type.rb +4 -4
- data/lib/pikuri/finalizers.rb +2 -2
- data/lib/pikuri/paths.rb +1 -1
- data/lib/pikuri/sanitizer.rb +4 -3
- data/lib/pikuri/subprocess.rb +17 -5
- data/lib/pikuri/testing.rb +122 -49
- data/lib/pikuri/tool/calculator.rb +134 -30
- data/lib/pikuri/tool/execute_context.rb +2 -2
- data/lib/pikuri/tool/parameters.rb +10 -0
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +52 -21
- data/lib/pikuri/tool.rb +298 -24
- data/lib/pikuri/trifecta/report.rb +28 -30
- data/lib/pikuri/trifecta.rb +1 -2
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +5 -11
- metadata +16 -73
- data/lib/pikuri/agent/context_window_detector.rb +0 -181
- data/lib/pikuri/agent/control/step_limit.rb +0 -95
- data/lib/pikuri/agent/extension_context.rb +0 -120
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
- data/lib/pikuri/agent/synthesizer.rb +0 -129
- data/lib/pikuri/extractor/html.rb +0 -256
- data/lib/pikuri/ruby_llm_patches.rb +0 -106
- data/lib/pikuri/tool/fetch.rb +0 -146
- data/lib/pikuri/tool/scraper.rb +0 -144
- data/lib/pikuri/tool/search/brave.rb +0 -170
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
- data/lib/pikuri/tool/search/engines.rb +0 -319
- data/lib/pikuri/tool/search/exa.rb +0 -195
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
- data/lib/pikuri/tool/search/result.rb +0 -24
- data/lib/pikuri/tool/web_scrape.rb +0 -105
- data/lib/pikuri/tool/web_search.rb +0 -133
- data/lib/pikuri/url_cache.rb +0 -96
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
|
-
# {
|
|
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::
|
|
22
|
-
#
|
|
23
|
-
#
|
|
24
|
-
#
|
|
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.
|
|
28
|
-
# plus
|
|
26
|
+
# "What fires when" is one grep for +@listeners.on_event+ (loop narration)
|
|
27
|
+
# plus {Configurator#emit_event} (domain events).
|
|
29
28
|
#
|
|
30
|
-
# ==
|
|
29
|
+
# == One agent, one conversation
|
|
31
30
|
#
|
|
32
|
-
#
|
|
33
|
-
#
|
|
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
|
-
#
|
|
36
|
-
#
|
|
37
|
-
#
|
|
38
|
-
#
|
|
39
|
-
#
|
|
40
|
-
#
|
|
41
|
-
#
|
|
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
|
|
47
|
-
#
|
|
48
|
-
#
|
|
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
|
-
#
|
|
87
|
-
#
|
|
88
|
-
#
|
|
89
|
-
#
|
|
90
|
-
#
|
|
91
|
-
#
|
|
92
|
-
#
|
|
93
|
-
#
|
|
94
|
-
#
|
|
95
|
-
#
|
|
96
|
-
#
|
|
97
|
-
#
|
|
98
|
-
#
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
# A
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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}
|
|
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
|
|
162
|
-
#
|
|
163
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
191
|
-
|
|
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
|
-
#
|
|
217
|
-
#
|
|
218
|
-
# agent
|
|
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}
|
|
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 [
|
|
254
|
-
#
|
|
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
|
|
268
|
-
# +configure+ ran during the +Agent.new+ block
|
|
269
|
-
#
|
|
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
|
-
#
|
|
273
|
-
#
|
|
274
|
-
#
|
|
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
|
|
293
|
-
# {Event::UserTurn} (+mid_loop: false+) and appends it; with
|
|
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
|
|
297
|
-
#
|
|
298
|
-
# +complete+s the chat. Output is
|
|
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
|
-
#
|
|
302
|
-
#
|
|
303
|
-
#
|
|
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
|
-
#
|
|
308
|
-
# "
|
|
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:+
|
|
313
|
-
# (via {#apply_transport!})
|
|
314
|
-
#
|
|
315
|
-
#
|
|
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},
|
|
326
|
-
#
|
|
327
|
-
#
|
|
328
|
-
#
|
|
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
|
|
334
|
-
# 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
|
|
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
|
|
342
|
-
# bare turn (see above)
|
|
343
|
-
# @param
|
|
344
|
-
#
|
|
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 [
|
|
348
|
-
#
|
|
349
|
-
#
|
|
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
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
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
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
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.
|
|
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!(
|
|
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
|
-
#
|
|
444
|
-
#
|
|
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
|
|
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 —
|
|
450
|
-
# resumed conversation gets today's, not the one that was current when
|
|
451
|
-
# was
|
|
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
|
|
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(
|
|
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}
|
|
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.
|
|
590
|
-
# +Agent.new+ block
|
|
591
|
-
#
|
|
592
|
-
#
|
|
593
|
-
# +@on_close_handlers+ itself, so a
|
|
594
|
-
# live the instant it's registered —
|
|
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
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
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)
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
566
|
+
drain_interloper if tool_batch_complete?(msg)
|
|
643
567
|
end
|
|
644
568
|
@chat.before_tool_call do |tc|
|
|
645
|
-
|
|
646
|
-
|
|
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
|
-
@
|
|
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
|
-
|
|
654
|
-
|
|
655
|
-
|
|
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
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
@
|
|
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).
|
|
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
|
-
#
|
|
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 `
|
|
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
|
-
#
|
|
696
|
-
#
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
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
|
-
# @
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
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
|
-
#
|
|
715
|
-
#
|
|
716
|
-
#
|
|
717
|
-
#
|
|
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
|
-
#
|
|
720
|
-
#
|
|
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
|
-
# {#
|
|
768
|
+
# {#restore_history}'s repair only covers a conversation that arrives stale.
|
|
725
769
|
#
|
|
726
|
-
#
|
|
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.
|
|
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
|
|
752
|
-
#
|
|
753
|
-
# +
|
|
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
|
-
|
|
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
|
|
769
|
-
#
|
|
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(
|
|
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
|
|
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 +
|
|
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.
|
|
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 +
|
|
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
|
-
# {#
|
|
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.
|
|
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,
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
976
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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.
|
|
1216
|
+
@listeners.on_event(Event::Thinking.new(content: text)) if text && !text.empty?
|
|
1059
1217
|
|
|
1060
1218
|
content = msg.content
|
|
1061
|
-
@listeners.
|
|
1062
|
-
|
|
1063
|
-
@listeners.
|
|
1064
|
-
input: msg.
|
|
1065
|
-
output: msg.
|
|
1066
|
-
cached: msg.
|
|
1067
|
-
cache_creation: msg.
|
|
1068
|
-
thinking: msg.
|
|
1069
|
-
model_id: msg.
|
|
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
|
|
1074
|
-
#
|
|
1075
|
-
#
|
|
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.
|
|
1082
|
-
|
|
1239
|
+
@listeners.on_event(Event::ThinkingDelta.new(content: thinking)) if thinking && !thinking.empty?
|
|
1083
1240
|
content = chunk.content
|
|
1084
|
-
@listeners.
|
|
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
|
-
|
|
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
|