pikuri-core 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +16 -29
  3. data/lib/pikuri/agent/chat_transport.rb +114 -33
  4. data/lib/pikuri/agent/configurator.rb +191 -110
  5. data/lib/pikuri/agent/control/cancellable.rb +25 -16
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +87 -120
  8. data/lib/pikuri/agent/control.rb +9 -11
  9. data/lib/pikuri/agent/event.rb +73 -61
  10. data/lib/pikuri/agent/extension.rb +45 -81
  11. data/lib/pikuri/agent/history.rb +91 -497
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +115 -108
  14. data/lib/pikuri/agent/listener/token_log.rb +21 -55
  15. data/lib/pikuri/agent/listener.rb +4 -4
  16. data/lib/pikuri/agent/listener_list.rb +19 -13
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +624 -448
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/extractor/passthrough.rb +5 -2
  21. data/lib/pikuri/extractor.rb +43 -12
  22. data/lib/pikuri/file_type.rb +4 -4
  23. data/lib/pikuri/finalizers.rb +2 -2
  24. data/lib/pikuri/paths.rb +1 -1
  25. data/lib/pikuri/sanitizer.rb +4 -3
  26. data/lib/pikuri/subprocess.rb +17 -5
  27. data/lib/pikuri/testing.rb +122 -49
  28. data/lib/pikuri/tool/calculator.rb +134 -30
  29. data/lib/pikuri/tool/execute_context.rb +2 -2
  30. data/lib/pikuri/tool/parameters.rb +10 -0
  31. data/lib/pikuri/tool/result.rb +164 -0
  32. data/lib/pikuri/tool/trifecta_legs.rb +52 -21
  33. data/lib/pikuri/tool.rb +298 -24
  34. data/lib/pikuri/trifecta/report.rb +28 -30
  35. data/lib/pikuri/trifecta.rb +1 -2
  36. data/lib/pikuri/version.rb +1 -1
  37. data/lib/pikuri-core.rb +5 -11
  38. metadata +16 -73
  39. data/lib/pikuri/agent/context_window_detector.rb +0 -181
  40. data/lib/pikuri/agent/control/step_limit.rb +0 -95
  41. data/lib/pikuri/agent/extension_context.rb +0 -120
  42. data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
  43. data/lib/pikuri/agent/synthesizer.rb +0 -129
  44. data/lib/pikuri/extractor/html.rb +0 -256
  45. data/lib/pikuri/ruby_llm_patches.rb +0 -106
  46. data/lib/pikuri/tool/fetch.rb +0 -146
  47. data/lib/pikuri/tool/scraper.rb +0 -144
  48. data/lib/pikuri/tool/search/brave.rb +0 -170
  49. data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
  50. data/lib/pikuri/tool/search/engines.rb +0 -319
  51. data/lib/pikuri/tool/search/exa.rb +0 -195
  52. data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
  53. data/lib/pikuri/tool/search/result.rb +0 -24
  54. data/lib/pikuri/tool/web_scrape.rb +0 -105
  55. data/lib/pikuri/tool/web_search.rb +0 -133
  56. data/lib/pikuri/url_cache.rb +0 -96
@@ -3,79 +3,47 @@
3
3
  module Pikuri
4
4
  class Agent
5
5
  module Control
