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.
Files changed (60) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +17 -30
  3. data/lib/pikuri/agent/chat_transport.rb +168 -107
  4. data/lib/pikuri/agent/configurator.rb +194 -173
  5. data/lib/pikuri/agent/control/cancellable.rb +100 -70
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +107 -118
  8. data/lib/pikuri/agent/control.rb +13 -35
  9. data/lib/pikuri/agent/event.rb +144 -197
  10. data/lib/pikuri/agent/extension.rb +83 -95
  11. data/lib/pikuri/agent/history.rb +247 -0
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +169 -136
  14. data/lib/pikuri/agent/listener/token_log.rb +84 -157
  15. data/lib/pikuri/agent/listener.rb +24 -44
  16. data/lib/pikuri/agent/listener_list.rb +32 -47
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +1095 -577
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/bundler_env.rb +68 -0
  21. data/lib/pikuri/extractor/passthrough.rb +24 -31
  22. data/lib/pikuri/extractor.rb +125 -155
  23. data/lib/pikuri/file_type.rb +64 -136
  24. data/lib/pikuri/finalizers.rb +32 -47
  25. data/lib/pikuri/paths.rb +104 -13
  26. data/lib/pikuri/sanitizer.rb +46 -67
  27. data/lib/pikuri/subprocess.rb +86 -118
  28. data/lib/pikuri/testing.rb +369 -0
  29. data/lib/pikuri/tool/calculator.rb +168 -74
  30. data/lib/pikuri/tool/execute_context.rb +42 -0
  31. data/lib/pikuri/tool/parameters.rb +31 -29
  32. data/lib/pikuri/tool/result.rb +164 -0
  33. data/lib/pikuri/tool/trifecta_legs.rb +248 -0
  34. data/lib/pikuri/tool.rb +416 -67
  35. data/lib/pikuri/trifecta/contribution.rb +43 -0
  36. data/lib/pikuri/trifecta/node.rb +47 -0
  37. data/lib/pikuri/trifecta/report.rb +228 -0
  38. data/lib/pikuri/trifecta.rb +126 -0
  39. data/lib/pikuri/version.rb +1 -1
  40. data/lib/pikuri-core.rb +70 -92
  41. data/prompts/agent-loop.txt +5 -0
  42. data/prompts/pikuri-chat.txt +3 -12
  43. metadata +26 -72
  44. data/lib/pikuri/agent/context_window_detector.rb +0 -222
  45. data/lib/pikuri/agent/control/step_limit.rb +0 -111
  46. data/lib/pikuri/agent/extension_context.rb +0 -147
  47. data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
  48. data/lib/pikuri/agent/synthesizer.rb +0 -171
  49. data/lib/pikuri/extractor/html.rb +0 -303
  50. data/lib/pikuri/tool/fetch.rb +0 -172
  51. data/lib/pikuri/tool/scraper.rb +0 -186
  52. data/lib/pikuri/tool/search/brave.rb +0 -198
  53. data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
  54. data/lib/pikuri/tool/search/engines.rb +0 -186
  55. data/lib/pikuri/tool/search/exa.rb +0 -229
  56. data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
  57. data/lib/pikuri/tool/search/result.rb +0 -29
  58. data/lib/pikuri/tool/web_scrape.rb +0 -121
  59. data/lib/pikuri/tool/web_search.rb +0 -57
  60. data/lib/pikuri/url_cache.rb +0 -112
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pikuri-core
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.7
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Martin Vysny
@@ -23,20 +23,6 @@ dependencies:
23
23
  - - "~>"
24
24
  - !ruby/object:Gem::Version
25
25
  version: '2.9'
26
- - !ruby/object:Gem::Dependency
27
- name: nokogiri
28
- requirement: !ruby/object:Gem::Requirement
29
- requirements:
30
- - - "~>"
31
- - !ruby/object:Gem::Version
32
- version: '1.19'
33
- type: :runtime
34
- prerelease: false
35
- version_requirements: !ruby/object:Gem::Requirement
36
- requirements:
37
- - - "~>"
38
- - !ruby/object:Gem::Version
39
- version: '1.19'
40
26
  - !ruby/object:Gem::Dependency
41
27
  name: rainbow
