pikuri-core 0.0.7 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +17 -30
- data/lib/pikuri/agent/chat_transport.rb +168 -107
- data/lib/pikuri/agent/configurator.rb +194 -173
- data/lib/pikuri/agent/control/cancellable.rb +100 -70
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +107 -118
- data/lib/pikuri/agent/control.rb +13 -35
- data/lib/pikuri/agent/event.rb +144 -197
- data/lib/pikuri/agent/extension.rb +83 -95
- data/lib/pikuri/agent/history.rb +247 -0
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +169 -136
- data/lib/pikuri/agent/listener/token_log.rb +84 -157
- data/lib/pikuri/agent/listener.rb +24 -44
- data/lib/pikuri/agent/listener_list.rb +32 -47
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +1095 -577
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/bundler_env.rb +68 -0
- data/lib/pikuri/extractor/passthrough.rb +24 -31
- data/lib/pikuri/extractor.rb +125 -155
- data/lib/pikuri/file_type.rb +64 -136
- data/lib/pikuri/finalizers.rb +32 -47
- data/lib/pikuri/paths.rb +104 -13
- data/lib/pikuri/sanitizer.rb +46 -67
- data/lib/pikuri/subprocess.rb +86 -118
- data/lib/pikuri/testing.rb +369 -0
- data/lib/pikuri/tool/calculator.rb +168 -74
- data/lib/pikuri/tool/execute_context.rb +42 -0
- data/lib/pikuri/tool/parameters.rb +31 -29
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +248 -0
- data/lib/pikuri/tool.rb +416 -67
- data/lib/pikuri/trifecta/contribution.rb +43 -0
- data/lib/pikuri/trifecta/node.rb +47 -0
- data/lib/pikuri/trifecta/report.rb +228 -0
- data/lib/pikuri/trifecta.rb +126 -0
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +70 -92
- data/prompts/agent-loop.txt +5 -0
- data/prompts/pikuri-chat.txt +3 -12
- metadata +26 -72
- data/lib/pikuri/agent/context_window_detector.rb +0 -222
- data/lib/pikuri/agent/control/step_limit.rb +0 -111
- data/lib/pikuri/agent/extension_context.rb +0 -147
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
- data/lib/pikuri/agent/synthesizer.rb +0 -171
- data/lib/pikuri/extractor/html.rb +0 -303
- data/lib/pikuri/tool/fetch.rb +0 -172
- data/lib/pikuri/tool/scraper.rb +0 -186
- data/lib/pikuri/tool/search/brave.rb +0 -198
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
- data/lib/pikuri/tool/search/engines.rb +0 -186
- data/lib/pikuri/tool/search/exa.rb +0 -229
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
- data/lib/pikuri/tool/search/result.rb +0 -29
- data/lib/pikuri/tool/web_scrape.rb +0 -121
- data/lib/pikuri/tool/web_search.rb +0 -57
- data/lib/pikuri/url_cache.rb +0 -112
|
@@ -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
|