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
@@ -0,0 +1,247 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'securerandom'
4
+
5
+ module Pikuri
6
+ class Agent
7
+ # A conversation, as a value — what {Agent#export_history} hands out and
8
+ # +Agent.new(history:)+ resumes:
9
+ #
10
+ # history = agent.export_history
11
+ # agent.close
12
+ # Agent.new(transport: t, system_prompt: p, history: history)
13
+ #
14
+ # The system prompt is *not* here — the resuming agent assembles its own
15
+ # from every extension, so a resumed conversation gets today's
16
+ # prompt (a re-read +MACHINE.md+, a fresh memory persona) rather than
17
+ # yesterday's.
18
+ #
19
+ # pikuri never writes one to disk nor reads one back: storing a
20
+ # conversation, and validating stored bytes on the way in, is the host's.
21
+ #
22
+ # == Implementation details
23
+ #
24
+ # Attachment bytes are held **eagerly** as {Pikuri::Attachment}s, never a
25
+ # lazy handle to a file that can change underneath — so +==+ compares
26
+ # content, and the history is what the model saw.
27
+ class History < Data.define(:messages)
28
+ # What a +user+-role message *is*: something the human typed
29
+ # (+"user"+), or reference text pikuri injected on its own initiative —
30
+ # recalled memory, a host-loaded skill, a path-activation promotion
31
+ # (+"reference"+, what {Agent#append_reference_block} appends).
32
+ #
33
+ # Local only: both land on the wire as +role: :user+, and no provider is
34
+ # told which is which. It exists so a resumed conversation can tell a
35
+ # stale skill listing from something the human meant.
36
+ KINDS = %w[user reference].freeze
37
+
38
+ # One tool call the assistant asked for. +id+ is the provider's own
39
+ # identifier and is load-bearing — the +tool+ message answering this call
40
+ # repeats it, and providers reject a pair that does not match.
41
+ #
42
+ # +display_name+ and +argument+ are the chrome's display line for the call
43
+ # (+"Write"+ / +"lib/foo.rb"+) — local to pikuri like {Message#id}, so no
44
+ # provider ever sees them. They are kept because a later wiring may no
45
+ # longer have the tool that composed them — a removed extension, a renamed
46
+ # MCP server — and +nil+ falls back to {Pikuri::Tool.display_name_for} /
47
+ # {Pikuri::Tool.describe_arguments}.
48
+ ToolCall = Data.define(:id, :name, :arguments, :display_name, :argument) do
49
+ # @param id [String] the provider's tool-call id
50
+ # @param name [String] the tool name
51
+ # @param arguments [Hash] arguments as the model sent them
52
+ # @param display_name [String, nil] see {Pikuri::Tool#display_name}
53
+ # @param argument [String, nil] see {Pikuri::Tool#describe_call}
54
+ def initialize(id:, name:, arguments: {}, display_name: nil, argument: nil)
55
+ super
56
+ end
57
+ end
58
+
59
+ # An assistant reasoning block, as the provider reported it.
60
+ #
61
+ # The two fields are not symmetric, and which one carries the substance
62
+ # flips by provider: on Anthropic +signature+ is the full reasoning,
63
+ # encrypted, and +text+ a summary that is empty by default; on an
64
+ # OpenAI-compatible server +text+ is the reasoning itself and
65
+ # +signature+ is usually absent. So the whole block, never one field, is
66
+ # what {Agent} withholds from a model that did not produce it — see
67
+ # +design/decisions.md+ +D_thinking_block_replay+.
68
+ Thinking = Data.define(:text, :signature)
69
+
70
+ # Per-message token usage, as the provider reported it. Carried so a
71
+ # host's context readout can be reseeded after a resume — nothing on the
72
+ # wire needs it.
73
+ Tokens = Data.define(:input, :output, :cached, :cache_creation, :thinking)
74
+
75
+ # One message. +id+ and +kind+ are pikuri's own and never reach a
76
+ # provider; everything else is what the model saw.
77
+ #
78
+ # +content+ is always a String (empty on a pure tool-call turn, which is
79
+ # what ruby_llm stores); anything the model was *shown* beyond text is an
80
+ # {Pikuri::Attachment} in +attachments+.
81
+ Message = Data.define(
82
+ :id, :role, :kind, :content, :attachments,
83
+ :tool_calls, :tool_call_id, :model_id, :thinking, :tokens, :summary
84
+ ) do
85
+ # @param id [String] see {History.mint_id}
86
+ # @param role [String] +"user"+, +"assistant"+ or +"tool"+; never
87
+ # +"system"+ — the prompt is re-assembled, not replayed
88
+ # @param kind [String] one of {KINDS}; defaults to +"user"+
89
+ # @param content [String] the text the model saw; +""+ is legal
90
+ # @param attachments [Array<Pikuri::Attachment>]
91
+ # @param tool_calls [Array<ToolCall>] empty unless the assistant asked
92
+ # for tools
93
+ # @param tool_call_id [String, nil] set exactly on a +tool+ message
94
+ # @param model_id [String, nil] which model produced this
95
+ # @param thinking [Thinking, nil]
96
+ # @param tokens [Tokens, nil]
97
+ # @param summary [String, nil] a +tool+ message's display line
98
+ # (+"Returned 23 search results"+) — local to pikuri like {#id}, and
99
+ # kept because it was computed from structure the +content+ no
100
+ # longer holds, so nothing can recompute it on resume. +nil+ falls
101
+ # back to {Pikuri::Tool.describe_content}.
102
+ def initialize(id:, role:, content:, kind: 'user', attachments: [], tool_calls: [],
103
+ tool_call_id: nil, model_id: nil, thinking: nil, tokens: nil, summary: nil)
104
+ super
105
+ end
106
+
107
+ # @return [Boolean] whether this message asked for tools.
108
+ def tool_call? = !tool_calls.empty?
109
+
110
+ # Snapshot a live +RubyLLM::Message+. Attachment bytes are read *now*
111
+ # — the file a tool showed the model may be gone or changed by the
112
+ # time anyone resumes this.
113
+ #
114
+ # @param msg [RubyLLM::Message] must not be +role: :system+.
115
+ # @param id [String] see {History.mint_id}.
116
+ # @param kind [String] one of {KINDS}.
117
+ # @param summary [String, nil] see {Message#summary}.
118
+ # @param tool_call_lines [Hash{String=>Hash}] display strings per call
119
+ # id, +{id => {display_name:, argument:}}+ — what {Agent} recorded as
120
+ # each call went out; an id it has nothing for stores +nil+s.
121
+ # @return [Message]
122
+ def self.from_ruby_llm(msg, id:, kind: 'user', summary: nil, tool_call_lines: {})
123
+ attachments = msg.attachments.map { |a| Pikuri::Attachment.from_ruby_llm(a) }
124
+ t = msg.tokens
125
+ new(
126
+ id: id, role: msg.role.to_s, kind: kind, content: msg.content.to_s, attachments: attachments,
127
+ summary: summary,
128
+ # The server's call ids, not the ones ruby_llm mints per chat: a
129
+ # restored call replays its +id+ on the wire, and anything else
130
+ # would change the request bytes. See +D_history_wire_call_ids+.
131
+ tool_calls: (msg.tool_calls || {}).values.map do |c|
132
+ lines = tool_call_lines[c.provider_call_id] || {}
133
+ ToolCall.new(id: c.provider_call_id, name: c.name, arguments: c.arguments || {},
134
+ display_name: lines[:display_name], argument: lines[:argument])
135
+ end,
136
+ tool_call_id: msg.provider_call_id,
137
+ model_id: msg.model,
138
+ thinking: msg.thinking && Thinking.new(text: msg.thinking.text, signature: msg.thinking.signature),
139
+ # ruby_llm gives every message a Tokens, all-nil where nothing was
140
+ # counted; +nil+ keeps "no usage" out of the export.
141
+ tokens: (Tokens.new(input: t.input, output: t.output, cached: t.cache_read,
142
+ cache_creation: t.cache_write, thinking: t.thinking) if t.to_h.any?)
143
+ )
144
+ end
145
+
146
+ # Rebuild the +RubyLLM::Message+ this was taken from.
147
+ #
148
+ # @param keep_thinking [Boolean] +false+ replays the turn without its
149
+ # {Thinking} block at all — what {Agent} passes for a turn some
150
+ # *other* model produced, since a thinking block lands in a slot the
151
+ # receiving model reads as its own scratchpad. Dropped from the
152
+ # *message*, not from the record: {Agent#export_history} still
153
+ # carries it. See +design/decisions.md+ +D_thinking_block_replay+.
154
+ # @return [RubyLLM::Message]
155
+ def to_ruby_llm(keep_thinking: true)
156
+ calls = tool_calls.to_h do |c|
157
+ [c.id, RubyLLM::ToolCall.new(id: c.id, name: c.name, arguments: c.arguments)]
158
+ end
159
+ replayed = thinking if keep_thinking
160
+ RubyLLM::Message.new(
161
+ role: role.to_sym,
162
+ # An attachment-only user turn went out with no text part
163
+ # ({Agent#run_loop}); +""+ would replay as an empty one, which
164
+ # Anthropic refuses.
165
+ content: content.empty? && !attachments.empty? ? nil : content,
166
+ attachments: attachments.map(&:to_ruby_llm),
167
+ tool_calls: calls.empty? ? nil : calls,
168
+ tool_call_id: tool_call_id,
169
+ model: model_id,
170
+ thinking: replayed && RubyLLM::Thinking.build(
171
+ text: replayed.text, signature: replayed.signature
172
+ ),
173
+ tokens: tokens && RubyLLM::Tokens.new(input: tokens.input, output: tokens.output, cache_read: tokens.cached,
174
+ cache_write: tokens.cache_creation, thinking: tokens.thinking)
175
+ )
176
+ end
177
+ end
178
+
179
+ # A fresh message id: lexicographically sortable, so ordering falls out
180
+ # of the id itself and a future tree format inherits identity for free.
181
+ #
182
+ # History.mint_id # => "0198c4f1a2b30001f3c9a2"
183
+ #
184
+ # Not a wire value — no provider is ever shown one.
185
+ #
186
+ # @return [String] 22 hex chars: 12 of millisecond timestamp, 4 of
187
+ # per-process counter (so two ids minted in one millisecond still
188
+ # sort), 6 random.
189
+ def self.mint_id
190
+ MINT_LOCK.synchronize do
191
+ @counter = ((@counter || -1) + 1) & 0xffff
192
+ format('%012x%04x%s', (Time.now.to_f * 1000).to_i, @counter, SecureRandom.hex(3))
193
+ end
194
+ end
195
+
196
+ MINT_LOCK = Mutex.new
197
+ private_constant :MINT_LOCK
198
+
199
+ # @param messages [Array<Message>]
200
+ def initialize(messages: [])
201
+ super
202
+ end
203
+
204
+ # A copy in which every tool call has an answer, synthesizing
205
+ # {INTERRUPTED_RESULT} for any the recorded conversation left hanging —
206
+ # what a process killed mid-batch leaves behind.
207
+ #
208
+ # Providers reject an assistant +tool_use+ with no matching result, so
209
+ # this has to happen before the history goes back into a chat. It runs
210
+ # on resume, never at export: the record stays faithful to what
211
+ # happened, and the repair is applied on the way back in.
212
+ #
213
+ # Telling the model "you asked, it did not finish" beats dropping the
214
+ # assistant turn, which would erase that it ever decided to call the
215
+ # tool and leave it to re-derive the decision from nothing.
216
+ #
217
+ # @return [History] +self+ when nothing was dangling.
218
+ def repair_interrupted_tool_calls
219
+ out = []
220
+ pending = []
221
+ repaired = false
222
+ messages.each_with_index do |m, i|
223
+ # Hold synthetics until the batch's real results have gone by, so
224
+ # the answering run stays contiguous and in the order it happened.
225
+ unless pending.empty? || m.role == 'tool'
226
+ out.concat(pending)
227
+ pending = []
228
+ end
229
+ out << m
230
+ next unless m.tool_call?
231
+
232
+ answered = messages[(i + 1)..].take_while { |n| n.role == 'tool' }.map(&:tool_call_id)
233
+ pending = m.tool_calls.reject { |c| answered.include?(c.id) }.map do |call|
234
+ repaired = true
235
+ Message.new(id: History.mint_id, role: 'tool', tool_call_id: call.id,
236
+ content: INTERRUPTED_RESULT, summary: INTERRUPTED_SUMMARY)
237
+ end
238
+ end
239
+ out.concat(pending)
240
+ repaired ? with(messages: out) : self
241
+ end
242
+
243
+ # Observation synthesized for a tool call whose result never arrived.
244
+ INTERRUPTED_RESULT = '[Tool execution was interrupted]'
245
+ end
246
+ end
247
+ end
@@ -24,7 +24,7 @@ module Pikuri
24
24
  @events << event
25
25
  end
26
26
 
27
- # @return [String] short label for {Agent#to_s}
27
+ # @return [String] short label for {ListenerList#to_s}
28
28
  def to_s
29
29
  'InMemoryEventList'
30
30
  end