pikuri-core 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +16 -29
- data/lib/pikuri/agent/chat_transport.rb +114 -33
- data/lib/pikuri/agent/configurator.rb +191 -110
- data/lib/pikuri/agent/control/cancellable.rb +25 -16
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +87 -120
- data/lib/pikuri/agent/control.rb +9 -11
- data/lib/pikuri/agent/event.rb +73 -61
- data/lib/pikuri/agent/extension.rb +45 -81
- data/lib/pikuri/agent/history.rb +91 -497
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +115 -108
- data/lib/pikuri/agent/listener/token_log.rb +21 -55
- data/lib/pikuri/agent/listener.rb +4 -4
- data/lib/pikuri/agent/listener_list.rb +19 -13
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +624 -448
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/extractor/passthrough.rb +5 -2
- data/lib/pikuri/extractor.rb +43 -12
- data/lib/pikuri/file_type.rb +4 -4
- data/lib/pikuri/finalizers.rb +2 -2
- data/lib/pikuri/paths.rb +1 -1
- data/lib/pikuri/sanitizer.rb +4 -3
- data/lib/pikuri/subprocess.rb +17 -5
- data/lib/pikuri/testing.rb +122 -49
- data/lib/pikuri/tool/calculator.rb +134 -30
- data/lib/pikuri/tool/execute_context.rb +2 -2
- data/lib/pikuri/tool/parameters.rb +10 -0
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +52 -21
- data/lib/pikuri/tool.rb +298 -24
- data/lib/pikuri/trifecta/report.rb +28 -30
- data/lib/pikuri/trifecta.rb +1 -2
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +5 -11
- metadata +16 -73
- data/lib/pikuri/agent/context_window_detector.rb +0 -181
- data/lib/pikuri/agent/control/step_limit.rb +0 -95
- data/lib/pikuri/agent/extension_context.rb +0 -120
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
- data/lib/pikuri/agent/synthesizer.rb +0 -129
- data/lib/pikuri/extractor/html.rb +0 -256
- data/lib/pikuri/ruby_llm_patches.rb +0 -106
- data/lib/pikuri/tool/fetch.rb +0 -146
- data/lib/pikuri/tool/scraper.rb +0 -144
- data/lib/pikuri/tool/search/brave.rb +0 -170
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
- data/lib/pikuri/tool/search/engines.rb +0 -319
- data/lib/pikuri/tool/search/exa.rb +0 -195
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
- data/lib/pikuri/tool/search/result.rb +0 -24
- data/lib/pikuri/tool/web_scrape.rb +0 -105
- data/lib/pikuri/tool/web_search.rb +0 -133
- data/lib/pikuri/url_cache.rb +0 -96
data/lib/pikuri/agent/history.rb
CHANGED
|
@@ -1,68 +1,30 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
-
require 'json'
|
|
4
|
-
require 'digest'
|
|
5
|
-
require 'pathname'
|
|
6
3
|
require 'securerandom'
|
|
7
4
|
|
|
8
5
|
module Pikuri
|
|
9
6
|
class Agent
|
|
10
7
|
# A conversation, as a value — what {Agent#export_history} hands out and
|
|
11
|
-
#
|
|
8
|
+
# +Agent.new(history:)+ resumes:
|
|
12
9
|
#
|
|
13
|
-
#
|
|
14
|
-
# agent.
|
|
10
|
+
# history = agent.export_history
|
|
11
|
+
# agent.close
|
|
12
|
+
# Agent.new(transport: t, system_prompt: p, history: history)
|
|
15
13
|
#
|
|
16
|
-
#
|
|
17
|
-
#
|
|
18
|
-
#
|
|
19
|
-
# Both round-trip to the same value, which is the property that keeps them
|
|
20
|
-
# from drifting into two formats:
|
|
21
|
-
#
|
|
22
|
-
# History.load(dir) == History.parse(json) # => true
|
|
23
|
-
#
|
|
24
|
-
# The system prompt is *not* here — {Agent#clear_conversation} re-assembles
|
|
25
|
-
# it from every extension on load, so a resumed conversation gets today's
|
|
14
|
+
# The system prompt is *not* here — the resuming agent assembles its own
|
|
15
|
+
# from every extension, so a resumed conversation gets today's
|
|
26
16
|
# prompt (a re-read +MACHINE.md+, a fresh memory persona) rather than
|
|
27
17
|
# yesterday's.
|
|
28
18
|
#
|
|
29
|
-
#
|
|
30
|
-
#
|
|
31
|
-
# {parse}, {from_h} and {load} are the only ways to build one from
|
|
32
|
-
# untrusted bytes, and each raises {Error} rather than returning something
|
|
33
|
-
# half-built. There is deliberately no "accepts a String or a Hash or a
|
|
34
|
-
# History" convenience: one way in means one place validation could be
|
|
35
|
-
# skipped, i.e. none.
|
|
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.
|
|
36
21
|
#
|
|
37
22
|
# == Implementation details
|
|
38
23
|
#
|
|
39
|
-
# Attachment bytes are held **eagerly
|
|
40
|
-
#
|
|
41
|
-
#
|
|
42
|
-
|
|
43
|
-
# would reintroduce exactly the "the bytes changed since the model saw
|
|
44
|
-
# them" failure this format exists to avoid.
|
|
45
|
-
#
|
|
46
|
-
# The container is one JSON object, not JSONL. Should append ever be worth
|
|
47
|
-
# it, going to JSONL is a *sniff* (does the whole file parse as one
|
|
48
|
-
# object?) rather than a version bump — see +DECISIONS.md+ +D_history_container+.
|
|
49
|
-
class History < Data.define(:version, :messages)
|
|
50
|
-
# Bumped only for a change an old reader could not survive; an added
|
|
51
|
-
# optional key is not one (readers ignore unknown keys). A file claiming
|
|
52
|
-
# a higher version is refused, never best-effort loaded.
|
|
53
|
-
CURRENT_VERSION = 1
|
|
54
|
-
|
|
55
|
-
# Basename of the JSON written by {#save}, and read by {load}.
|
|
56
|
-
HISTORY_FILE = 'history.json'
|
|
57
|
-
|
|
58
|
-
# Subfolder {#save} writes attachment bytes into. Fixed, so
|
|
59
|
-
# "in the folder" is one comparison rather than a policy.
|
|
60
|
-
ATTACHMENTS_DIR = 'attachments'
|
|
61
|
-
|
|
62
|
-
# Message roles that may appear in an exported history. +:system+ cannot:
|
|
63
|
-
# the prompt is re-assembled, not replayed.
|
|
64
|
-
ROLES = %w[user assistant tool].freeze
|
|
65
|
-
|
|
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)
|
|
66
28
|
# What a +user+-role message *is*: something the human typed
|
|
67
29
|
# (+"user"+), or reference text pikuri injected on its own initiative —
|
|
68
30
|
# recalled memory, a host-loaded skill, a path-activation promotion
|
|
@@ -73,14 +35,26 @@ module Pikuri
|
|
|
73
35
|
# stale skill listing from something the human meant.
|
|
74
36
|
KINDS = %w[user reference].freeze
|
|
75
37
|
|
|
76
|
-
# Raised by every door in: a malformed record, a dangling tool result, an
|
|
77
|
-
# attachment outside the folder, a version from the future.
|
|
78
|
-
class Error < StandardError; end
|
|
79
|
-
|
|
80
38
|
# One tool call the assistant asked for. +id+ is the provider's own
|
|
81
39
|
# identifier and is load-bearing — the +tool+ message answering this call
|
|
82
40
|
# repeats it, and providers reject a pair that does not match.
|
|
83
|
-
|
|
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
|
|
84
58
|
|
|
85
59
|
# An assistant reasoning block, as the provider reported it.
|
|
86
60
|
#
|
|
@@ -90,73 +64,43 @@ module Pikuri
|
|
|
90
64
|
# OpenAI-compatible server +text+ is the reasoning itself and
|
|
91
65
|
# +signature+ is usually absent. So the whole block, never one field, is
|
|
92
66
|
# what {Agent} withholds from a model that did not produce it — see
|
|
93
|
-
# +
|
|
67
|
+
# +design/decisions.md+ +D_thinking_block_replay+.
|
|
94
68
|
Thinking = Data.define(:text, :signature)
|
|
95
69
|
|
|
96
70
|
# Per-message token usage, as the provider reported it. Carried so a
|
|
97
|
-
# host's context readout can be reseeded after a
|
|
71
|
+
# host's context readout can be reseeded after a resume — nothing on the
|
|
98
72
|
# wire needs it.
|
|
99
73
|
Tokens = Data.define(:input, :output, :cached, :cache_creation, :thinking)
|
|
100
74
|
|
|
101
|
-
# A file the model was shown — an image from +read+, a pasted document.
|
|
102
|
-
# Holds the actual bytes; {#stored_name} is what {History#save} calls it
|
|
103
|
-
# on disk.
|
|
104
|
-
Attachment = Data.define(:mime, :filename, :bytes) do
|
|
105
|
-
# @param mime [String] e.g. +"image/png"+
|
|
106
|
-
# @param filename [String] the name the model was shown
|
|
107
|
-
# @param bytes [String] the file's contents; re-tagged binary, since
|
|
108
|
-
# the same image arrives as UTF-8 from a source file and as
|
|
109
|
-
# ASCII-8BIT from base64, and two differently-tagged copies of one
|
|
110
|
-
# PNG are not +==+ — which would quietly break the round-trip
|
|
111
|
-
# property this whole type exists to hold.
|
|
112
|
-
def initialize(mime:, filename:, bytes:)
|
|
113
|
-
super(mime: mime, filename: filename, bytes: bytes.b)
|
|
114
|
-
end
|
|
115
|
-
|
|
116
|
-
# Content-addressed filename: the digest prefix makes it unique and
|
|
117
|
-
# self-verifying, so the same image read twice is stored once and a
|
|
118
|
-
# tampered file is caught at load.
|
|
119
|
-
#
|
|
120
|
-
# Attachment.new(mime: 'image/png', filename: 'shot.png', bytes: png).stored_name
|
|
121
|
-
# # => "3f9a1c8e2b-shot.png"
|
|
122
|
-
#
|
|
123
|
-
# @return [String] a bare basename, never a path.
|
|
124
|
-
def stored_name
|
|
125
|
-
ext = File.extname(filename.to_s)
|
|
126
|
-
stem = File.basename(filename.to_s, ext).gsub(/[^A-Za-z0-9._-]+/, '-')
|
|
127
|
-
stem = 'attachment' if stem.empty?
|
|
128
|
-
"#{digest[0, 10]}-#{stem}#{ext}"
|
|
129
|
-
end
|
|
130
|
-
|
|
131
|
-
# @return [String] SHA-256 of {#bytes}, hex.
|
|
132
|
-
def digest
|
|
133
|
-
Digest::SHA256.hexdigest(bytes)
|
|
134
|
-
end
|
|
135
|
-
end
|
|
136
|
-
|
|
137
75
|
# One message. +id+ and +kind+ are pikuri's own and never reach a
|
|
138
76
|
# provider; everything else is what the model saw.
|
|
139
77
|
#
|
|
140
78
|
# +content+ is always a String (empty on a pure tool-call turn, which is
|
|
141
79
|
# what ruby_llm stores); anything the model was *shown* beyond text is an
|
|
142
|
-
# {Attachment} in +attachments+.
|
|
80
|
+
# {Pikuri::Attachment} in +attachments+.
|
|
143
81
|
Message = Data.define(
|
|
144
82
|
:id, :role, :kind, :content, :attachments,
|
|
145
|
-
:tool_calls, :tool_call_id, :model_id, :thinking, :tokens
|
|
83
|
+
:tool_calls, :tool_call_id, :model_id, :thinking, :tokens, :summary
|
|
146
84
|
) do
|
|
147
85
|
# @param id [String] see {History.mint_id}
|
|
148
|
-
# @param role [String]
|
|
86
|
+
# @param role [String] +"user"+, +"assistant"+ or +"tool"+; never
|
|
87
|
+
# +"system"+ — the prompt is re-assembled, not replayed
|
|
149
88
|
# @param kind [String] one of {KINDS}; defaults to +"user"+
|
|
150
89
|
# @param content [String] the text the model saw; +""+ is legal
|
|
151
|
-
# @param attachments [Array<Attachment>]
|
|
90
|
+
# @param attachments [Array<Pikuri::Attachment>]
|
|
152
91
|
# @param tool_calls [Array<ToolCall>] empty unless the assistant asked
|
|
153
92
|
# for tools
|
|
154
93
|
# @param tool_call_id [String, nil] set exactly on a +tool+ message
|
|
155
94
|
# @param model_id [String, nil] which model produced this
|
|
156
95
|
# @param thinking [Thinking, nil]
|
|
157
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}.
|
|
158
102
|
def initialize(id:, role:, content:, kind: 'user', attachments: [], tool_calls: [],
|
|
159
|
-
tool_call_id: nil, model_id: nil, thinking: nil, tokens: nil)
|
|
103
|
+
tool_call_id: nil, model_id: nil, thinking: nil, tokens: nil, summary: nil)
|
|
160
104
|
super
|
|
161
105
|
end
|
|
162
106
|
|
|
@@ -165,42 +109,40 @@ module Pikuri
|
|
|
165
109
|
|
|
166
110
|
# Snapshot a live +RubyLLM::Message+. Attachment bytes are read *now*
|
|
167
111
|
# — the file a tool showed the model may be gone or changed by the
|
|
168
|
-
# time anyone
|
|
112
|
+
# time anyone resumes this.
|
|
169
113
|
#
|
|
170
114
|
# @param msg [RubyLLM::Message] must not be +role: :system+.
|
|
171
115
|
# @param id [String] see {History.mint_id}.
|
|
172
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.
|
|
173
121
|
# @return [Message]
|
|
174
|
-
def self.from_ruby_llm(msg, id:, kind: 'user')
|
|
175
|
-
|
|
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
|
|
176
125
|
new(
|
|
177
|
-
id: id, role: msg.role.to_s, kind: kind, content:
|
|
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+.
|
|
178
131
|
tool_calls: (msg.tool_calls || {}).values.map do |c|
|
|
179
|
-
|
|
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])
|
|
180
135
|
end,
|
|
181
|
-
tool_call_id: msg.
|
|
182
|
-
model_id: msg.
|
|
136
|
+
tool_call_id: msg.provider_call_id,
|
|
137
|
+
model_id: msg.model,
|
|
183
138
|
thinking: msg.thinking && Thinking.new(text: msg.thinking.text, signature: msg.thinking.signature),
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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?)
|
|
188
143
|
)
|
|
189
144
|
end
|
|
190
145
|
|
|
191
|
-
# @param content [String, RubyLLM::Content, nil]
|
|
192
|
-
# @return [Array(String, Array<Attachment>)]
|
|
193
|
-
def self.split_content(content)
|
|
194
|
-
return ['', []] if content.nil?
|
|
195
|
-
return [content, []] if content.is_a?(String)
|
|
196
|
-
return [content.to_s, []] unless content.respond_to?(:attachments)
|
|
197
|
-
|
|
198
|
-
[content.text.to_s, content.attachments.map do |a|
|
|
199
|
-
Attachment.new(mime: a.mime_type, filename: a.filename.to_s, bytes: a.content)
|
|
200
|
-
end]
|
|
201
|
-
end
|
|
202
|
-
private_class_method :split_content
|
|
203
|
-
|
|
204
146
|
# Rebuild the +RubyLLM::Message+ this was taken from.
|
|
205
147
|
#
|
|
206
148
|
# @param keep_thinking [Boolean] +false+ replays the turn without its
|
|
@@ -208,7 +150,7 @@ module Pikuri
|
|
|
208
150
|
# *other* model produced, since a thinking block lands in a slot the
|
|
209
151
|
# receiving model reads as its own scratchpad. Dropped from the
|
|
210
152
|
# *message*, not from the record: {Agent#export_history} still
|
|
211
|
-
#
|
|
153
|
+
# carries it. See +design/decisions.md+ +D_thinking_block_replay+.
|
|
212
154
|
# @return [RubyLLM::Message]
|
|
213
155
|
def to_ruby_llm(keep_thinking: true)
|
|
214
156
|
calls = tool_calls.to_h do |c|
|
|
@@ -217,365 +159,55 @@ module Pikuri
|
|
|
217
159
|
replayed = thinking if keep_thinking
|
|
218
160
|
RubyLLM::Message.new(
|
|
219
161
|
role: role.to_sym,
|
|
220
|
-
|
|
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),
|
|
221
167
|
tool_calls: calls.empty? ? nil : calls,
|
|
222
168
|
tool_call_id: tool_call_id,
|
|
223
|
-
|
|
169
|
+
model: model_id,
|
|
224
170
|
thinking: replayed && RubyLLM::Thinking.build(
|
|
225
171
|
text: replayed.text, signature: replayed.signature
|
|
226
172
|
),
|
|
227
|
-
tokens: tokens && RubyLLM::Tokens.
|
|
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)
|
|
228
175
|
)
|
|
229
176
|
end
|
|
230
|
-
|
|
231
|
-
private
|
|
232
|
-
|
|
233
|
-
def ruby_llm_content
|
|
234
|
-
return content if attachments.empty?
|
|
235
|
-
|
|
236
|
-
RubyLLM::Content.new(content).tap do |c|
|
|
237
|
-
attachments.each { |a| c.add_attachment(StringIO.new(a.bytes), filename: a.filename) }
|
|
238
|
-
end
|
|
239
|
-
end
|
|
240
177
|
end
|
|
241
178
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
raise Error, "history is not valid JSON: #{e.message}"
|
|
257
|
-
end
|
|
258
|
-
from_h(raw)
|
|
259
|
-
end
|
|
260
|
-
|
|
261
|
-
# Read a folder written by {#save}.
|
|
262
|
-
#
|
|
263
|
-
# @param dir [String, Pathname] the folder holding {HISTORY_FILE}.
|
|
264
|
-
# @return [History]
|
|
265
|
-
# @raise [Error] as {from_h}, plus a missing, unreadable, or
|
|
266
|
-
# digest-mismatched attachment.
|
|
267
|
-
def load(dir)
|
|
268
|
-
dir = Pathname(dir)
|
|
269
|
-
file = dir / HISTORY_FILE
|
|
270
|
-
raise Error, "no #{HISTORY_FILE} in #{dir}" unless file.file?
|
|
271
|
-
|
|
272
|
-
raw = begin
|
|
273
|
-
JSON.parse(file.read)
|
|
274
|
-
rescue JSON::ParserError => e
|
|
275
|
-
raise Error, "#{file} is not valid JSON: #{e.message}"
|
|
276
|
-
end
|
|
277
|
-
from_h(raw, dir: dir)
|
|
278
|
-
end
|
|
279
|
-
|
|
280
|
-
# Validate a plain Hash — the shared gate {parse} and {load} both run
|
|
281
|
-
# through, and the only place a record's shape is checked.
|
|
282
|
-
#
|
|
283
|
-
# Unknown *keys* are ignored, so a file written by a newer pikuri
|
|
284
|
-
# still loads; malformed *known* keys raise. That asymmetry is the
|
|
285
|
-
# whole forward-compatibility story, and it is why {CURRENT_VERSION}
|
|
286
|
-
# is expected to stay +1+.
|
|
287
|
-
#
|
|
288
|
-
# @param raw [Hash] parsed JSON, String keys.
|
|
289
|
-
# @param dir [Pathname, nil] folder to resolve file-backed attachments
|
|
290
|
-
# against; +nil+ refuses them.
|
|
291
|
-
# @return [History]
|
|
292
|
-
# @raise [Error] on a non-Hash, a version above {CURRENT_VERSION}, a
|
|
293
|
-
# message with a bad role/kind/id, a duplicate id, or a +tool+
|
|
294
|
-
# message whose +tool_call_id+ no preceding assistant message issued.
|
|
295
|
-
def from_h(raw, dir: nil)
|
|
296
|
-
raise Error, "expected a Hash, got #{raw.class}" unless raw.is_a?(Hash)
|
|
297
|
-
|
|
298
|
-
version = raw['version']
|
|
299
|
-
raise Error, "missing version (expected #{CURRENT_VERSION})" if version.nil?
|
|
300
|
-
if version.is_a?(Integer) && version > CURRENT_VERSION
|
|
301
|
-
raise Error, "history version #{version} is newer than this pikuri understands " \
|
|
302
|
-
"(#{CURRENT_VERSION}); upgrade pikuri to read it"
|
|
303
|
-
end
|
|
304
|
-
raise Error, "version must be #{CURRENT_VERSION}, got #{version.inspect}" unless version == CURRENT_VERSION
|
|
305
|
-
|
|
306
|
-
messages = raw['messages']
|
|
307
|
-
raise Error, "messages must be an Array, got #{messages.class}" unless messages.is_a?(Array)
|
|
308
|
-
|
|
309
|
-
built = messages.each_with_index.map { |m, i| message_from_h(m, i, dir) }
|
|
310
|
-
check_ids!(built)
|
|
311
|
-
check_tool_pairing!(built)
|
|
312
|
-
new(version: CURRENT_VERSION, messages: built)
|
|
313
|
-
end
|
|
314
|
-
|
|
315
|
-
# A fresh message id: lexicographically sortable, so ordering falls out
|
|
316
|
-
# of the id itself and a future tree format inherits identity for free.
|
|
317
|
-
#
|
|
318
|
-
# History.mint_id # => "0198c4f1a2b30001f3c9a2"
|
|
319
|
-
#
|
|
320
|
-
# Not a wire value — no provider is ever shown one.
|
|
321
|
-
#
|
|
322
|
-
# @return [String] 22 hex chars: 12 of millisecond timestamp, 4 of
|
|
323
|
-
# per-process counter (so two ids minted in one millisecond still
|
|
324
|
-
# sort), 6 random.
|
|
325
|
-
def mint_id
|
|
326
|
-
MINT_LOCK.synchronize do
|
|
327
|
-
@counter = ((@counter || -1) + 1) & 0xffff
|
|
328
|
-
format('%012x%04x%s', (Time.now.to_f * 1000).to_i, @counter, SecureRandom.hex(3))
|
|
329
|
-
end
|
|
330
|
-
end
|
|
331
|
-
|
|
332
|
-
private
|
|
333
|
-
|
|
334
|
-
def message_from_h(raw, index, dir)
|
|
335
|
-
raise Error, "message #{index}: expected a Hash, got #{raw.class}" unless raw.is_a?(Hash)
|
|
336
|
-
|
|
337
|
-
role = raw['role']
|
|
338
|
-
raise Error, "message #{index}: role must be one of #{ROLES.join('/')}, got #{role.inspect}" unless
|
|
339
|
-
ROLES.include?(role)
|
|
340
|
-
|
|
341
|
-
# Absent kind reads as "user": additive fields must not break an
|
|
342
|
-
# older file, and this is the only field with a sensible default.
|
|
343
|
-
kind = raw['kind'] || 'user'
|
|
344
|
-
raise Error, "message #{index}: kind must be one of #{KINDS.join('/')}, got #{kind.inspect}" unless
|
|
345
|
-
KINDS.include?(kind)
|
|
346
|
-
|
|
347
|
-
id = raw['id']
|
|
348
|
-
raise Error, "message #{index}: id must be a non-empty String, got #{id.inspect}" unless
|
|
349
|
-
id.is_a?(String) && !id.empty?
|
|
350
|
-
|
|
351
|
-
tool_call_id = raw['tool_call_id']
|
|
352
|
-
if role == 'tool' && !(tool_call_id.is_a?(String) && !tool_call_id.empty?)
|
|
353
|
-
raise Error, "message #{index} (#{id}): a tool message needs a tool_call_id, got #{tool_call_id.inspect}"
|
|
354
|
-
end
|
|
355
|
-
if role != 'tool' && !tool_call_id.nil?
|
|
356
|
-
raise Error, "message #{index} (#{id}): only a tool message may carry a tool_call_id"
|
|
357
|
-
end
|
|
358
|
-
|
|
359
|
-
Message.new(
|
|
360
|
-
id: id, role: role, kind: kind,
|
|
361
|
-
content: string_field(raw['content'], index, id, 'content'),
|
|
362
|
-
attachments: (raw['attachments'] || []).map { |a| attachment_from_h(a, index, id, dir) },
|
|
363
|
-
tool_calls: (raw['tool_calls'] || []).map { |t| tool_call_from_h(t, index, id) },
|
|
364
|
-
tool_call_id: tool_call_id,
|
|
365
|
-
model_id: raw['model_id'],
|
|
366
|
-
thinking: thinking_from_h(raw['thinking'], index, id),
|
|
367
|
-
tokens: tokens_from_h(raw['tokens'], index, id)
|
|
368
|
-
)
|
|
369
|
-
end
|
|
370
|
-
|
|
371
|
-
def string_field(value, index, id, name)
|
|
372
|
-
return value if value.is_a?(String)
|
|
373
|
-
return '' if value.nil?
|
|
374
|
-
|
|
375
|
-
raise Error, "message #{index} (#{id}): #{name} must be a String, got #{value.class}"
|
|
376
|
-
end
|
|
377
|
-
|
|
378
|
-
def tool_call_from_h(raw, index, id)
|
|
379
|
-
raise Error, "message #{index} (#{id}): each tool_call must be a Hash" unless raw.is_a?(Hash)
|
|
380
|
-
|
|
381
|
-
call_id = raw['id']
|
|
382
|
-
raise Error, "message #{index} (#{id}): a tool_call needs a non-empty id" unless
|
|
383
|
-
call_id.is_a?(String) && !call_id.empty?
|
|
384
|
-
raise Error, "message #{index} (#{id}): tool_call #{call_id} needs a name" unless raw['name'].is_a?(String)
|
|
385
|
-
|
|
386
|
-
args = raw['arguments'] || {}
|
|
387
|
-
raise Error, "message #{index} (#{id}): tool_call #{call_id} arguments must be a Hash" unless args.is_a?(Hash)
|
|
388
|
-
|
|
389
|
-
ToolCall.new(id: call_id, name: raw['name'], arguments: args)
|
|
390
|
-
end
|
|
391
|
-
|
|
392
|
-
def thinking_from_h(raw, index, id)
|
|
393
|
-
return nil if raw.nil?
|
|
394
|
-
raise Error, "message #{index} (#{id}): thinking must be a Hash" unless raw.is_a?(Hash)
|
|
395
|
-
|
|
396
|
-
Thinking.new(text: raw['text'], signature: raw['signature'])
|
|
397
|
-
end
|
|
398
|
-
|
|
399
|
-
def tokens_from_h(raw, index, id)
|
|
400
|
-
return nil if raw.nil?
|
|
401
|
-
raise Error, "message #{index} (#{id}): tokens must be a Hash" unless raw.is_a?(Hash)
|
|
402
|
-
|
|
403
|
-
Tokens.new(
|
|
404
|
-
input: raw['input'], output: raw['output'], cached: raw['cached'],
|
|
405
|
-
cache_creation: raw['cache_creation'], thinking: raw['thinking']
|
|
406
|
-
)
|
|
407
|
-
end
|
|
408
|
-
|
|
409
|
-
def attachment_from_h(raw, index, id, dir)
|
|
410
|
-
raise Error, "message #{index} (#{id}): each attachment must be a Hash" unless raw.is_a?(Hash)
|
|
411
|
-
|
|
412
|
-
filename = raw['filename'].to_s
|
|
413
|
-
bytes =
|
|
414
|
-
case raw['kind']
|
|
415
|
-
when 'inline' then decode_inline(raw['bytes'], index, id)
|
|
416
|
-
when 'file' then read_confined(dir, raw['file'], index, id)
|
|
417
|
-
else raise Error, "message #{index} (#{id}): attachment kind must be inline or file, " \
|
|
418
|
-
"got #{raw['kind'].inspect}"
|
|
419
|
-
end
|
|
420
|
-
|
|
421
|
-
Attachment.new(mime: raw['mime'], filename: filename, bytes: bytes)
|
|
422
|
-
end
|
|
423
|
-
|
|
424
|
-
def decode_inline(data, index, id)
|
|
425
|
-
raise Error, "message #{index} (#{id}): inline attachment needs base64 bytes" unless data.is_a?(String)
|
|
426
|
-
|
|
427
|
-
data.unpack1('m0')
|
|
428
|
-
rescue ArgumentError => e
|
|
429
|
-
raise Error, "message #{index} (#{id}): attachment base64 is malformed: #{e.message}"
|
|
430
|
-
end
|
|
431
|
-
|
|
432
|
-
# Read one attachment, refusing anything that is not a plain file
|
|
433
|
-
# directly inside +dir/attachments+.
|
|
434
|
-
#
|
|
435
|
-
# The comparison is on the **resolved** path, not the string: a file
|
|
436
|
-
# sitting in the folder may itself be a symlink to +~/.ssh/id_ed25519+,
|
|
437
|
-
# which every textual check passes. That is the case this method
|
|
438
|
-
# exists for.
|
|
439
|
-
def read_confined(dir, name, index, id)
|
|
440
|
-
where = "message #{index} (#{id})"
|
|
441
|
-
if dir.nil?
|
|
442
|
-
raise Error, "#{where}: this history references the external attachment #{name.inspect}; " \
|
|
443
|
-
'use History.load(dir) rather than History.parse'
|
|
444
|
-
end
|
|
445
|
-
raise Error, "#{where}: attachment file must be a String" unless name.is_a?(String)
|
|
446
|
-
unless !name.empty? && name == File.basename(name) && !name.start_with?('.')
|
|
447
|
-
raise Error, "#{where}: attachment file #{name.inspect} must be a bare filename"
|
|
448
|
-
end
|
|
449
|
-
|
|
450
|
-
root = dir / ATTACHMENTS_DIR
|
|
451
|
-
path = root / name
|
|
452
|
-
raise Error, "#{where}: attachment #{name.inspect} is missing from #{root}" unless path.file?
|
|
453
|
-
|
|
454
|
-
real = path.realpath
|
|
455
|
-
unless real.dirname == root.realpath
|
|
456
|
-
raise Error, "#{where}: attachment #{name.inspect} resolves to #{real}, outside #{root}"
|
|
457
|
-
end
|
|
458
|
-
|
|
459
|
-
bytes = real.binread
|
|
460
|
-
expected = name[/\A[0-9a-f]{10}/]
|
|
461
|
-
if expected && !Digest::SHA256.hexdigest(bytes).start_with?(expected)
|
|
462
|
-
raise Error, "#{where}: attachment #{name.inspect} does not match its content digest"
|
|
463
|
-
end
|
|
464
|
-
|
|
465
|
-
bytes
|
|
466
|
-
end
|
|
467
|
-
|
|
468
|
-
def check_ids!(messages)
|
|
469
|
-
seen = {}
|
|
470
|
-
messages.each_with_index do |m, i|
|
|
471
|
-
if (first = seen[m.id])
|
|
472
|
-
raise Error, "message #{i}: duplicate id #{m.id} (already used by message #{first})"
|
|
473
|
-
end
|
|
474
|
-
|
|
475
|
-
seen[m.id] = i
|
|
476
|
-
end
|
|
477
|
-
end
|
|
478
|
-
|
|
479
|
-
# Refuse a tool result nothing asked for, and one answered twice.
|
|
480
|
-
#
|
|
481
|
-
# The mirror case — a call with *no* result — is deliberately legal
|
|
482
|
-
# here: that is what a process killed mid-batch leaves behind, and
|
|
483
|
-
# {Agent#load_history!} repairs it by synthesizing an interrupted
|
|
484
|
-
# result. Refusing it would make the crash case the one thing that
|
|
485
|
-
# cannot be loaded.
|
|
486
|
-
def check_tool_pairing!(messages)
|
|
487
|
-
issued = {}
|
|
488
|
-
answered = {}
|
|
489
|
-
messages.each_with_index do |m, i|
|
|
490
|
-
m.tool_calls.each { |c| issued[c.id] = i }
|
|
491
|
-
next unless m.role == 'tool'
|
|
492
|
-
|
|
493
|
-
unless issued.key?(m.tool_call_id)
|
|
494
|
-
raise Error, "message #{i} (#{m.id}): tool_call_id #{m.tool_call_id} " \
|
|
495
|
-
'was never issued by a preceding assistant message'
|
|
496
|
-
end
|
|
497
|
-
if (prev = answered[m.tool_call_id])
|
|
498
|
-
raise Error, "message #{i} (#{m.id}): tool_call_id #{m.tool_call_id} " \
|
|
499
|
-
"was already answered by message #{prev}"
|
|
500
|
-
end
|
|
501
|
-
|
|
502
|
-
answered[m.tool_call_id] = i
|
|
503
|
-
end
|
|
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))
|
|
504
193
|
end
|
|
505
194
|
end
|
|
506
195
|
|
|
507
196
|
MINT_LOCK = Mutex.new
|
|
508
197
|
private_constant :MINT_LOCK
|
|
509
198
|
|
|
510
|
-
# @param version [Integer] must be {CURRENT_VERSION}; defaulted so
|
|
511
|
-
# callers building one in Ruby never restate it.
|
|
512
199
|
# @param messages [Array<Message>]
|
|
513
|
-
def initialize(
|
|
200
|
+
def initialize(messages: [])
|
|
514
201
|
super
|
|
515
202
|
end
|
|
516
203
|
|
|
517
|
-
# The self-contained Hash: attachments inline, as base64.
|
|
518
|
-
#
|
|
519
|
-
# @param inline_attachments [Boolean] +false+ renders each attachment as
|
|
520
|
-
# a reference to its {Attachment#stored_name}, which only {#save}
|
|
521
|
-
# wants — the bytes then live in the folder, not the Hash.
|
|
522
|
-
# @return [Hash{String => Object}] JSON-safe, String keys.
|
|
523
|
-
def to_h(inline_attachments: true)
|
|
524
|
-
{
|
|
525
|
-
'version' => version,
|
|
526
|
-
'messages' => messages.map { |m| message_to_h(m, inline_attachments) }
|
|
527
|
-
}
|
|
528
|
-
end
|
|
529
|
-
|
|
530
|
-
# @return [String] pretty-printed {#to_h}, so a stored conversation stays
|
|
531
|
-
# readable and diffs a turn at a time.
|
|
532
|
-
def to_json(*_args)
|
|
533
|
-
JSON.pretty_generate(to_h)
|
|
534
|
-
end
|
|
535
|
-
|
|
536
|
-
# Write +dir/history.json+ plus +dir/attachments/+, creating the folder if
|
|
537
|
-
# needed.
|
|
538
|
-
#
|
|
539
|
-
# agent.export_history.save('~/conversations/2026-08-27-abc')
|
|
540
|
-
#
|
|
541
|
-
# Attachments are written **first**: +history.json+ is the commit point,
|
|
542
|
-
# so an interrupted save leaves unreferenced bytes (harmless) rather than
|
|
543
|
-
# a reference to bytes that are not there.
|
|
544
|
-
#
|
|
545
|
-
# Never deletes. An attachment the history no longer references simply
|
|
546
|
-
# stays — pikuri writes into this folder but does not own everything in
|
|
547
|
-
# it, and removing a file a human put there is a worse failure than an
|
|
548
|
-
# orphan. Re-saving is idempotent: a content-addressed name that already
|
|
549
|
-
# exists is skipped after one +stat+, so cost tracks the history rather
|
|
550
|
-
# than the folder.
|
|
551
|
-
#
|
|
552
|
-
# @param dir [String, Pathname] destination; created if absent.
|
|
553
|
-
# @return [Pathname] +dir+, so a caller can chain.
|
|
554
|
-
def save(dir)
|
|
555
|
-
dir = Pathname(dir).expand_path
|
|
556
|
-
attachments = messages.flat_map(&:attachments)
|
|
557
|
-
|
|
558
|
-
unless attachments.empty?
|
|
559
|
-
root = dir / ATTACHMENTS_DIR
|
|
560
|
-
root.mkpath
|
|
561
|
-
attachments.each do |a|
|
|
562
|
-
path = root / a.stored_name
|
|
563
|
-
atomic_write(path, a.bytes) unless path.exist?
|
|
564
|
-
end
|
|
565
|
-
end
|
|
566
|
-
|
|
567
|
-
dir.mkpath
|
|
568
|
-
atomic_write(dir / HISTORY_FILE, JSON.pretty_generate(to_h(inline_attachments: false)))
|
|
569
|
-
dir
|
|
570
|
-
end
|
|
571
|
-
|
|
572
204
|
# A copy in which every tool call has an answer, synthesizing
|
|
573
205
|
# {INTERRUPTED_RESULT} for any the recorded conversation left hanging —
|
|
574
206
|
# what a process killed mid-batch leaves behind.
|
|
575
207
|
#
|
|
576
208
|
# Providers reject an assistant +tool_use+ with no matching result, so
|
|
577
209
|
# this has to happen before the history goes back into a chat. It runs
|
|
578
|
-
#
|
|
210
|
+
# on resume, never at export: the record stays faithful to what
|
|
579
211
|
# happened, and the repair is applied on the way back in.
|
|
580
212
|
#
|
|
581
213
|
# Telling the model "you asked, it did not finish" beats dropping the
|
|
@@ -600,7 +232,8 @@ module Pikuri
|
|
|
600
232
|
answered = messages[(i + 1)..].take_while { |n| n.role == 'tool' }.map(&:tool_call_id)
|
|
601
233
|
pending = m.tool_calls.reject { |c| answered.include?(c.id) }.map do |call|
|
|
602
234
|
repaired = true
|
|
603
|
-
Message.new(id: History.mint_id, role: 'tool', tool_call_id: call.id,
|
|
235
|
+
Message.new(id: History.mint_id, role: 'tool', tool_call_id: call.id,
|
|
236
|
+
content: INTERRUPTED_RESULT, summary: INTERRUPTED_SUMMARY)
|
|
604
237
|
end
|
|
605
238
|
end
|
|
606
239
|
out.concat(pending)
|
|
@@ -609,45 +242,6 @@ module Pikuri
|
|
|
609
242
|
|
|
610
243
|
# Observation synthesized for a tool call whose result never arrived.
|
|
611
244
|
INTERRUPTED_RESULT = '[Tool execution was interrupted]'
|
|
612
|
-
|
|
613
|
-
private
|
|
614
|
-
|
|
615
|
-
def message_to_h(msg, inline)
|
|
616
|
-
h = {
|
|
617
|
-
'id' => msg.id,
|
|
618
|
-
'role' => msg.role,
|
|
619
|
-
'kind' => msg.kind,
|
|
620
|
-
'content' => msg.content
|
|
621
|
-
}
|
|
622
|
-
h['attachments'] = msg.attachments.map { |a| attachment_to_h(a, inline) } unless msg.attachments.empty?
|
|
623
|
-
h['tool_calls'] = msg.tool_calls.map { |c| c.to_h.transform_keys(&:to_s) } unless msg.tool_calls.empty?
|
|
624
|
-
h['tool_call_id'] = msg.tool_call_id if msg.tool_call_id
|
|
625
|
-
h['model_id'] = msg.model_id if msg.model_id
|
|
626
|
-
h['thinking'] = compact_h(msg.thinking) if msg.thinking
|
|
627
|
-
h['tokens'] = compact_h(msg.tokens) if msg.tokens
|
|
628
|
-
h
|
|
629
|
-
end
|
|
630
|
-
|
|
631
|
-
def attachment_to_h(att, inline)
|
|
632
|
-
base = { 'mime' => att.mime, 'filename' => att.filename }
|
|
633
|
-
if inline
|
|
634
|
-
base.merge('kind' => 'inline', 'bytes' => [att.bytes].pack('m0'))
|
|
635
|
-
else
|
|
636
|
-
base.merge('kind' => 'file', 'file' => att.stored_name)
|
|
637
|
-
end
|
|
638
|
-
end
|
|
639
|
-
|
|
640
|
-
def compact_h(value)
|
|
641
|
-
value.to_h.compact.transform_keys(&:to_s)
|
|
642
|
-
end
|
|
643
|
-
|
|
644
|
-
# Write via a sibling temp file and rename, so a reader never sees a
|
|
645
|
-
# half-written file and a crash cannot leave one.
|
|
646
|
-
def atomic_write(path, content)
|
|
647
|
-
tmp = path.dirname / ".#{path.basename}.tmp"
|
|
648
|
-
tmp.binwrite(content)
|
|
649
|
-
tmp.rename(path.to_s)
|
|
650
|
-
end
|
|
651
245
|
end
|
|
652
246
|
end
|
|
653
247
|
end
|