6
- # Mid-loop host→agent injection queue. A host (TUI, web client)
7
- # constructs an +Interloper+, passes it to {Agent#initialize} via
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
- # == Two kinds
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
- # Each item carries a {Item#kind}, driving how {Agent#drain_interloper}
16
- # lands it:
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
- # - +:user+ ({#inject_user_message}) — a mid-loop user turn: appended
19
- # verbatim, emits +Event::UserTurn(mid_loop: true)+, and runs the
20
- # {Extension#on_user_message} dispatch (prefetch/record like an initial
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
- # Both reach the wire as +role: :user+ — the kinds differ in dispatch and
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
- # Groundwork for downstream TUI/web hosts: the bundled +bin/pikuri-*+ do
32
- # not wire one (stdin is synchronous). A host running the agent on a
33
- # worker thread wires one in with no other changes.
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
- # == Delivery boundary
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. Producers are the two
77
- # +inject_*+ methods; the consumer is {Agent#drain_interloper}.
78
- Item = Data.define(:kind, :content)
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
- # Optional host callback invoked with the new pending count whenever it
87
- # changes (after {#inject_user_message}, and after a {#drain!} that
88
- # empties a non-empty queue). +nil+ (default) disables it. Runs
89
- # *outside* the queue lock, on the mutating thread, so a callback
90
- # feeding another thread should hand off only immutable data.
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
- # @return [Proc, nil]
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 (any thread; +Mutex+-guarded). Fires
96
- # {#on_change} with the new count, outside the lock.
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
- # @param content [String] non-blank user-supplied text
99
- # @raise [ArgumentError] if +content+ is +nil+/blank — a blank
100
- # injection would poison the chat history like a blank turn
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
- enqueue(:user, content)
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
- # other retrieved context injected on the host's own initiative, not a
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 (e.g. a rendered
111
- # skill block); an own semantic tag is kept, the +<system-reminder>+
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
- # Non-destructive snapshot of the queue in delivery order, for a host
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 from any
135
- # thread (may have drained by the time the caller reads it)
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. Called by {Agent}'s
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; empty when the queue
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(0) unless items.empty?
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
- # @raise [ArgumentError] if +content+ is +nil+/blank
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
- count = @mutex.synchronize { @items << Item.new(kind: kind, content: content); @items.size }
180
- @on_change&.call(count)
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
@@ -2,22 +2,20 @@
2
2
 
3
3
  module Pikuri
4
4
  class Agent
5
- # Namespace for the +Agent+'s host-facing controls: {StepLimit},
6
- # {Cancellable}, and {Interloper}. Each is a small value-holder the +Agent+
7
- # reads from (or pokes into the event stream from) at fixed points in
8
- # ruby_llm's callback cycle. They are *not* listeners — they receive no
9
- # events and never appear in a {ListenerList}.
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, ticks the step counter, checks the cancel flag,
14
- # and drains the interloper queue — "what fires when" is one grep for
15
- # +@listeners.emit+ in +agent.rb+.
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, sub-agents, and the synthesizer.
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
@@ -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. +Pikuri::Tasks::ListChanged+) and emit
13
- # them via {ExtensionContext#emit_event} onto the same stream;
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
- UserTurn = Data.define(:content, :mid_loop) do
23
- # @param content [String] user-supplied text
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. +arguments+ is
70
- # the raw hash ruby_llm parsed from the model's +tool_calls+ JSON —
71
- # unvalidated. Emitted by +before_tool_call+.
72
- ToolCall = Data.define(:name, :arguments)
73
-
74
- # The observation a tool produced ({Tool#run}'s return). Recoverable
75
- # failures arrive as +"Error: ..."+ strings, not exceptions. Emitted
76
- # by +after_tool_result+.
77
- ToolResult = Data.define(:content)
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
- # just before the new model's {ContextCap}. Carries both
108
- # {Agent::ChatTransport}s verbatim and unformatted — each chrome
109
- # presents them its own way. The new cap rides on the paired
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 — unlike {FallbackNotice}, no
122
- # recovery follows; the caller returns control to the user.
144
+ # +Cancelled+ exception re-raises. No recovery follows; the caller
145
+ # returns control to the user.
123
146
  Cancelled = Data.define
124
147
 
125
- # Marks a *domain* event whose successor **replaces** it rather than adding
126
- # to a log: an indexing bar, a download percentage. A chrome that can
127
- # rewrite a line does; one that cannot shows only the final state.
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
- # the Agent then drives a fixed hook set: {#configure} during the block
9
- # (gets the {Configurator}), {#bind} once fully constructed,
10
- # {#on_user_message} per user turn, {#on_conversation_reset} per
11
- # {Agent#clear_conversation} (these three get the runtime
12
- # {ExtensionContext}), and {#system_prompt_snippets} whenever the prompt
13
- # is (re)assembled (no argument — reads state set in +configure+).
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
- # == Example
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
- # Called immediately by {Configurator#add_extension} during the
35
- # +Agent.new+ block, once per instance, with the parent's
36
- # {Configurator}. Default no-op; override to install *agent-agnostic*
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
- # * tools via {Configurator#add_tool}, listeners via
40
- # {Configurator#add_listener}
41
- # * parent-only +on_close+ cleanup via {Configurator#on_close}
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 parent agent's Configurator
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
- # @param ctx [ExtensionContext] the live agent whose turn this is (same
73
- # instance +bind+ received)
74
- # @param content [String] the user message (initial or interloper)
75
- # @return [String, nil] text to inject verbatim as a system-role message
76
- # after the user message, or +nil+ to inject nothing
77
- def on_user_message(ctx, content); end
78
-
79
- # Optional hook fired by {Agent#clear_conversation} (a "/clear").
80
- # Override to drop *conversation-scoped* state; default no-op, so an
81
- # extension holding only process/infrastructure state opts out by not
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 by concatenating the
106
- # base with what every extension returns here — at construction and
107
- # again on every {Agent#clear_conversation}. So a section computed from
108
- # live state (a resident memory persona, +MACHINE.md+ from disk) is
109
- # *recomputed* on clear and stays current; a static section returns the
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, so it stays cheap enough
115
- # for every clear (memoize an expensive one-shot at its source —
116
- # +Pikuri::Os::SystemInfo#prompt_section+). Sections are joined by the
117
- # Agent (blank/nil dropped), in registration order.
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 = []