42
28
  requirement: !ruby/object:Gem::Requirement
@@ -51,48 +37,20 @@ dependencies:
51
37
  - - "~>"
52
38
  - !ruby/object:Gem::Version
53
39
  version: '3.1'
54
- - !ruby/object:Gem::Dependency
55
- name: reverse_markdown
56
- requirement: !ruby/object:Gem::Requirement
57
- requirements:
58
- - - "~>"
59
- - !ruby/object:Gem::Version
60
- version: '3.0'
61
- type: :runtime
62
- prerelease: false
63
- version_requirements: !ruby/object:Gem::Requirement
64
- requirements:
65
- - - "~>"
66
- - !ruby/object:Gem::Version
67
- version: '3.0'
68
- - !ruby/object:Gem::Dependency
69
- name: ruby-readability
70
- requirement: !ruby/object:Gem::Requirement
71
- requirements:
72
- - - "~>"
73
- - !ruby/object:Gem::Version
74
- version: '0.7'
75
- type: :runtime
76
- prerelease: false
77
- version_requirements: !ruby/object:Gem::Requirement
78
- requirements:
79
- - - "~>"
80
- - !ruby/object:Gem::Version
81
- version: '0.7'
82
40
  - !ruby/object:Gem::Dependency
83
41
  name: ruby_llm
84
42
  requirement: !ruby/object:Gem::Requirement
85
43
  requirements:
86
44
  - - "~>"
87
45
  - !ruby/object:Gem::Version
88
- version: '1.15'
46
+ version: '2.2'
89
47
  type: :runtime
90
48
  prerelease: false
91
49
  version_requirements: !ruby/object:Gem::Requirement
92
50
  requirements:
93
51
  - - "~>"
94
52
  - !ruby/object:Gem::Version
95
- version: '1.15'
53
+ version: '2.2'
96
54
  - !ruby/object:Gem::Dependency
97
55
  name: zeitwerk
98
56
  requirement: !ruby/object:Gem::Requirement
@@ -111,12 +69,11 @@ description: |
111
69
  pikuri-core is the lean, audit-friendly foundation of the pikuri family:
112
70
  Pikuri::Agent (a thin wrapper around ruby_llm's chat loop) with its
113
71
  Configurator + Extension protocol, the strict Pikuri::Tool framework, a
114
- listener surface for rendering / budgets / sub-agents, and four bundled
115
- stateless tools (calculator, web search, web scrape, fetch). Extensions
116
- (skills, MCP, workspace, coding stack, named-agent personas) live in
72
+ listener surface for rendering / budgets / sub-agents, and a calculator
73
+ as the one bundled example tool. Extensions (web tools, skills, MCP,
74
+ workspace, coding stack, named-agent personas) live in
117
75
  sibling gems so a privacy-conscious user can install just this core and
118
- audit a minimal dependency tree. For the convenience bundle that pulls
119
- in everything, see the +pikuri+ metagem.
76
+ audit a minimal dependency tree.
120
77
  email:
121
78
  - martin@vysny.me
122
79
  executables: []
@@ -128,52 +85,49 @@ files:
128
85
  - lib/pikuri/agent.rb
129
86
  - lib/pikuri/agent/chat_transport.rb
130
87
  - lib/pikuri/agent/configurator.rb
131
- - lib/pikuri/agent/context_window_detector.rb
132
88
  - lib/pikuri/agent/control.rb
133
89
  - lib/pikuri/agent/control/cancellable.rb
90
+ - lib/pikuri/agent/control/handoff.rb
134
91
  - lib/pikuri/agent/control/interloper.rb
135
- - lib/pikuri/agent/control/step_limit.rb
136
92
  - lib/pikuri/agent/event.rb
137
93
  - lib/pikuri/agent/extension.rb
138
- - lib/pikuri/agent/extension_context.rb
94
+ - lib/pikuri/agent/history.rb
139
95
  - lib/pikuri/agent/listener.rb
140
96
  - lib/pikuri/agent/listener/in_memory_event_list.rb
141
- - lib/pikuri/agent/listener/rate_limited.rb
142
97
  - lib/pikuri/agent/listener/terminal.rb
143
98
  - lib/pikuri/agent/listener/token_log.rb
144
99
  - lib/pikuri/agent/listener_list.rb
145
- - lib/pikuri/agent/synthesizer.rb
100
+ - lib/pikuri/agent/request_instrumenter.rb
101
+ - lib/pikuri/attachment.rb
102
+ - lib/pikuri/bundler_env.rb
146
103
  - lib/pikuri/extractor.rb
147
- - lib/pikuri/extractor/html.rb
148
104
  - lib/pikuri/extractor/passthrough.rb
149
105
  - lib/pikuri/file_type.rb
150
106
  - lib/pikuri/finalizers.rb
151
107
  - lib/pikuri/paths.rb
152
108
  - lib/pikuri/sanitizer.rb
153
109
  - lib/pikuri/subprocess.rb
110
+ - lib/pikuri/testing.rb
154
111
  - lib/pikuri/tool.rb
155
112
  - lib/pikuri/tool/calculator.rb
156
- - lib/pikuri/tool/fetch.rb
113
+ - lib/pikuri/tool/execute_context.rb
157
114
  - lib/pikuri/tool/parameters.rb
158
- - lib/pikuri/tool/scraper.rb
159
- - lib/pikuri/tool/search/brave.rb
160
- - lib/pikuri/tool/search/duckduckgo.rb
161
- - lib/pikuri/tool/search/engines.rb
162
- - lib/pikuri/tool/search/exa.rb
163
- - lib/pikuri/tool/search/rate_limiter.rb
164
- - lib/pikuri/tool/search/result.rb
165
- - lib/pikuri/tool/web_scrape.rb
166
- - lib/pikuri/tool/web_search.rb
167
- - lib/pikuri/url_cache.rb
115
+ - lib/pikuri/tool/result.rb
116
+ - lib/pikuri/tool/trifecta_legs.rb
117
+ - lib/pikuri/trifecta.rb
118
+ - lib/pikuri/trifecta/contribution.rb
119
+ - lib/pikuri/trifecta/node.rb
120
+ - lib/pikuri/trifecta/report.rb
168
121
  - lib/pikuri/version.rb
122
+ - prompts/agent-loop.txt
169
123
  - prompts/pikuri-chat.txt
170
- homepage: https://codeberg.org/mvysny/pikuri
124
+ homepage: https://github.com/mvysny/pikuri
171
125
  licenses:
172
126
  - MIT
173
127
  metadata:
174
- source_code_uri: https://codeberg.org/mvysny/pikuri/src/branch/master
175
- changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
176
- bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
128
+ source_code_uri: https://github.com/mvysny/pikuri/tree/master
129
+ changelog_uri: https://github.com/mvysny/pikuri/blob/master/CHANGELOG.md
130
+ bug_tracker_uri: https://github.com/mvysny/pikuri/issues
177
131
  rubygems_mfa_required: 'true'
178
132
  rdoc_options: []
179
133
  require_paths:
@@ -192,5 +146,5 @@ requirements: []
192
146
  rubygems_version: 3.6.7
193
147
  specification_version: 4
194
148
  summary: The minimal core of the pikuri AI-assistant toolkit (Agent, Tool framework,
195
- web tools, bin/pikuri-chat).
149
+ bin/pikuri-chat).
196
150
  test_files: []
