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
|
@@ -2,158 +2,93 @@
|
|
|
2
2
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Agent
|
|
5
|
-
#
|
|
6
|
-
#
|
|
7
|
-
# additional tools, listeners, system-prompt snippets, +on_close+
|
|
8
|
-
# handlers, extension instances, and persona-flavored sub-agents;
|
|
9
|
-
# {Agent#initialize} drains the collected state into the agent's
|
|
10
|
-
# final wiring before returning.
|
|
11
|
-
#
|
|
12
|
-
# == Why this exists
|
|
13
|
-
#
|
|
14
|
-
# Splits "configure the agent" from "the agent's runtime state".
|
|
15
|
-
# Hosts can write a block that reads cleanly:
|
|
5
|
+
# The one handle for wiring an {Agent}, yielded into the +Pikuri::Agent.new+
|
|
6
|
+
# block and handed to every {Extension#configure}:
|
|
16
7
|
#
|
|
17
8
|
# Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
|
|
18
9
|
# c.add_listener Pikuri::Agent::Listener::Terminal.new
|
|
19
|
-
# c.add_tool Pikuri::Tool::
|
|
20
|
-
# c.
|
|
21
|
-
# c.add_tool Pikuri::Tool::FETCH
|
|
22
|
-
# c.add_extension Pikuri::Skill::Extension.new(catalog: catalog)
|
|
10
|
+
# c.add_tool Pikuri::Tool::CALCULATOR
|
|
11
|
+
# c.add_extension Pikuri::Workspace::Extension.new(filesystem: fs, confirmer: confirmer)
|
|
23
12
|
# end
|
|
24
13
|
#
|
|
25
|
-
#
|
|
14
|
+
# Two kinds of call. *Declarations* — {#add_tool}, {#add_listener},
|
|
15
|
+
# {#add_extension}, {#on_close} — shape the agent being built. *Capabilities*
|
|
16
|
+
# — {#emit_event}, {#add_raw_tool}, {#sub_agent_listeners},
|
|
17
|
+
# {#replace_compacted_history} — act on the live
|
|
18
|
+
# agent, so an extension keeps the Configurator and uses them later, from a
|
|
19
|
+
# callback or a tool's +execute+:
|
|
20
|
+
#
|
|
21
|
+
# def configure(c)
|
|
22
|
+
# @list.on_change = -> { c.emit_event(ListChanged.new(items: @list.items)) }
|
|
23
|
+
# end
|
|
24
|
+
#
|
|
25
|
+
# == Why a handed object, not methods on Agent
|
|
26
|
+
#
|
|
27
|
+
# {Agent} has no public path to these capabilities (no +listeners+ or
|
|
28
|
+
# +chat+ reader, no emit method): holding an agent grants read access to
|
|
29
|
+
# its config and nothing more. The way to them is to be handed the
|
|
30
|
+
# Configurator — by +Agent.new+, or onward by whoever was
|
|
31
|
+
# ({Pikuri::SubAgent::SubAgentTool} keeps its extension's). The boundary is
|
|
32
|
+
# the API contract, not a mechanical seal.
|
|
26
33
|
#
|
|
27
|
-
#
|
|
28
|
-
# in {#tools} and gets handed to ruby_llm via +chat.with_tool+.
|
|
29
|
-
# {#add_sub_agent_tool} registers a tool the parent *cannot* call
|
|
30
|
-
# — it lands in {#sub_agent_tools} and is never sent to ruby_llm
|
|
31
|
-
# for the parent, but is visible to {Pikuri::SubAgent::Extension}'s
|
|
32
|
-
# persona-tool-name resolution. The use case is the lethal-trifecta
|
|
33
|
-
# defense in {Pikuri::Code::Bash::Sandbox} terms: keep network tools
|
|
34
|
-
# (+web_search+ / +web_scrape+ / +fetch+) off the parent so a prompt-
|
|
35
|
-
# injected file read cannot egress through the parent's own tools,
|
|
36
|
-
# while still letting the +researcher+ persona reach them via the
|
|
37
|
-
# +agent+ delegation tool. See SECURITY.md §"Defense: capability
|
|
38
|
-
# boundaries via sub-agents".
|
|
34
|
+
# == Two tool pools: regular vs. sub-agent-only
|
|
39
35
|
#
|
|
40
|
-
#
|
|
41
|
-
#
|
|
42
|
-
#
|
|
36
|
+
# {#add_tool} registers a tool the parent agent can call. {#add_sub_agent_tool}
|
|
37
|
+
# registers one the parent *cannot* call, which only a sub-agent whose
|
|
38
|
+
# persona names it receives. The use case is the lethal-trifecta defense:
|
|
39
|
+
# keep network tools (+web_search+ / +web_scrape+ / +fetch+) off the parent
|
|
40
|
+
# so a prompt-injected file read can't egress through it, while the
|
|
41
|
+
# +researcher+ persona still reaches them via the +agent+ tool. See
|
|
42
|
+
# SECURITY.md.
|
|
43
43
|
#
|
|
44
|
-
# ==
|
|
44
|
+
# == Implementation details
|
|
45
45
|
#
|
|
46
|
-
#
|
|
47
|
-
#
|
|
48
|
-
#
|
|
49
|
-
#
|
|
50
|
-
# — it carries no runtime state.
|
|
46
|
+
# {#add_raw_tool} reaches the chat at once, so a raw tool added inside the
|
|
47
|
+
# block precedes the regular tools, which the Agent registers when the block
|
|
48
|
+
# returns. An event emitted inside the block reaches only the listeners
|
|
49
|
+
# added so far.
|
|
51
50
|
class Configurator
|
|
52
|
-
# @return [Agent
|
|
53
|
-
#
|
|
54
|
-
#
|
|
55
|
-
#
|
|
56
|
-
attr_reader :
|
|
57
|
-
|
|
58
|
-
# @return [
|
|
59
|
-
#
|
|
60
|
-
#
|
|
61
|
-
#
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
# @return [String] this agent's unique identifier; empty for the
|
|
66
|
-
# main agent, persona-rooted (e.g. +"researcher 0"+) for sub-agents.
|
|
67
|
-
attr_reader :id
|
|
68
|
-
|
|
69
|
-
# @return [Boolean] +true+ when the agent opted into chunk-level
|
|
70
|
-
# streaming.
|
|
71
|
-
attr_reader :streaming
|
|
72
|
-
|
|
73
|
-
# @return [Control::StepLimit, nil] step-budget control passed
|
|
74
|
-
# to the Agent ctor, or +nil+.
|
|
75
|
-
attr_reader :step_limit
|
|
76
|
-
|
|
77
|
-
# @return [Control::Cancellable, nil] cancellation control
|
|
78
|
-
# passed to the Agent ctor, or +nil+. Extensions that run
|
|
79
|
-
# sub-LLM calls during +configure+ (e.g. an MCP description
|
|
80
|
-
# synthesizer) share this so a user cancel during boot
|
|
81
|
-
# propagates correctly.
|
|
82
|
-
attr_reader :cancellable
|
|
83
|
-
|
|
84
|
-
# @return [Control::Interloper, nil] mid-loop user-input queue
|
|
85
|
-
# passed to the Agent ctor, or +nil+.
|
|
86
|
-
attr_reader :interloper
|
|
87
|
-
|
|
88
|
-
# @return [Array<Tool>] tools added via {#add_tool}, in
|
|
89
|
-
# declaration order. Drained by {Agent#initialize} and
|
|
90
|
-
# registered with ruby_llm so the parent LLM can call them.
|
|
51
|
+
# @return [Agent] the agent being built. Its constructor arguments
|
|
52
|
+
# (+transport+, +id+, +cancellable+, +interloper+, ...) are readable at
|
|
53
|
+
# once; what the block declares (+tools+, +system_prompt+) only once
|
|
54
|
+
# +Agent.new+ returns.
|
|
55
|
+
attr_reader :agent
|
|
56
|
+
|
|
57
|
+
# @return [History, nil] the conversation +Agent.new(history:)+ resumes,
|
|
58
|
+
# as passed in, or +nil+ for a fresh one — so an extension can rebuild
|
|
59
|
+
# what the transcript implies (MCP re-registers the tools of servers it
|
|
60
|
+
# had connected).
|
|
61
|
+
attr_reader :history
|
|
62
|
+
|
|
63
|
+
# @return [Array<Tool>] tools added via {#add_tool}, in declaration order.
|
|
91
64
|
attr_reader :tools
|
|
92
65
|
|
|
93
|
-
# @return [Array<Tool>] tools added via {#add_sub_agent_tool},
|
|
94
|
-
#
|
|
95
|
-
# *not* registered with ruby_llm — invisible to the parent
|
|
96
|
-
# LLM, available only to sub-agents through
|
|
97
|
-
# {Pikuri::SubAgent::Extension}'s persona-tool-name
|
|
98
|
-
# resolution. See the class header.
|
|
66
|
+
# @return [Array<Tool>] tools added via {#add_sub_agent_tool}, in
|
|
67
|
+
# declaration order.
|
|
99
68
|
attr_reader :sub_agent_tools
|
|
100
69
|
|
|
101
|
-
# @return [Array<
|
|
102
|
-
#
|
|
103
|
-
# {Agent#initialize}.
|
|
104
|
-
attr_reader :listeners
|
|
105
|
-
|
|
106
|
-
# @return [Array<String>] system-prompt snippets added via
|
|
107
|
-
# {#append_system_prompt}, in declaration order. Joined with
|
|
108
|
-
# double-newline separators between the base prompt and each
|
|
109
|
-
# snippet by {Agent#initialize}.
|
|
110
|
-
attr_reader :system_prompt_additions
|
|
111
|
-
|
|
112
|
-
# @return [Array<Proc>] +on_close+ handlers added via
|
|
113
|
-
# {#on_close}, in declaration order. Fired by {Agent#close}
|
|
114
|
-
# in LIFO order with per-handler rescue.
|
|
115
|
-
attr_reader :on_close_handlers
|
|
116
|
-
|
|
117
|
-
# @return [Array<#configure>] extension instances added via
|
|
118
|
-
# {#add_extension}, in declaration order. The Agent ctor
|
|
119
|
-
# walks this list after wiring is complete and calls +bind+
|
|
120
|
-
# on each with the agent's {ExtensionContext}.
|
|
70
|
+
# @return [Array<Extension>] extensions added via {#add_extension}, in
|
|
71
|
+
# declaration order.
|
|
121
72
|
attr_reader :extensions
|
|
122
73
|
|
|
123
|
-
# @param
|
|
124
|
-
# @param
|
|
125
|
-
# @param
|
|
126
|
-
# @param
|
|
127
|
-
# @param
|
|
128
|
-
#
|
|
129
|
-
#
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
# array for standalone use (e.g. specs).
|
|
137
|
-
def initialize(transport:, system_prompt_base:, id:, streaming:,
|
|
138
|
-
step_limit:, cancellable:, interloper:, on_close_sink: nil)
|
|
139
|
-
@transport = transport
|
|
140
|
-
@system_prompt_base = system_prompt_base
|
|
141
|
-
@id = id
|
|
142
|
-
@streaming = streaming
|
|
143
|
-
@step_limit = step_limit
|
|
144
|
-
@cancellable = cancellable
|
|
145
|
-
@interloper = interloper
|
|
146
|
-
|
|
74
|
+
# @param agent [Agent] the agent under construction
|
|
75
|
+
# @param chat [RubyLLM::Chat] its chat, the target of {#add_raw_tool}
|
|
76
|
+
# @param listeners [ListenerList] its listener list
|
|
77
|
+
# @param history [History, nil]
|
|
78
|
+
# @param on_close_sink [Array<Proc>] the agent's live +on_close+ list, so
|
|
79
|
+
# a handler armed mid-block is there when a later +configure+ raises
|
|
80
|
+
# and the constructor closes the half-built agent.
|
|
81
|
+
def initialize(agent:, chat:, listeners:, history:, on_close_sink:)
|
|
82
|
+
@agent = agent
|
|
83
|
+
@chat = chat
|
|
84
|
+
@listeners = listeners
|
|
85
|
+
@history = history
|
|
86
|
+
@on_close_handlers = on_close_sink
|
|
147
87
|
@tools = []
|
|
148
88
|
@sub_agent_tools = []
|
|
149
|
-
@listeners = []
|
|
150
|
-
@system_prompt_additions = []
|
|
151
|
-
@on_close_handlers = on_close_sink || []
|
|
152
89
|
@extensions = []
|
|
153
90
|
end
|
|
154
91
|
|
|
155
|
-
# Append a tool to the agent's static tool list.
|
|
156
|
-
#
|
|
157
92
|
# @param tool [Tool]
|
|
158
93
|
# @return [void]
|
|
159
94
|
def add_tool(tool)
|
|
@@ -161,20 +96,14 @@ module Pikuri
|
|
|
161
96
|
nil
|
|
162
97
|
end
|
|
163
98
|
|
|
164
|
-
# Append several tools at once. Equivalent to calling {#add_tool}
|
|
165
|
-
# for each element of +tools+; declaration order is preserved.
|
|
166
|
-
#
|
|
167
99
|
# @param tools [Enumerable<Tool>]
|
|
168
100
|
# @return [void]
|
|
169
101
|
def add_tools(tools)
|
|
170
|
-
tools.each { |t|
|
|
102
|
+
tools.each { |t| add_tool(t) }
|
|
171
103
|
nil
|
|
172
104
|
end
|
|
173
105
|
|
|
174
|
-
#
|
|
175
|
-
# never sees it; only sub-agents whose persona +tool_names+
|
|
176
|
-
# include the tool's +name+ get it in their toolset. See the
|
|
177
|
-
# class header for the trifecta-defense rationale.
|
|
106
|
+
# Add a tool only sub-agents can receive; see +== Two tool pools+.
|
|
178
107
|
#
|
|
179
108
|
# @param tool [Tool]
|
|
180
109
|
# @return [void]
|
|
@@ -183,61 +112,42 @@ module Pikuri
|
|
|
183
112
|
nil
|
|
184
113
|
end
|
|
185
114
|
|
|
186
|
-
# Append a listener to the agent's listener list.
|
|
187
|
-
#
|
|
188
115
|
# @param listener [Listener::Base]
|
|
189
116
|
# @return [void]
|
|
190
117
|
def add_listener(listener)
|
|
191
|
-
@listeners
|
|
118
|
+
@listeners.add(listener)
|
|
192
119
|
nil
|
|
193
120
|
end
|
|
194
121
|
|
|
195
|
-
# Append several listeners at once. Accepts any enumerable
|
|
196
|
-
# (Array, {ListenerList}, …); declaration order is preserved.
|
|
197
|
-
#
|
|
198
122
|
# @param listeners [Enumerable<Listener::Base>]
|
|
199
123
|
# @return [void]
|
|
200
124
|
def add_listeners(listeners)
|
|
201
|
-
listeners.each { |l|
|
|
202
|
-
nil
|
|
203
|
-
end
|
|
204
|
-
|
|
205
|
-
# Append a snippet to the system prompt. Snippets are joined
|
|
206
|
-
# to the base prompt with double-newline separators.
|
|
207
|
-
#
|
|
208
|
-
# Used by extensions to register +<available_skills>+,
|
|
209
|
-
# +<available_mcps>+, and similar advertisement blocks. Block
|
|
210
|
-
# users typically pass the full system prompt via the ctor's
|
|
211
|
-
# +system_prompt:+ kwarg instead.
|
|
212
|
-
#
|
|
213
|
-
# @param snippet [String]
|
|
214
|
-
# @return [void]
|
|
215
|
-
def append_system_prompt(snippet)
|
|
216
|
-
@system_prompt_additions << snippet
|
|
125
|
+
listeners.each { |l| add_listener(l) }
|
|
217
126
|
nil
|
|
218
127
|
end
|
|
219
128
|
|
|
220
|
-
# Register an extension
|
|
221
|
-
#
|
|
222
|
-
#
|
|
223
|
-
# that runs at the end of {Agent#initialize}.
|
|
129
|
+
# Register an extension and run its +configure(self)+ at once, so source
|
|
130
|
+
# order is execution order: a later extension sees what earlier ones
|
|
131
|
+
# added. +include Pikuri::Agent::Extension+ for no-op defaults.
|
|
224
132
|
#
|
|
225
|
-
#
|
|
226
|
-
#
|
|
227
|
-
#
|
|
228
|
-
#
|
|
133
|
+
# An instance serves one agent ({Extension}), so one already added to
|
|
134
|
+
# any agent — this one included, and even after that agent closed — is
|
|
135
|
+
# refused before its +configure+ runs. Reuse is a host bug that fails
|
|
136
|
+
# quietly otherwise: the second agent would share the first one's
|
|
137
|
+
# per-conversation state and the servers it started.
|
|
229
138
|
#
|
|
230
|
-
# @param extension [Extension, #configure
|
|
139
|
+
# @param extension [Extension, #configure] extension instance
|
|
231
140
|
# @return [void]
|
|
141
|
+
# @raise [ArgumentError] when +extension+ was already added to an agent
|
|
232
142
|
def add_extension(extension)
|
|
143
|
+
claim(extension)
|
|
233
144
|
@extensions << extension
|
|
234
145
|
extension.configure(self)
|
|
235
146
|
nil
|
|
236
147
|
end
|
|
237
148
|
|
|
238
|
-
# Register a handler called by {Agent#close}
|
|
239
|
-
#
|
|
240
|
-
# +ensure+-block cleanup discipline.
|
|
149
|
+
# Register a handler called by {Agent#close} (LIFO, each inside its own
|
|
150
|
+
# +rescue+).
|
|
241
151
|
#
|
|
242
152
|
# @yield called with no arguments at close time
|
|
243
153
|
# @return [void]
|
|
@@ -247,6 +157,117 @@ module Pikuri
|
|
|
247
157
|
@on_close_handlers << blk
|
|
248
158
|
nil
|
|
249
159
|
end
|
|
160
|
+
|
|
161
|
+
# Emit a domain event onto the agent's listener stream. Core {Event}
|
|
162
|
+
# variants narrate the loop; gems define their own (e.g. a task list's
|
|
163
|
+
# +ListChanged+) and emit them here. Listeners no-op on
|
|
164
|
+
# variants they don't recognize ({Listener::Base#on_event}'s default).
|
|
165
|
+
#
|
|
166
|
+
# Call it on the agent's thread — typically inside a tool's +execute+,
|
|
167
|
+
# landing between {Event::ToolCall} and {Event::ToolResult}.
|
|
168
|
+
#
|
|
169
|
+
# @param event [Object] an immutable event value (by convention a +Data+)
|
|
170
|
+
# @return [void]
|
|
171
|
+
def emit_event(event)
|
|
172
|
+
@listeners.on_event(event)
|
|
173
|
+
nil
|
|
174
|
+
end
|
|
175
|
+
|
|
176
|
+
# Register a raw +RubyLLM::Tool+ subclass on the agent's chat, bypassing
|
|
177
|
+
# {Pikuri::Tool}'s strict validation — MCP's tools, whose schema is the
|
|
178
|
+
# server's. Usable mid-conversation (+mcp_connect+ adds a server's tools
|
|
179
|
+
# when the model asks).
|
|
180
|
+
#
|
|
181
|
+
# The tool does NOT enter {Agent#tools}, so sub-agents can't snapshot it:
|
|
182
|
+
# activation is strictly per-agent.
|
|
183
|
+
#
|
|
184
|
+
# @param ruby_llm_tool [Class] subclass of +RubyLLM::Tool+
|
|
185
|
+
# @return [void]
|
|
186
|
+
def add_raw_tool(ruby_llm_tool)
|
|
187
|
+
@chat.with_tools(ruby_llm_tool)
|
|
188
|
+
nil
|
|
189
|
+
end
|
|
190
|
+
|
|
191
|
+
# Replace the conversation with a shorter rendering of *itself* — the
|
|
192
|
+
# actuator a compaction extension drives, deciding when and how to
|
|
193
|
+
# shorten on its own:
|
|
194
|
+
#
|
|
195
|
+
# def configure(c)
|
|
196
|
+
# @c = c
|
|
197
|
+
# end
|
|
198
|
+
#
|
|
199
|
+
# def on_user_message(_content, _attachments)
|
|
200
|
+
# @c.replace_compacted_history(compact(@c.agent.export_history)) if over_budget?
|
|
201
|
+
# nil
|
|
202
|
+
# end
|
|
203
|
+
#
|
|
204
|
+
# Only the messages change. Tools, MCP connections and the servers
|
|
205
|
+
# behind them, every extension's state (a workspace's read-marks,
|
|
206
|
+
# promoted skills), listeners, the system prompt and the transport all
|
|
207
|
+
# stand, because a compacted conversation is still the same
|
|
208
|
+
# conversation. The incoming messages get {Agent}'s resume repairs.
|
|
209
|
+
#
|
|
210
|
+
# So +history+ must be *this* conversation, shortened: handed a
|
|
211
|
+
# different one, that conversation inherits everything this one built
|
|
212
|
+
# up, the logged-in browser behind an MCP server included. Nothing
|
|
213
|
+
# checks this beyond the shape below; the name is the guard. See
|
|
214
|
+
# +design/decisions.md+ +D_compaction_in_place+.
|
|
215
|
+
#
|
|
216
|
+
# Shape it must keep, enforced:
|
|
217
|
+
#
|
|
218
|
+
# - end with the conversation's current last message, same {History::Message#id};
|
|
219
|
+
# rewriting its content is fine;
|
|
220
|
+
# - keep each tool result right after the assistant turn that made its call.
|
|
221
|
+
#
|
|
222
|
+
# Keep the ids of every other message you carry over too, so state an
|
|
223
|
+
# extension keys on one still finds it. Callable on the agent's thread
|
|
224
|
+
# anywhere outside an open tool batch: between turns, or from
|
|
225
|
+
# {Extension#on_user_message}.
|
|
226
|
+
#
|
|
227
|
+
# @param history [History] typically {Agent#export_history}, shortened
|
|
228
|
+
# @return [void]
|
|
229
|
+
# @raise [ArgumentError] if +history+ breaks the shape above
|
|
230
|
+
# @raise [RuntimeError] inside the +Agent.new+ block, or while a tool
|
|
231
|
+
# batch is open (from a tool's +execute+)
|
|
232
|
+
def replace_compacted_history(history)
|
|
233
|
+
# Private on Agent, so holding an agent doesn't grant it.
|
|
234
|
+
@agent.send(:replace_compacted_history, history)
|
|
235
|
+
nil
|
|
236
|
+
end
|
|
237
|
+
|
|
238
|
+
# A listener list for a spawned sub-agent, via {ListenerList#for_sub_agent}.
|
|
239
|
+
#
|
|
240
|
+
# @param params [Hash{Symbol => Object}] forwarded to each listener's
|
|
241
|
+
# +for_sub_agent+ hook (currently +id:+)
|
|
242
|
+
# @return [ListenerList]
|
|
243
|
+
def sub_agent_listeners(**params)
|
|
244
|
+
@listeners.for_sub_agent(**params)
|
|
245
|
+
end
|
|
246
|
+
|
|
247
|
+
# Every extension ever added, process-wide. Keyed by identity (a
|
|
248
|
+
# +WeakMap+, not a +WeakKeyMap+, so two equal value objects stay two
|
|
249
|
+
# extensions) and weak, so a claim never keeps an extension alive.
|
|
250
|
+
CLAIMED = ObjectSpace::WeakMap.new
|
|
251
|
+
# Agents may be built on several threads; the check and the mark are
|
|
252
|
+
# one step.
|
|
253
|
+
CLAIM_LOCK = Mutex.new
|
|
254
|
+
private_constant :CLAIMED, :CLAIM_LOCK
|
|
255
|
+
|
|
256
|
+
private
|
|
257
|
+
|
|
258
|
+
# @param extension [Object]
|
|
259
|
+
# @return [void]
|
|
260
|
+
# @raise [ArgumentError] when +extension+ is already claimed
|
|
261
|
+
def claim(extension)
|
|
262
|
+
CLAIM_LOCK.synchronize do
|
|
263
|
+
if CLAIMED.key?(extension)
|
|
264
|
+
raise ArgumentError, "#{extension.class} instance is already added to an agent; " \
|
|
265
|
+
'build a fresh one for every Agent.new'
|
|
266
|
+
end
|
|
267
|
+
|
|
268
|
+
CLAIMED[extension] = true
|
|
269
|
+
end
|
|
270
|
+
end
|
|
250
271
|
end
|
|
251
272
|
end
|
|
252
273
|
end
|