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