@@ -1,222 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require 'ruby_llm'
4
- require 'faraday'
5
- require 'json'
6
- require 'cgi'
7
-
8
- module Pikuri
9
- class Agent
10
- # Resolves the model's context-window cap by asking the server that
11
- # actually serves it. The only authoritative runtime source pikuri
12
- # has is llama.cpp's non-standard +/props+ endpoint, which reports
13
- # the server's *launched* +n_ctx+ (the real window — possibly
14
- # smaller than the model's theoretical max, e.g. +llama-server -c
15
- # 8192+ on a 128k model). Returns +nil+ — an honest "we don't
16
- # know" — for anything else.
17
- #
18
- # Used by {Agent#detect_and_emit_context_cap!} at construction and
19
- # after every model switch to feed {Listener::TokenLog} a cap it can
20
- # render alongside the running context size (so the +ctx=12.2k/32.0k+
21
- # line tells the operator how close the conversation is to the limit).
22
- # The caller prefers an explicit/inherited
23
- # {ChatTransport#context_window} over this probe; this runs only when
24
- # the transport carries none.
25
- #
26
- # == Why no ruby_llm registry source
27
- #
28
- # +RubyLLM::Model::Info#context_window+ is a static lookup in a
29
- # bundled +models.json+ snapshot: +nil+ for every +assume_exists+
30
- # local model id, +nil+ for anything newer than the snapshot, and —
31
- # worst — a *frozen* value for known models, so a window the provider
32
- # later bumped (256k → 1M) still reports the old number. A cap you
33
- # have to caveat defeats the cap's only job (a number trustworthy
34
- # enough to act on before +RubyLLM::ContextLengthExceededError+), so
35
- # pikuri deliberately does not consult it. The probe (server truth)
36
- # and an explicit {ChatTransport#context_window} (operator/parent
37
- # truth) are the only two sources; absent both, the cap is +nil+.
38
- #
39
- # == The openai-provider gate + auto-derived URL
40
- #
41
- # The probe only makes sense against an OpenAI-compatible local
42
- # server (llama.cpp), reached through ruby_llm's +:openai+ provider
43
- # with a custom base. So {.detect} runs only when
44
- # +transport.provider == :openai+ and derives the probe URL from the
45
- # *same* +RubyLLM.config.openai_api_base+ the chat itself uses —
46
- # +/props+ lives at the host root, NOT under +/v1+, so the +/v1+
47
- # suffix is stripped. Deriving from the live config (rather than a
48
- # URL passed in) means the probe can't target a different server than
49
- # the chat. A bare +:openai+ pointed at real +api.openai.com+ gets
50
- # one fast +/props+ 404 that degrades to +nil+ (the simple gate; not
51
- # worth narrowing — you're already sending that server the whole
52
- # conversation).
53
- #
54
- # == llama.cpp router mode
55
- #
56
- # A llama.cpp *router* (the multi-instance front that proxies to N
57
- # on-demand model servers) answers a bare +/props+ with
58
- # +{"role":"router", ..., "n_ctx":0}+ — there is no single loaded
59
- # model at the router itself, so its top-level +n_ctx+ is +0+. The
60
- # real per-model cap is one proxied hop away: +GET /props?model=<id>+
61
- # routes the probe to that model's instance, whose +/props+ carries
62
- # the launched +n_ctx+. So when the bare probe reports +role: router+
63
- # and a +model_id+ is known, this re-probes with the model id before
64
- # giving up. A plain single-model server is untouched: its bare
65
- # +/props+ already carries a positive +n_ctx+, so the router branch
66
- # never runs.
67
- #
68
- # == Failure handling
69
- #
70
- # The probe is best-effort. HTTP error, timeout, non-JSON body, or a
71
- # missing/invalid +n_ctx+ field all return +nil+ and log one +warn+
72
- # line via +Pikuri.logger_for('ContextWindowDetector')+. This is the
73
- # CLAUDE.md "secondary to the loop" carve-out — a wedged or
74
- # non-llama.cpp server should not abort agent construction over a
75
- # cosmetic readout.
76
- class ContextWindowDetector
77
- # Subsystem logger; set its level with
78
- # +PIKURI_LOG_CONTEXTWINDOWDETECTOR+ or the global +PIKURI_LOG+.
79
- #
80
- # @return [Logger]
81
- LOGGER = Pikuri.logger_for('ContextWindowDetector')
82
-
83
- # Connect timeout in seconds for the llama.cpp +/props+ probe.
84
- # Short on purpose: a server that isn't even listening should fail
85
- # fast rather than stall +Agent+ construction.
86
- #
87
- # @return [Integer]
88
- OPEN_TIMEOUT = 2
89
- # Read timeout in seconds for the llama.cpp +/props+ probe.
90
- # Generous on purpose, and the reason it differs from
91
- # {OPEN_TIMEOUT}: a llama.cpp router answers +/props?model=<id>+
92
- # only *after* spinning up that model's instance, and a cold model
93
- # load can take 10+ seconds — which the next chat turn must wait
94
- # for anyway. A read timeout shorter than the load would abandon
95
- # the probe (and lose the cap) precisely when switching to a
96
- # cold model. A server that accepts the connection but then hangs
97
- # would stall the actual chat identically, so tolerating the wait
98
- # here costs nothing extra.
99
- #
100
- # @return [Integer]
101
- READ_TIMEOUT = 30
102
-
103
- # Resolve the context-window cap for +transport+ by probing the
104
- # server that serves it.
105
- #
106
- # @param transport [Agent::ChatTransport] the model-resolution
107
- # triple; +provider+ gates the probe and +model+ drives the
108
- # router +?model=+ hop
109
- # @param openai_base [String, nil] the configured OpenAI-compatible
110
- # base URL the probe URL is derived from; defaults to the live
111
- # +RubyLLM.config.openai_api_base+. Passed explicitly only by
112
- # tests, which don't want to mutate global config.
113
- # @return [Integer, nil] the launched +n_ctx+, or +nil+ for a
114
- # non-+:openai+ transport, an unconfigured base, or any probe
115
- # failure
116
- def self.detect(transport, openai_base: RubyLLM.config.openai_api_base)
117
- return nil unless transport.provider == :openai
118
-
119
- url = props_url(openai_base)
120
- return nil if url.nil?
121
-
122
- new(probe_url: url, model_id: transport.model).probe
123
- end
124
-
125
- # Derive the llama.cpp +/props+ URL from the OpenAI-compatible
126
- # base. +/props+ sits at the host root, so a trailing +/v1+ is
127
- # stripped before appending.
128
- #
129
- # @param openai_base [String, nil]
130
- # @return [String, nil] the +/props+ URL, or +nil+ when the base
131
- # is blank
132
- def self.props_url(openai_base)
133
- base = openai_base.to_s.strip.chomp('/')
134
- return nil if base.empty?
135
-
136
- "#{base.delete_suffix('/v1')}/props"
137
- end
138
-
139
- # @param probe_url [String] full URL to llama.cpp +/props+
140
- # @param model_id [String, nil] the chat model id, used to follow a
141
- # llama.cpp router via +/props?model=<id>+ when the bare probe
142
- # reports +role: router+. +nil+ or empty disables that second hop.
143
- def initialize(probe_url:, model_id:)
144
- @probe_url = probe_url
145
- @model_id = model_id
146
- end
147
-
148
- # @return [Integer, nil] resolved cap, or +nil+ if the probe
149
- # produced none
150
- def probe
151
- probe_llama_cpp
152
- end
153
-
154
- private
155
-
156
- def probe_llama_cpp
157
- data = fetch_props(@probe_url)
158
- return nil if data.nil?
159
-
160
- n_ctx = positive_n_ctx(data)
161
- return n_ctx if n_ctx
162
-
163
- # llama.cpp router: the bare /props carries no model, so its
164
- # n_ctx is 0. Follow the router to the model's own instance.
165
- return probe_router_model if data['role'] == 'router' && model_id_present?
166
-
167
- warn_and_nil(
168
- "no positive integer at default_generation_settings.n_ctx in #{@probe_url} response"
169
- )
170
- end
171
-
172
- def probe_router_model
173
- url = "#{@probe_url}?model=#{CGI.escape(@model_id)}"
174
- data = fetch_props(url)
175
- return nil if data.nil?
176
-
177
- n_ctx = positive_n_ctx(data)
178
- return n_ctx if n_ctx
179
-
180
- warn_and_nil(
181
- "no positive integer at default_generation_settings.n_ctx in router probe #{url}"
182
- )
183
- end
184
-
185
- # GETs +url+ and parses its JSON body.
186
- #
187
- # @param url [String] a llama.cpp +/props+ URL
188
- # @return [Hash, nil] the parsed body, or +nil+ (after one +warn+
189
- # line) on non-200, timeout, transport error, or non-JSON body
190
- def fetch_props(url)
191
- response = Faraday.new(
192
- request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
193
- ).get(url) do |req|
194
- req.headers['Accept'] = 'application/json'
195
- end
196
-
197
- return warn_and_nil("HTTP #{response.status} from #{url}") unless response.status == 200
198
-
199
- JSON.parse(response.body)
200
- rescue Faraday::Error, JSON::ParserError => e
201
- warn_and_nil("#{e.class.name.split('::').last}: #{e.message}")
202
- end
203
-
204
- # @param data [Hash] a parsed +/props+ body
205
- # @return [Integer, nil] the launched +n_ctx+ when present and
206
- # positive, else +nil+
207
- def positive_n_ctx(data)
208
- n_ctx = data.dig('default_generation_settings', 'n_ctx')
209
- n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
210
- end
211
-
212
- def model_id_present?
213
- !@model_id.nil? && !@model_id.empty?
214
- end
215
-
216
- def warn_and_nil(reason)
217
- LOGGER.warn("llama.cpp /props probe failed: #{reason}")
218
- nil
219
- end
220
- end
221
- end
222
- end
@@ -1,111 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Pikuri
4
- class Agent
5
- module Control
6
- # Caps the number of tool calls per {Agent#run_loop}
7
- # invocation. ruby_llm has no built-in step budget; the
8
- # +Agent+ pokes {#tick!} on every +before_tool_call+
9
- # callback and {#reset!} at the start of each turn. Once the
10
- # counter exceeds the configured cap, {#tick!} raises
11
- # {Exceeded} and the +Agent+ applies the {#on_exhausted}
12
- # policy: re-raise to the host (the default), or run the
13
- # step-exhaustion synthesizer to salvage a partial answer.
14
- #
15
- # == Why the policy lives here, not on +Agent+
16
- #
17
- # Synthesis can only ever fire off a tripped step limit, so
18
- # an +Agent.new(synthesize: ...)+ kwarg would be meaningless
19
- # whenever +step_limit:+ is +nil+ — an invalid combination
20
- # the API would have to document away. Attaching the policy
21
- # to the budget makes "what happens when the budget runs
22
- # out" travel with the budget, and the nonsense state is
23
- # unrepresentable. The host picks per wiring: a Q&A REPL
24
- # wants +:synthesize+ (salvage an answer from the evidence
25
- # gathered so far); a coding agent wants the default
26
- # +:raise+ (a tools-free pass can't finish writing code —
27
- # stop, let the user say "continue"; {#reset!} at the next
28
- # turn boundary refreshes the budget).
29
- class StepLimit
30
- # Valid {#on_exhausted} policies.
31
- ON_EXHAUSTED = %i[raise synthesize].freeze
32
- # Raised by {#tick!} once tool-call count exceeds +max+.
33
- # Carries the budget that was tripped so rescue clauses
34
- # can include it in user-facing messages.
35
- class Exceeded < StandardError
36
- # @return [Integer]
37
- attr_reader :max_steps
38
-
39
- # @param max_steps [Integer]
40
- def initialize(max_steps)
41
- @max_steps = max_steps
42
- super("Agent loop exceeded #{max_steps} steps")
43
- end
44
- end
45
-
46
- # @return [Integer] the configured cap
47
- attr_reader :max
48
-
49
- # @return [Symbol] what {Agent#run_loop} does when this
50
- # budget trips: +:raise+ lets {Exceeded} propagate to the
51
- # host; +:synthesize+ runs the tools-free synthesizer
52
- # rescue. See the class header for how to pick.
53
- attr_reader :on_exhausted
54
-
55
- # @param max [Integer] hard cap on tool-call rounds; must
56
- # be positive
57
- # @param on_exhausted [Symbol] +:raise+ (default) or
58
- # +:synthesize+ — see {#on_exhausted}
59
- # @raise [ArgumentError] if +max+ is zero or negative, or
60
- # +on_exhausted+ is not one of {ON_EXHAUSTED}
61
- def initialize(max:, on_exhausted: :raise)
62
- raise ArgumentError, "max must be positive, got #{max}" if max <= 0
63
- raise ArgumentError, "on_exhausted must be one of #{ON_EXHAUSTED.inspect}, got #{on_exhausted.inspect}" \
64
- unless ON_EXHAUSTED.include?(on_exhausted)
65
-
66
- @max = max
67
- @on_exhausted = on_exhausted
68
- @step = 0
69
- end
70
-
71
- # Increment the tool-call counter; raise {Exceeded} once
72
- # it crosses {#max}. Called by {Agent} from its
73
- # +before_tool_call+ wiring.
74
- #
75
- # @return [void]
76
- # @raise [Exceeded] when the counter has now exceeded
77
- # {#max}
78
- def tick!
79
- @step += 1
80
- raise Exceeded, @max if @step > @max
81
- end
82
-
83
- # Reset the counter back to zero. Called by {Agent} at the
84
- # start of each turn (in {Agent#run_loop} before forwarding
85
- # the user message to the chat) so the same instance can
86
- # govern many turns across a long-running REPL. Mid-loop
87
- # {Control::Interloper} injections deliberately do *not*
88
- # trigger a reset — those are additional context for the
89
- # same turn, not a fresh one, and a chatty user could
90
- # otherwise refresh the budget forever by injecting.
91
- #
92
- # @return [void]
93
- def reset!
94
- @step = 0
95
- end
96
-
97
- # @return [Integer] current step count; exposed so callers
98
- # can introspect it (and so tests can assert it)
99
- attr_reader :step
100
-
101
- # @return [String] short config dump for {Agent#to_s}.
102
- # The policy only renders when it's the non-default
103
- # +:synthesize+, so existing banner output is unchanged.
104
- def to_s
105
- policy = @on_exhausted == :raise ? '' : ", on_exhausted=#{@on_exhausted}"
106
- "StepLimit(max=#{@max}#{policy})"
107
- end
108
- end
109
- end
110
- end
111
- end
@@ -1,147 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Pikuri
4
- class Agent
5
- # Capability facade handed to {Extension#bind} and
6
- # {Extension#on_user_message} — the runtime counterpart of
7
- # {Configurator}. Where the Configurator collects *build-time*
8
- # declarations (tools, listeners, prompt snippets), this object
9
- # grants the *runtime* capabilities an extension needs once the
10
- # agent is fully wired: emitting domain events onto the listener
11
- # stream, registering raw per-agent tools, and deriving sub-agent
12
- # listener lists.
13
- #
14
- # == Why a handed object, not a getter on Agent
15
- #
16
- # The {Agent} deliberately exposes NO public path to these
17
- # capabilities — no +listeners+ reader, no +chat+ reader, no
18
- # emit method. Holding an agent reference grants read access to
19
- # its configuration ({Agent#tools}, {Agent#transport}, ...) and
20
- # nothing more; the write capabilities live here, and the only
21
- # way to obtain this object is to be an {Extension} receiving a
22
- # +bind+ / +on_user_message+ call (or to be handed it onward by
23
- # one, e.g. {Pikuri::SubAgent::SubAgentTool} and
24
- # {Pikuri::Mcp::Servers::Connect} both capture the context their
25
- # extension's +bind+ received). Capabilities flow by explicit
26
- # handoff, never by fetching from a globally reachable object.
27
- #
28
- # The usual Ruby caveat applies: nothing here is mechanically
29
- # sealed (+instance_variable_get+ exists). The boundary is the
30
- # API contract — same as every seam in CLAUDE.md.
31
- #
32
- # == Boundary rule
33
- #
34
- # Operations that *act on* the live agent's wiring live here.
35
- # Passive readers of constructor-given config (+transport+,
36
- # +id+, +streaming+, +tools+, +cancellable+, ...) stay on
37
- # {Agent}, reachable via {#agent}. Don't move readers in; don't
38
- # add capabilities to Agent.
39
- #
40
- # == Audit
41
- #
42
- # One context per agent, constructed by {Agent#initialize} right
43
- # before the extension +bind+ sweep. {ListenerList#emit} has
44
- # exactly two callers: {Agent} (loop narration) and this class
45
- # (extension domain events). The roster of capability users is
46
- # +grep -rn 'emit_event\|add_raw_tool\|sub_agent_listeners'
47
- # pikuri-*/lib/+.
48
- class ExtensionContext
49
- # @param agent [Agent] the live, fully wired agent.
50
- # @param chat [RubyLLM::Chat] the agent's underlying chat —
51
- # target of {#add_raw_tool}.
52
- # @param listeners [ListenerList] the agent's listener list —
53
- # target of {#emit_event} / {#sub_agent_listeners}.
54
- # @param on_close_sink [Array<Proc>] the agent's live
55
- # +@on_close_handlers+ array, which {#on_close} appends to —
56
- # same live-sink shape as {Configurator}'s +on_close_sink:+.
57
- def initialize(agent:, chat:, listeners:, on_close_sink:)
58
- @agent = agent
59
- @chat = chat
60
- @listeners = listeners
61
- @on_close_handlers = on_close_sink
62
- end
63
-
64
- # @return [Agent] the live agent, for read access to its
65
- # configuration (tools, transport, id, streaming, ...).
66
- attr_reader :agent
67
-
68
- # Emit a domain event onto the agent's listener stream.
69
- #
70
- # Core {Event} variants narrate the chat loop and are emitted
71
- # by {Agent} alone; gems define their own variants (e.g.
72
- # +Pikuri::Tasks::ListChanged+) in their own namespace and
73
- # emit them here. Listeners must no-op on variants they don't
74
- # recognize — {Listener::Base#on_event}'s default and
75
- # +case+-fallthrough give that for free.
76
- #
77
- # Called on the agent's thread (typically from inside a tool's
78
- # +execute+, where the event lands between {Event::ToolCall}
79
- # and {Event::ToolResult} in the stream). Listeners doing
80
- # cross-thread handoff snapshot/serialize inside +on_event+.
81
- #
82
- # @param event [Object] an immutable event value (by
83
- # convention a +Data+ instance).
84
- # @return [void]
85
- def emit_event(event)
86
- @listeners.emit(event)
87
- nil
88
- end
89
-
90
- # Register a raw +RubyLLM::Tool+ subclass on the agent's
91
- # underlying chat, bypassing the {Pikuri::Tool}
92
- # strict-validation seam — hence "raw": native pikuri tools
93
- # should go through {Pikuri::Tool} (registered at build time
94
- # via {Configurator#add_tool}) so they get {Tool::Parameters}
95
- # validation and the LLM-actionable +"Error: ..."+ contract.
96
- # Intended callers: {Pikuri::Mcp::Servers} (MCP tools
97
- # deliberately bypass — see IDEAS.md §"MCP tools bypass
98
- # +Pikuri::Tool+ entirely") and
99
- # {Pikuri::SubAgent::Extension} (the +agent+ tool must
100
- # register after the parent's tool list is final).
101
- #
102
- # The added tool does NOT enter {Agent#tools}, only the chat's
103
- # tool list. Sub-agents therefore cannot snapshot it — which
104
- # is the whole point: activation is strictly per-agent, see
105
- # IDEAS.md §"Per-agent activation, no propagation".
106
- #
107
- # @param ruby_llm_tool [Class] subclass of +RubyLLM::Tool+
108
- # @return [void]
109
- def add_raw_tool(ruby_llm_tool)
110
- @chat.with_tool(ruby_llm_tool)
111
- nil
112
- end
113
-
114
- # Derive a listener list for a spawned sub-agent via
115
- # {ListenerList#for_sub_agent}. Sole intended caller:
116
- # {Pikuri::SubAgent::SubAgentTool}, once per spawn.
117
- #
118
- # The derived list deliberately aliases the parent's listener
119
- # *instances* where a listener opts to share by reference
120
- # (stateful sinks like {Listener::InMemoryEventList}) — see
121
- # {ListenerList#for_sub_agent} for the per-listener semantics.
122
- #
123
- # @param params [Hash{Symbol => Object}] forwarded to each
124
- # listener's +for_sub_agent+ hook (currently +id:+).
125
- # @return [ListenerList]
126
- def sub_agent_listeners(**params)
127
- @listeners.for_sub_agent(**params)
128
- end
129
-
130
- # Register a handler called by {Agent#close}. Symmetric to
131
- # {Configurator#on_close} — same LIFO + per-handler-rescue +
132
- # idempotent semantics — but available post-construction, so
133
- # an {Extension}'s +bind+ can install per-agent cleanup keyed
134
- # to this specific agent (e.g. +Pikuri::Memory::Extension+
135
- # arms its recorder's bounded flush here).
136
- #
137
- # @yield called with no arguments at close time
138
- # @return [void]
139
- def on_close(&blk)
140
- raise ArgumentError, 'on_close requires a block' unless block_given?
141
-
142
- @on_close_handlers << blk
143
- nil
144
- end
145
- end
146
- end
147
- end