pikuri-core 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +16 -29
- data/lib/pikuri/agent/chat_transport.rb +114 -33
- data/lib/pikuri/agent/configurator.rb +191 -110
- data/lib/pikuri/agent/control/cancellable.rb +25 -16
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +87 -120
- data/lib/pikuri/agent/control.rb +9 -11
- data/lib/pikuri/agent/event.rb +73 -61
- data/lib/pikuri/agent/extension.rb +45 -81
- data/lib/pikuri/agent/history.rb +91 -497
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +115 -108
- data/lib/pikuri/agent/listener/token_log.rb +21 -55
- data/lib/pikuri/agent/listener.rb +4 -4
- data/lib/pikuri/agent/listener_list.rb +19 -13
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +624 -448
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/extractor/passthrough.rb +5 -2
- data/lib/pikuri/extractor.rb +43 -12
- data/lib/pikuri/file_type.rb +4 -4
- data/lib/pikuri/finalizers.rb +2 -2
- data/lib/pikuri/paths.rb +1 -1
- data/lib/pikuri/sanitizer.rb +4 -3
- data/lib/pikuri/subprocess.rb +17 -5
- data/lib/pikuri/testing.rb +122 -49
- data/lib/pikuri/tool/calculator.rb +134 -30
- data/lib/pikuri/tool/execute_context.rb +2 -2
- data/lib/pikuri/tool/parameters.rb +10 -0
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +52 -21
- data/lib/pikuri/tool.rb +298 -24
- data/lib/pikuri/trifecta/report.rb +28 -30
- data/lib/pikuri/trifecta.rb +1 -2
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +5 -11
- metadata +16 -73
- data/lib/pikuri/agent/context_window_detector.rb +0 -181
- data/lib/pikuri/agent/control/step_limit.rb +0 -95
- data/lib/pikuri/agent/extension_context.rb +0 -120
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
- data/lib/pikuri/agent/synthesizer.rb +0 -129
- data/lib/pikuri/extractor/html.rb +0 -256
- data/lib/pikuri/ruby_llm_patches.rb +0 -106
- data/lib/pikuri/tool/fetch.rb +0 -146
- data/lib/pikuri/tool/scraper.rb +0 -144
- data/lib/pikuri/tool/search/brave.rb +0 -170
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
- data/lib/pikuri/tool/search/engines.rb +0 -319
- data/lib/pikuri/tool/search/exa.rb +0 -195
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
- data/lib/pikuri/tool/search/result.rb +0 -24
- data/lib/pikuri/tool/web_scrape.rb +0 -105
- data/lib/pikuri/tool/web_search.rb +0 -133
- data/lib/pikuri/url_cache.rb +0 -96
|
@@ -3,79 +3,47 @@
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Agent
|
|
5
5
|
module Control
|
|
6
|
-
# Mid-loop host→agent injection queue.
|
|
7
|
-
#
|
|
8
|
-
# +interloper:+, and enqueues from any thread while the agent runs. The
|
|
9
|
-
# +Agent+ drains it once the running tool batch is answered — the only
|
|
10
|
-
# point in ruby_llm's loop where conversation state is consistent — and
|
|
11
|
-
# the next round-trip reacts to what was injected.
|
|
6
|
+
# Mid-loop host→agent injection queue. Every {Agent} builds its own, and
|
|
7
|
+
# a host (TUI, web client) enqueues from any thread while the agent runs:
|
|
12
8
|
#
|
|
13
|
-
#
|
|
9
|
+
# agent.interloper.inject_user_message('also check the tests') # a user turn
|
|
10
|
+
# agent.interloper.inject_system_message('<skill name="tdd">…</skill>') # reference text
|
|
14
11
|
#
|
|
15
|
-
#
|
|
16
|
-
# lands
|
|
12
|
+
# The agent drains it at turn start and once each tool batch is
|
|
13
|
+
# answered: an injection made while idle lands ahead of the next turn's
|
|
14
|
+
# message, one made mid-turn reaches the next round-trip.
|
|
15
|
+
# {Agent#drain_interloper} says how each {Item#kind} lands. A host
|
|
16
|
+
# showing what's queued — a "2 queued" badge, the pending messages
|
|
17
|
+
# themselves — sets {#on_change}, which hands it the items. Why a
|
|
18
|
+
# running turn takes a user message at all: +design/decisions.md+
|
|
19
|
+
# +D_mid_turn_user_message+.
|
|
17
20
|
#
|
|
18
|
-
# -
|
|
19
|
-
#
|
|
20
|
-
#
|
|
21
|
-
# turn).
|
|
22
|
-
# - +:system+ ({#inject_system_message}) — host-supplied reference text
|
|
23
|
-
# (a loaded skill, retrieved context): appended wrapped in
|
|
24
|
-
# +<system-reminder>+, emits +Event::SystemInjected+, and runs *no*
|
|
25
|
-
# +on_user_message+ dispatch and no +UserTurn+ (it's not a user turn).
|
|
21
|
+
# Sub-agents are private to the parent, so a child's queue stays empty —
|
|
22
|
+
# injection is directed at the main agent, where {Control::Cancellable}
|
|
23
|
+
# is shared by the whole tree.
|
|
26
24
|
#
|
|
27
|
-
#
|
|
28
|
-
# envelope, not in role. +:system+ names the *role the text plays*, and
|
|
29
|
-
# {Agent#append_reference_block} says why the wire role can't match it.
|
|
25
|
+
# == Implementation details
|
|
30
26
|
#
|
|
31
|
-
#
|
|
32
|
-
#
|
|
33
|
-
#
|
|
27
|
+
# Never drained *inside* a tool batch: an assistant message carrying
|
|
28
|
+
# tool_calls and the +:tool+ messages answering it are one unit on the
|
|
29
|
+
# wire, and a message appended between them is rejected or mangled (see
|
|
30
|
+
# {Agent#tool_batch_complete?}).
|
|
34
31
|
#
|
|
35
|
-
#
|
|
36
|
-
#
|
|
37
|
-
# Delivery is at the end of a tool batch, *not* the LLM HTTP call: an
|
|
38
|
-
# injection made mid-response takes effect on the *next* round-trip, once
|
|
39
|
-
# the model has committed to the current response's tool calls. Never
|
|
40
|
-
# *inside* a batch — an assistant message carrying tool_calls and the
|
|
41
|
-
# +:tool+ messages answering it are one unit on the wire, and a message
|
|
42
|
-
# appended between them is rejected or mangled (see
|
|
43
|
-
# {Agent#tool_batch_complete?}). Same
|
|
44
|
-
# "gentle" semantic {Control::Cancellable} promises — the cleanest
|
|
45
|
-
# cross-provider point (no in-flight subprocess, no half-built response).
|
|
46
|
-
# Controls are reset only at turn start, never on a mid-loop injection,
|
|
47
|
-
# so "cancel-then-inject" and "refresh-budget-by-injecting" can't arise.
|
|
48
|
-
#
|
|
49
|
-
# == Change notification
|
|
50
|
-
#
|
|
51
|
-
# A host rendering the pending count reactively (a "3 waiting" badge)
|
|
52
|
-
# sets {#on_change} instead of polling {#size}. It fires whenever the
|
|
53
|
-
# count changes — once per {#inject_user_message}, once per {#drain!}
|
|
54
|
-
# that empties a non-empty queue (an empty-queue drain, the hot path,
|
|
55
|
-
# stays silent) — with the new count, outside the lock. A host-side hook,
|
|
56
|
-
# not an {Agent} listener event: the count changes on the injecting
|
|
57
|
-
# thread, off the agent-thread-confined stream. Mirrors
|
|
58
|
-
# {Pikuri::Tasks::List#on_change} but pushes the count (the interloper
|
|
59
|
-
# exposes no race-free snapshot to re-read).
|
|
60
|
-
#
|
|
61
|
-
# == Sub-agent semantics
|
|
62
|
-
#
|
|
63
|
-
# Sub-agents are private to the parent; the host has no handle to them,
|
|
64
|
-
# so the +agent+ tool omits the kwarg, leaving a child's +interloper+
|
|
65
|
-
# +nil+. Contrast {Control::Cancellable}, shared by reference so the
|
|
66
|
-
# parent's stop propagates to the whole tree — cancellation is global,
|
|
67
|
-
# injection is directed at the main agent.
|
|
68
|
-
#
|
|
69
|
-
# Thread-safe: {#inject_user_message}, {#inject_system_message}, {#peek},
|
|
70
|
-
# {#pending?}, {#size}, and {#drain!} are a +Mutex+-guarded +Array+
|
|
71
|
-
# (chosen over +Thread::Queue+, which exposes no snapshot for {#peek}).
|
|
72
|
-
# {#on_change} fires outside the lock so a re-entrant or blocking callback
|
|
73
|
-
# can't deadlock.
|
|
32
|
+
# Thread-safe: a +Mutex+-guarded +Array+. {#on_change} fires outside the
|
|
33
|
+
# lock, so a callback may re-enter the interloper.
|
|
74
34
|
class Interloper
|
|
75
35
|
# A queued injection: +kind+ (+:user+ or +:system+) selects the drain
|
|
76
|
-
# path; +content+ is the message text
|
|
77
|
-
# +
|
|
78
|
-
|
|
36
|
+
# path; +content+ is the message text (+""+ for an attachment-only
|
|
37
|
+
# user message), +attachments+ the files shown with it, always empty
|
|
38
|
+
# for +:system+.
|
|
39
|
+
Item = Data.define(:kind, :content, :attachments) do
|
|
40
|
+
# @param kind [Symbol]
|
|
41
|
+
# @param content [String]
|
|
42
|
+
# @param attachments [Array<Pikuri::Attachment>]
|
|
43
|
+
def initialize(kind:, content:, attachments: [])
|
|
44
|
+
super(kind: kind, content: content, attachments: attachments.dup.freeze)
|
|
45
|
+
end
|
|
46
|
+
end
|
|
79
47
|
|
|
80
48
|
def initialize
|
|
81
49
|
@mutex = Mutex.new
|
|
@@ -83,67 +51,73 @@ module Pikuri
|
|
|
83
51
|
@on_change = nil
|
|
84
52
|
end
|
|
85
53
|
|
|
86
|
-
#
|
|
87
|
-
#
|
|
88
|
-
#
|
|
89
|
-
#
|
|
90
|
-
#
|
|
54
|
+
# Called with a frozen snapshot of the queue after each injection, and
|
|
55
|
+
# with +[]+ after a {#drain!} that empties a non-empty queue (an empty
|
|
56
|
+
# drain, the hot path, stays silent); +nil+ disables it:
|
|
57
|
+
#
|
|
58
|
+
# interloper.on_change = ->(items) { badge.text = "#{items.size} queued" }
|
|
91
59
|
#
|
|
92
|
-
#
|
|
60
|
+
# The snapshot is the queue as this change left it, taken under the
|
|
61
|
+
# same lock; {#size} read from the callback may already see a later
|
|
62
|
+
# change. Runs on the mutating thread; the frozen snapshot of frozen
|
|
63
|
+
# {Item}s may be handed to another thread as is.
|
|
64
|
+
#
|
|
65
|
+
# @return [Proc, nil] called with an +Array<Item>+ in delivery order
|
|
93
66
|
attr_accessor :on_change
|
|
94
67
|
|
|
95
|
-
# Enqueue a +:user+ mid-loop turn
|
|
96
|
-
#
|
|
68
|
+
# Enqueue a +:user+ mid-loop turn, the same message {Agent#run_loop}
|
|
69
|
+
# takes, e.g. an image dropped while the agent works:
|
|
70
|
+
#
|
|
71
|
+
# interloper.inject_user_message('and this one?', attachments: [png])
|
|
97
72
|
#
|
|
98
|
-
#
|
|
99
|
-
#
|
|
100
|
-
#
|
|
73
|
+
# Unlike {Agent#run_loop}, nothing here can refuse an attachment the
|
|
74
|
+
# model can't see: this runs on the host's thread with no agent, and
|
|
75
|
+
# raising at the drain would end the running turn over a picture. The
|
|
76
|
+
# drain withholds it instead, with a note in the text the model reads
|
|
77
|
+
# ({ChatTransport#modalities}). A host wanting an error up front checks
|
|
78
|
+
# +agent.transport.modalities+ before injecting.
|
|
79
|
+
#
|
|
80
|
+
# @param content [String, nil] the user's text; may be blank only when
|
|
81
|
+
# +attachments+ are given
|
|
82
|
+
# @param attachments [Array<Pikuri::Attachment>] files shown with it
|
|
83
|
+
# @raise [ArgumentError] if there is neither text nor an attachment — a
|
|
84
|
+
# blank injection would poison the chat history like a blank turn —
|
|
85
|
+
# or an attachment is not a {Pikuri::Attachment}
|
|
101
86
|
# @return [void]
|
|
102
|
-
def inject_user_message(content)
|
|
103
|
-
|
|
87
|
+
def inject_user_message(content = nil, attachments: [])
|
|
88
|
+
unless attachments.all?(Pikuri::Attachment)
|
|
89
|
+
raise ArgumentError, "attachments must be Pikuri::Attachments, got #{attachments.map(&:class)}"
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
content = '' if !attachments.empty? && content.to_s.strip.empty?
|
|
93
|
+
enqueue(:user, content, attachments: attachments)
|
|
104
94
|
end
|
|
105
95
|
|
|
106
|
-
# Enqueue a +:system+ reference block — host-loaded skill text or
|
|
107
|
-
#
|
|
108
|
-
# user turn (any thread; +Mutex+-guarded). Fires {#on_change}.
|
|
96
|
+
# Enqueue a +:system+ reference block — host-loaded skill text or other
|
|
97
|
+
# retrieved context, not a user turn.
|
|
109
98
|
#
|
|
110
|
-
# @param content [String] non-blank reference text
|
|
111
|
-
#
|
|
112
|
-
# envelope nests around it
|
|
99
|
+
# @param content [String] non-blank reference text; an own semantic tag
|
|
100
|
+
# is kept, the +<system-reminder>+ envelope nests around it
|
|
113
101
|
# @raise [ArgumentError] if +content+ is +nil+/blank
|
|
114
102
|
# @return [void]
|
|
115
103
|
def inject_system_message(content)
|
|
116
104
|
enqueue(:system, content)
|
|
117
105
|
end
|
|
118
106
|
|
|
119
|
-
#
|
|
120
|
-
# rendering a "pending" affordance. Safe from any thread.
|
|
121
|
-
#
|
|
122
|
-
# @return [Array<Item>] copy of the pending items; never shares state
|
|
123
|
-
# with the internal buffer
|
|
124
|
-
def peek
|
|
125
|
-
@mutex.synchronize { @items.dup }
|
|
126
|
-
end
|
|
127
|
-
|
|
128
|
-
# @return [Boolean] whether the queue holds a pending injection;
|
|
129
|
-
# observable from any thread
|
|
107
|
+
# @return [Boolean] whether the queue holds a pending injection
|
|
130
108
|
def pending?
|
|
131
109
|
@mutex.synchronize { !@items.empty? }
|
|
132
110
|
end
|
|
133
111
|
|
|
134
|
-
# @return [Integer] number of pending injections; a snapshot
|
|
135
|
-
#
|
|
112
|
+
# @return [Integer] number of pending injections; a snapshot that may
|
|
113
|
+
# have drained by the time the caller reads it
|
|
136
114
|
def size
|
|
137
115
|
@mutex.synchronize { @items.size }
|
|
138
116
|
end
|
|
139
117
|
|
|
140
|
-
# Atomically take and remove all pending items.
|
|
141
|
-
# +after_message+ wiring, once a tool batch is complete. Returns +[]+ when empty (the hot path) —
|
|
142
|
-
# an empty drain does *not* fire {#on_change}; a drain that empties a
|
|
143
|
-
# non-empty queue fires it with +0+, outside the lock.
|
|
118
|
+
# Atomically take and remove all pending items.
|
|
144
119
|
#
|
|
145
|
-
# @return [Array<Item>] items in delivery order;
|
|
146
|
-
# is empty
|
|
120
|
+
# @return [Array<Item>] items in delivery order; +[]+ when empty
|
|
147
121
|
def drain!
|
|
148
122
|
items = @mutex.synchronize do
|
|
149
123
|
next [] if @items.empty?
|
|
@@ -152,32 +126,25 @@ module Pikuri
|
|
|
152
126
|
@items.clear
|
|
153
127
|
taken
|
|
154
128
|
end
|
|
155
|
-
@on_change&.call(
|
|
129
|
+
@on_change&.call([].freeze) unless items.empty?
|
|
156
130
|
items
|
|
157
131
|
end
|
|
158
132
|
|
|
159
|
-
# @return [String] short label for {Agent#to_s}, reflecting the
|
|
160
|
-
# pending count.
|
|
161
|
-
def to_s
|
|
162
|
-
pending = size
|
|
163
|
-
pending.zero? ? 'Interloper' : "Interloper(#{pending} pending)"
|
|
164
|
-
end
|
|
165
|
-
|
|
166
133
|
private
|
|
167
134
|
|
|
168
|
-
# Shared enqueue for both +inject_*+ methods: validate, push a typed
|
|
169
|
-
# {Item}, fire {#on_change} outside the lock.
|
|
170
|
-
#
|
|
171
135
|
# @param kind [Symbol] +:user+ or +:system+
|
|
172
|
-
# @param content [String]
|
|
173
|
-
# @
|
|
136
|
+
# @param content [String, nil]
|
|
137
|
+
# @param attachments [Array<Pikuri::Attachment>] non-empty excuses a
|
|
138
|
+
# blank +content+
|
|
139
|
+
# @raise [ArgumentError] if +content+ is +nil+/blank with no attachments
|
|
174
140
|
# @return [void]
|
|
175
|
-
def enqueue(kind, content)
|
|
141
|
+
def enqueue(kind, content, attachments: [])
|
|
176
142
|
raise ArgumentError, "content must not be blank, got #{content.inspect}" \
|
|
177
|
-
if content.nil? || content.to_s.strip.empty?
|
|
143
|
+
if attachments.empty? && (content.nil? || content.to_s.strip.empty?)
|
|
178
144
|
|
|
179
|
-
|
|
180
|
-
@
|
|
145
|
+
item = Item.new(kind: kind, content: content, attachments: attachments)
|
|
146
|
+
snapshot = @mutex.synchronize { @items << item; @items.dup.freeze }
|
|
147
|
+
@on_change&.call(snapshot)
|
|
181
148
|
nil
|
|
182
149
|
end
|
|
183
150
|
end
|
data/lib/pikuri/agent/control.rb
CHANGED
|
@@ -2,22 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Agent
|
|
5
|
-
# Namespace for the +Agent+'s host-facing controls: {
|
|
6
|
-
# {
|
|
7
|
-
#
|
|
8
|
-
#
|
|
9
|
-
#
|
|
5
|
+
# Namespace for the +Agent+'s host-facing controls: {Cancellable} and
|
|
6
|
+
# {Interloper}. Each is a small value-holder the +Agent+ reads from (or
|
|
7
|
+
# pokes into the event stream from) at fixed points in ruby_llm's callback
|
|
8
|
+
# cycle. They are *not* listeners — they receive no events and never appear
|
|
9
|
+
# in a {ListenerList}.
|
|
10
10
|
#
|
|
11
11
|
# The split: listeners are pure consumers of the event stream; controls are
|
|
12
12
|
# host-facing signal holders the +Agent+ reads. The +Agent+ is the only
|
|
13
|
-
# entity that emits events,
|
|
14
|
-
#
|
|
15
|
-
#
|
|
13
|
+
# entity that emits events, checks the cancel flag, and drains the
|
|
14
|
+
# interloper queue — "what fires when" is one grep for +@listeners.on_event+ in
|
|
15
|
+
# +agent.rb+.
|
|
16
16
|
#
|
|
17
|
-
# * {StepLimit} — caps tool calls per {Agent#run_loop}; sub-agents get their
|
|
18
|
-
# own counter.
|
|
19
17
|
# * {Cancellable} — cooperative cancel flag, shared by reference across the
|
|
20
|
-
# parent
|
|
18
|
+
# parent and its sub-agents.
|
|
21
19
|
# * {Interloper} — mid-loop user-input queue; not propagated to sub-agents.
|
|
22
20
|
module Control
|
|
23
21
|
end
|
data/lib/pikuri/agent/event.rb
CHANGED
|
@@ -9,9 +9,12 @@ module Pikuri
|
|
|
9
9
|
# "Sealed" scopes the *loop-narration* vocabulary: the variants below
|
|
10
10
|
# are the complete set, all emitted by {Agent}, and new chat-loop
|
|
11
11
|
# observability belongs here. Gems define their own *domain* events in
|
|
12
|
-
# their own namespace (e.g. +
|
|
13
|
-
# them via {
|
|
14
|
-
# listeners must no-op on variants they don't recognize.
|
|
12
|
+
# their own namespace (e.g. a task list's +ListChanged+) and emit
|
|
13
|
+
# them via {Configurator#emit_event} onto the same stream;
|
|
14
|
+
# listeners must no-op on variants they don't recognize. A domain event's
|
|
15
|
+
# +#to_s+ is its whole rendering in a generic listener, which never reads
|
|
16
|
+
# its fields — that keeps core ignorant of a gem's payload. Why one open
|
|
17
|
+
# stream: +design/decisions.md+ +D_domain_events+.
|
|
15
18
|
module Event
|
|
16
19
|
# User input for a turn (+mid_loop: false+, the default) or a host
|
|
17
20
|
# injection delivered mid-loop (+mid_loop: true+, drained from
|
|
@@ -19,12 +22,20 @@ module Pikuri
|
|
|
19
22
|
# +UserTurn+ as a turn boundary tell a fresh turn from an in-loop
|
|
20
23
|
# injection. Emitted by {Agent#run_loop} at turn start, and when an
|
|
21
24
|
# interloper item drains in after a tool batch.
|
|
22
|
-
|
|
23
|
-
|
|
25
|
+
#
|
|
26
|
+
# Carries the attachments themselves, not a handle to look up: a
|
|
27
|
+
# listener has no {Agent::History} to resolve one against, and the bytes are
|
|
28
|
+
# shared with the chat, not copied.
|
|
29
|
+
UserTurn = Data.define(:content, :attachments, :mid_loop) do
|
|
30
|
+
# @param content [String] user-supplied text; +""+ on an
|
|
31
|
+
# attachment-only turn
|
|
32
|
+
# @param attachments [Array<Pikuri::Attachment>] what the model was
|
|
33
|
+
# shown; mid-loop, without any it can't take, whose notes are then in
|
|
34
|
+
# +content+
|
|
24
35
|
# @param mid_loop [Boolean] +true+ when drained from
|
|
25
36
|
# {Control::Interloper}; default +false+
|
|
26
|
-
def initialize(content:, mid_loop: false)
|
|
27
|
-
super
|
|
37
|
+
def initialize(content:, attachments: [], mid_loop: false)
|
|
38
|
+
super(content: content, attachments: attachments.dup.freeze, mid_loop: mid_loop)
|
|
28
39
|
end
|
|
29
40
|
end
|
|
30
41
|
|
|
@@ -66,15 +77,39 @@ module Pikuri
|
|
|
66
77
|
# {ThinkingDelta}; consume {Assistant} for the authoritative text.
|
|
67
78
|
AssistantDelta = Data.define(:content)
|
|
68
79
|
|
|
69
|
-
# A tool the LLM requested but hasn't observed yet. +
|
|
70
|
-
#
|
|
71
|
-
#
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
#
|
|
75
|
-
#
|
|
76
|
-
#
|
|
77
|
-
|
|
80
|
+
# A tool the LLM requested but hasn't observed yet. +display_name+ and
|
|
81
|
+
# +argument+ are what a chrome puts on the screen:
|
|
82
|
+
#
|
|
83
|
+
# → Write(lib/shared/config.rb)
|
|
84
|
+
#
|
|
85
|
+
# +arguments+ is the raw hash ruby_llm parsed from the model's
|
|
86
|
+
# +tool_calls+ JSON — unvalidated; the two display strings are the tool's
|
|
87
|
+
# own ({Tool#display_name} / {Tool#describe_call}), so every chrome prints
|
|
88
|
+
# the same line and only styles, caps and defangs it. An +argument+ of
|
|
89
|
+
# +""+ renders the call bare — +Name+, not +Name()+.
|
|
90
|
+
#
|
|
91
|
+
# Strings rather than a +tool:+ reference a renderer could query: the
|
|
92
|
+
# event must stay plain serializable +Data+, and three cases have no
|
|
93
|
+
# {Pikuri::Tool} to query at all — an MCP tool, ruby_llm's
|
|
94
|
+
# unavailable-tool error, a replayed conversation.
|
|
95
|
+
#
|
|
96
|
+
# Emitted by +before_tool_call+.
|
|
97
|
+
ToolCall = Data.define(:tool_call_id, :name, :arguments, :display_name, :argument)
|
|
98
|
+
|
|
99
|
+
# The observation a tool produced ({Tool#run}'s return), plus the
|
|
100
|
+
# one-line +summary+ a chrome shows in its place (+"Returned 23 search
|
|
101
|
+
# results"+). Recoverable failures arrive as +"Error: ..."+ strings, not
|
|
102
|
+
# exceptions, and their summary is that message. An image observation
|
|
103
|
+
# arrives as its text note (+"Read image: shot.png (2048 bytes, …)"+); the
|
|
104
|
+
# bytes go to the model only.
|
|
105
|
+
#
|
|
106
|
+
# +tool_call_id+ pairs this with its {ToolCall} by key, so a renderer
|
|
107
|
+
# needs no assumption about call→result ordering. Both carry the
|
|
108
|
+
# server's id, the one {History} stores.
|
|
109
|
+
#
|
|
110
|
+
# Emitted by +after_tool_result+, and by {Agent#run_loop}'s
|
|
111
|
+
# dangling-call repair (summary +"Interrupted"+).
|
|
112
|
+
ToolResult = Data.define(:tool_call_id, :name, :content, :summary)
|
|
78
113
|
|
|
79
114
|
# Provider-reported token usage for one assistant turn, off a
|
|
80
115
|
# +RubyLLM::Message+'s +tokens+ block. Emitted by +after_message+ on
|
|
@@ -98,58 +133,22 @@ module Pikuri
|
|
|
98
133
|
# - +model_id+ — provider-side model name on the response.
|
|
99
134
|
Tokens = Data.define(:input, :output, :cached, :cache_creation, :thinking, :model_id)
|
|
100
135
|
|
|
101
|
-
# Model's resolved context-window cap (+nil+ if unknown). Emitted at
|
|
102
|
-
# construction and after each model switch. A later ContextCap
|
|
103
|
-
# overwrites the prior; the running context size is not re-baselined.
|
|
104
|
-
ContextCap = Data.define(:cap)
|
|
105
|
-
|
|
106
136
|
# Agent switched model mid-conversation. Emitted by {Agent#run_loop}
|
|
107
|
-
#
|
|
108
|
-
#
|
|
109
|
-
#
|
|
110
|
-
# {ContextCap}, not here.
|
|
137
|
+
# ahead of that turn's {UserTurn}. Carries both {Agent::ChatTransport}s
|
|
138
|
+
# verbatim and unformatted — each chrome presents them its own way; the
|
|
139
|
+
# new model's stated cap and modalities ride on +to+.
|
|
111
140
|
ModelSwitched = Data.define(:from, :to)
|
|
112
141
|
|
|
113
|
-
# Out-of-band notice that a rescue path was taken: emitted by
|
|
114
|
-
# {Agent#run_loop} when {Control::StepLimit} trips and the
|
|
115
|
-
# {Synthesizer} fallback runs. Carries the reason to surface before
|
|
116
|
-
# the synthesizer's own output flows through.
|
|
117
|
-
FallbackNotice = Data.define(:reason)
|
|
118
|
-
|
|
119
142
|
# Out-of-band notice that the user cancelled the in-flight turn via
|
|
120
143
|
# {Control::Cancellable}. Emitted by {Agent#run_loop} just before the
|
|
121
|
-
# +Cancelled+ exception re-raises
|
|
122
|
-
#
|
|
144
|
+
# +Cancelled+ exception re-raises. No recovery follows; the caller
|
|
145
|
+
# returns control to the user.
|
|
123
146
|
Cancelled = Data.define
|
|
124
147
|
|
|
125
|
-
#
|
|
126
|
-
#
|
|
127
|
-
#
|
|
128
|
-
#
|
|
129
|
-
# Progress = Data.define(:title, :done) do
|
|
130
|
-
# include Pikuri::Agent::Event::Transient
|
|
131
|
-
# def to_s = done ? "#{title} — done" : title
|
|
132
|
-
# end
|
|
133
|
-
#
|
|
134
|
-
# The contract is two methods, both of which a +Data.define+ already
|
|
135
|
-
# answers: +#to_s+ is the whole rendering — a listener never inspects the
|
|
136
|
-
# fields, which is what keeps core ignorant of a gem's payload — and
|
|
137
|
-
# +#done+ says the sequence is over and its line may go away.
|
|
138
|
-
module Transient
|
|
139
|
-
end
|
|
140
|
-
|
|
141
|
-
# The conversation was cleared by {Agent#clear_conversation}: history
|
|
142
|
-
# is back to the system prompt, controls are reset, and each
|
|
143
|
-
# extension's {Extension#on_conversation_reset} has run. Emitted
|
|
144
|
-
# once, *before* the extension sweep, so pure-consumer listeners can
|
|
145
|
-
# reset display state; extension-owned state is signalled by the
|
|
146
|
-
# extensions' own domain events, not here. No payload.
|
|
147
|
-
Reset = Data.define
|
|
148
|
-
|
|
149
|
-
# A saved conversation was restored by {Agent#load_history!}. Always
|
|
150
|
-
# follows a {Reset}, which is the part that clears display state — this
|
|
151
|
-
# one says the conversation is *not* empty after all, and carries what a
|
|
152
|
-
# listener needs to stop lying about it.
|
|
148
|
+
# The agent was built with a saved conversation (+Agent.new(history:)+)
|
|
149
|
+
# rather than an empty one. Emitted once, at the end of construction,
|
|
150
|
+
# and carries what a listener needs to stop reporting an empty
|
|
151
|
+
# conversation.
|
|
153
152
|
#
|
|
154
153
|
# +tokens+ is the last assistant message's usage as recorded when the
|
|
155
154
|
# conversation was exported, so a running context readout can pick up
|
|
@@ -162,6 +161,19 @@ module Pikuri
|
|
|
162
161
|
# @!attribute [r] tokens
|
|
163
162
|
# @return [Tokens, nil] usage of the last restored assistant message
|
|
164
163
|
HistoryLoaded = Data.define(:messages, :tokens)
|
|
164
|
+
|
|
165
|
+
# The conversation was swapped for a compacted rendering of itself
|
|
166
|
+
# ({Configurator#replace_compacted_history}); tools, extensions and the
|
|
167
|
+
# system prompt stand as they were.
|
|
168
|
+
#
|
|
169
|
+
# Carries no token counts: what the shorter conversation costs is known
|
|
170
|
+
# only once the next reply reports usage.
|
|
171
|
+
#
|
|
172
|
+
# @!attribute [r] messages_before
|
|
173
|
+
# @return [Integer] how many messages the conversation held
|
|
174
|
+
# @!attribute [r] messages_after
|
|
175
|
+
# @return [Integer] how many it holds now
|
|
176
|
+
HistoryCompacted = Data.define(:messages_before, :messages_after)
|
|
165
177
|
end
|
|
166
178
|
end
|
|
167
179
|
end
|
|
@@ -4,13 +4,21 @@ module Pikuri
|
|
|
4
4
|
class Agent
|
|
5
5
|
# The Extension protocol — how hosts bolt extra capabilities
|
|
6
6
|
# (system-prompt sections, tools, lifecycle hooks) onto an {Agent}.
|
|
7
|
-
# Added via {Configurator#add_extension} inside the +Agent.new+ block
|
|
8
|
-
#
|
|
9
|
-
#
|
|
10
|
-
# {#on_user_message}
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
#
|
|
7
|
+
# Added via {Configurator#add_extension} inside the +Agent.new+ block,
|
|
8
|
+
# which calls {#configure} at once; the Agent then pulls
|
|
9
|
+
# {#system_prompt_snippets} when it assembles the prompt and calls
|
|
10
|
+
# {#on_user_message} on every user turn.
|
|
11
|
+
#
|
|
12
|
+
# class Reminder
|
|
13
|
+
# include Pikuri::Agent::Extension
|
|
14
|
+
# def system_prompt_snippets = ["Always be polite."]
|
|
15
|
+
# end
|
|
16
|
+
#
|
|
17
|
+
# An instance serves one agent, which is one conversation: build a fresh
|
|
18
|
+
# one for every +Agent.new+, so per-conversation state is plain instance
|
|
19
|
+
# state and nothing has to reset it; {Configurator#add_extension} refuses
|
|
20
|
+
# a reused one. A resource that legitimately outlives the conversation is
|
|
21
|
+
# built by the host and passed in.
|
|
14
22
|
#
|
|
15
23
|
# Mix this module in to inherit no-op defaults for every hook, and
|
|
16
24
|
# override what you need. Not including it also works *if the class
|
|
@@ -19,45 +27,21 @@ module Pikuri
|
|
|
19
27
|
#
|
|
20
28
|
# The whole surface fires on the *parent agent only* — sub-agents do not
|
|
21
29
|
# inherit extensions (each persona owns its toolset and prompt verbatim).
|
|
22
|
-
#
|
|
23
|
-
#
|
|
24
|
-
#
|
|
25
|
-
# class MyExtension
|
|
26
|
-
# include Pikuri::Agent::Extension
|
|
27
|
-
# def system_prompt_snippets = ["Always be polite."]
|
|
28
|
-
# # configure / bind not overridden — inherit the empty defaults
|
|
29
|
-
# end
|
|
30
|
-
#
|
|
31
|
-
# See +Pikuri::Mcp::Extension+ / +Pikuri::Skill::Extension+ for worked
|
|
32
|
-
# implementations.
|
|
30
|
+
# See +Pikuri::Workspace::Extension+ / +Pikuri::Thunderbird::Extension+ (sibling
|
|
31
|
+
# gems) for worked implementations.
|
|
33
32
|
module Extension
|
|
34
|
-
#
|
|
35
|
-
#
|
|
36
|
-
# {Configurator}
|
|
37
|
-
# state — typically:
|
|
33
|
+
# Install this extension on the agent being built. Keep +c+ to act on
|
|
34
|
+
# the agent later — {Configurator#emit_event} from a change callback,
|
|
35
|
+
# {Configurator#add_raw_tool} from a tool's +execute+. Default no-op.
|
|
38
36
|
#
|
|
39
|
-
#
|
|
40
|
-
#
|
|
41
|
-
#
|
|
42
|
-
# * read transport / cancellable / etc. off the Configurator
|
|
37
|
+
# A resumed conversation is {Configurator#history}, so an extension can
|
|
38
|
+
# rebuild what the transcript implies — the tools it had registered
|
|
39
|
+
# mid-conversation.
|
|
43
40
|
#
|
|
44
|
-
# @param c [Configurator] the
|
|
41
|
+
# @param c [Configurator] the agent's Configurator
|
|
45
42
|
# @return [void]
|
|
46
43
|
def configure(c); end
|
|
47
44
|
|
|
48
|
-
# Called by {Agent#initialize} after the block returns and the chat is
|
|
49
|
-
# fully wired, with the agent's {ExtensionContext}. Default no-op;
|
|
50
|
-
# override to install state keyed to the live agent — typically:
|
|
51
|
-
#
|
|
52
|
-
# * dynamic tools via {ExtensionContext#add_raw_tool}
|
|
53
|
-
# * domain-event wiring via {ExtensionContext#emit_event}
|
|
54
|
-
# * per-agent +on_close+ via {ExtensionContext#on_close}
|
|
55
|
-
# * stash +ctx+ if the extension's tools act on this agent later
|
|
56
|
-
#
|
|
57
|
-
# @param ctx [ExtensionContext] capability facade for the live agent
|
|
58
|
-
# @return [void]
|
|
59
|
-
def bind(ctx); end
|
|
60
|
-
|
|
61
45
|
# Optional per-turn hook fired after a user message is added to the
|
|
62
46
|
# chat. Default no-op returning +nil+; override and return a {String} to
|
|
63
47
|
# have it appended after the user turn as a +<system-reminder>+ reference
|
|
@@ -67,54 +51,34 @@ module Pikuri
|
|
|
67
51
|
# The Agent only ever *appends* the returned block at the tail — never
|
|
68
52
|
# rewrites or removes an earlier one, which would bust the provider
|
|
69
53
|
# prefix cache for everything after the edit. Stale blocks ride the
|
|
70
|
-
# existing context-window machinery, not a per-turn rewrite.
|
|
71
|
-
#
|
|
72
|
-
#
|
|
73
|
-
#
|
|
74
|
-
#
|
|
75
|
-
# @
|
|
76
|
-
#
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
#
|
|
80
|
-
#
|
|
81
|
-
|
|
82
|
-
# defining it.
|
|
83
|
-
#
|
|
84
|
-
# That distinction is the point: reset state that only makes sense
|
|
85
|
-
# within one conversation (+Pikuri::Tasks::Extension+ clears its list,
|
|
86
|
-
# the workspace clears its read-record); leave infrastructure alone
|
|
87
|
-
# (MCP subprocesses, a docker-backed server, the memory recorder's
|
|
88
|
-
# queue — a clear is not a quit).
|
|
89
|
-
#
|
|
90
|
-
# Do *not* touch the system prompt here — that refreshes automatically
|
|
91
|
-
# via {#system_prompt_snippets}, which the clear re-pulls. This hook is
|
|
92
|
-
# only for imperative state the prompt machinery can't express. An
|
|
93
|
-
# extension owning a domain event should emit it here so UI listeners
|
|
94
|
-
# see the reset (Tasks fires +Tasks::ListChanged+ with an empty list),
|
|
95
|
-
# synchronously after the Agent's {Event::Reset}.
|
|
96
|
-
#
|
|
97
|
-
# @param ctx [ExtensionContext] the live agent being cleared (same
|
|
98
|
-
# instance +bind+ received)
|
|
99
|
-
# @return [void]
|
|
100
|
-
def on_conversation_reset(ctx); end
|
|
54
|
+
# existing context-window machinery, not a per-turn rewrite. Why a hook
|
|
55
|
+
# rather than a listener: +design/decisions.md+ +D_on_user_message_hook+.
|
|
56
|
+
#
|
|
57
|
+
# @param content [String] the user message's text (initial or
|
|
58
|
+
# interloper); +""+ when the turn carries only attachments
|
|
59
|
+
# @param attachments [Array<Pikuri::Attachment>] what the model was
|
|
60
|
+
# shown with it. Passed as data, so each extension words it as it
|
|
61
|
+
# needs — a memory extension records a note naming each file, while a
|
|
62
|
+
# reminder that only reacts to the turn ignores them.
|
|
63
|
+
# @return [String, nil] text to append, stripped and wrapped, as a +:user+
|
|
64
|
+
# reference block after the user message; +nil+ or blank injects nothing
|
|
65
|
+
def on_user_message(content, attachments); end
|
|
101
66
|
|
|
102
67
|
# This extension's system-prompt contributions, as text sections.
|
|
103
68
|
# Default none (+[]+); override to contribute one or more.
|
|
104
69
|
#
|
|
105
|
-
# Pull, not push: the {Agent} assembles its prompt
|
|
106
|
-
# base with what every extension
|
|
107
|
-
#
|
|
108
|
-
#
|
|
109
|
-
#
|
|
110
|
-
# same constant.
|
|
70
|
+
# Pull, not push: the {Agent} assembles its prompt once, at
|
|
71
|
+
# construction, by concatenating the base with what every extension
|
|
72
|
+
# returns here. A section computed from live state (the workspace's file
|
|
73
|
+
# listing, a note read from disk) is therefore as of the conversation's
|
|
74
|
+
# start, and a "/clear" — a new agent — takes it again.
|
|
111
75
|
#
|
|
112
76
|
# No argument: read instance state populated in {#configure} (which runs
|
|
113
77
|
# first). Producing that state (starting servers, probing a model)
|
|
114
|
-
# belongs in +configure+; this only *reads* it
|
|
115
|
-
#
|
|
116
|
-
#
|
|
117
|
-
#
|
|
78
|
+
# belongs in +configure+; this only *reads* it (memoize an expensive
|
|
79
|
+
# one-shot at its source).
|
|
80
|
+
# Sections are joined by the Agent (blank/nil dropped), in registration
|
|
81
|
+
# order.
|
|
118
82
|
#
|
|
119
83
|
# @return [Array<String>] zero or more prompt sections; +[]+ for none
|
|
120
84
|
def system_prompt_snippets = []
|