@yahyahammad/venastine 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.
- package/README.md +19 -2
- package/agents/subagent_tool.py +49 -26
- package/agents/tui_commands.py +24 -9
- package/core/agent_activity.py +118 -0
- package/core/client.py +11 -0
- package/core/compaction.py +971 -959
- package/core/loop.py +1490 -1353
- package/core/memory.py +370 -370
- package/core/replay.py +183 -167
- package/main.py +3 -1
- package/memories/tui_commands.py +14 -2
- package/package.json +73 -73
- package/pyproject.toml +100 -100
- package/safety/policy_enforcement.py +746 -682
- package/storage.py +1005 -1005
- package/tools/registry.py +29 -1
- package/tui/app.py +707 -30
- package/tui/app.tcss +106 -8
- package/tui/commands.py +170 -61
- package/tui/history.py +128 -0
- package/tui/markdown.py +1279 -0
- package/tui/meters.py +268 -0
- package/tui/themes.py +559 -366
- package/tui/widgets.py +1168 -75
package/core/memory.py
CHANGED
|
@@ -1,370 +1,370 @@
|
|
|
1
|
-
"""
|
|
2
|
-
core/memory.py
|
|
3
|
-
|
|
4
|
-
Keeps the running message history for one agent conversation, backed by
|
|
5
|
-
real persistence. Stores history in a PROVIDER-NEUTRAL shape -- not
|
|
6
|
-
Anthropic's content-block format, not OpenAI's tool_calls format -- so
|
|
7
|
-
this file has no idea which provider is in use. core/client.py is the
|
|
8
|
-
only place that translates this neutral shape into whatever wire format
|
|
9
|
-
a specific provider's API actually wants, the same way it already
|
|
10
|
-
translates tool schemas per provider.
|
|
11
|
-
|
|
12
|
-
Neutral shapes stored in self._messages:
|
|
13
|
-
user: {"role": "user", "content": "text"}
|
|
14
|
-
assistant: {"role": "assistant", "text": "...", "tool_calls": [
|
|
15
|
-
{"id": "...", "name": "...", "input": {...}}, ...]}
|
|
16
|
-
tool: {"role": "tool", "tool_call_id": "...", "content": "..."}
|
|
17
|
-
(one entry per individual tool result)
|
|
18
|
-
|
|
19
|
-
PERSISTENCE, AND WHY THERE'S NO NORMALIZATION STEP HERE:
|
|
20
|
-
Each add_* method passes storage.save_message() only the PAYLOAD that
|
|
21
|
-
role actually needs -- plain text for user, {"text", "tool_calls"} for
|
|
22
|
-
assistant, a plain result string for tool -- never the whole neutral
|
|
23
|
-
entry dict, which would redundantly re-wrap "role" (and, for tool rows,
|
|
24
|
-
"tool_call_id") a second time inside the persisted content itself.
|
|
25
|
-
storage.get_session_history() reconstructs the exact neutral shape
|
|
26
|
-
above directly, per msg.role, so what comes back on resume is
|
|
27
|
-
identical to what a fresh add_* call would have produced -- no
|
|
28
|
-
post-hoc reshaping step is needed here, for this role or any future one.
|
|
29
|
-
|
|
30
|
-
An earlier version of this file had exactly the bug this design avoids:
|
|
31
|
-
add_assistant_message's persisted shape was nested and lossy on
|
|
32
|
-
resume, a read-side "_normalize_resumed_history()" function was added
|
|
33
|
-
to fix it -- but only for role == "assistant". add_tool_result had the
|
|
34
|
-
identical root cause (same "pass the whole entry dict" pattern) and was
|
|
35
|
-
never touched, because the fix lived one layer above where the actual
|
|
36
|
-
divergence was produced. Fixing what gets WRITTEN, once, here, closes
|
|
37
|
-
this for every role without a matching special case at every point
|
|
38
|
-
it's read back. See tests/test_memory_write_through.py for the
|
|
39
|
-
regression tests (now covering the tool row's `content`, not just its
|
|
40
|
-
`role`/`tool_call_id`, which is exactly the assertion that was missing
|
|
41
|
-
before).
|
|
42
|
-
"""
|
|
43
|
-
|
|
44
|
-
from typing import Optional
|
|
45
|
-
from uuid import UUID
|
|
46
|
-
|
|
47
|
-
from storage import (
|
|
48
|
-
create_thread, get_thread, save_message, get_session_history,
|
|
49
|
-
update_thread_extra, latest_checkpoint, pinned_through,
|
|
50
|
-
message_ids_from, set_pinned, turn_start_ids, THREAD_KIND_CHAT,
|
|
51
|
-
)
|
|
52
|
-
|
|
53
|
-
# ROADMAP_v2 §21 (M8). How a compaction summary is introduced to the model.
|
|
54
|
-
#
|
|
55
|
-
# The neutral shape has three roles -- user, assistant, tool -- and no
|
|
56
|
-
# "system" among them, because the system prompt travels separately. A
|
|
57
|
-
# leading USER message is therefore the only form all three providers
|
|
58
|
-
# accept in the message list, and it is where a conversation naturally
|
|
59
|
-
# starts anyway.
|
|
60
|
-
#
|
|
61
|
-
# It is NEVER persisted as a MessageLog row. Doing so would put derived
|
|
62
|
-
# content in an append-only archive whose whole value is being original,
|
|
63
|
-
# and the next compaction would then summarize the previous summary as if
|
|
64
|
-
# it were something the user said -- chaining by accident, on a code path
|
|
65
|
-
# that means to re-derive.
|
|
66
|
-
SUMMARY_PREFIX = (
|
|
67
|
-
"[Summary of the earlier part of this conversation, compacted to save "
|
|
68
|
-
"context. The full history is preserved and unedited; this is what is "
|
|
69
|
-
"being shown to you now.]\n\n"
|
|
70
|
-
)
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
class ConversationMemory:
|
|
74
|
-
def __init__(self, thread_id: Optional[UUID] = None,
|
|
75
|
-
kind: str = THREAD_KIND_CHAT) -> None:
|
|
76
|
-
"""`kind` (§27 T1) says what a NEW thread is, and is forwarded to
|
|
77
|
-
storage.create_thread and nowhere else.
|
|
78
|
-
|
|
79
|
-
This class does not learn what a kind means, store it, or read it
|
|
80
|
-
back. It owns active in-run state and must stay unaware of what
|
|
81
|
-
data exists -- that boundary is storage.py's. Ignored when
|
|
82
|
-
`thread_id` is given, because resuming does not reclassify: a
|
|
83
|
-
thread's kind was decided when it was created.
|
|
84
|
-
"""
|
|
85
|
-
# Session-scoped billing (#4): zero on EVERY construction, fresh or
|
|
86
|
-
# resumed -- see record_billed for why this one is deliberately not
|
|
87
|
-
# extra_data like its neighbour.
|
|
88
|
-
self.billed_tokens = 0
|
|
89
|
-
if thread_id is None:
|
|
90
|
-
self.thread_id = create_thread(kind=kind)
|
|
91
|
-
self._messages: list[dict] = []
|
|
92
|
-
self._extra: dict = {}
|
|
93
|
-
self._kind = kind
|
|
94
|
-
else:
|
|
95
|
-
thread = get_thread(thread_id)
|
|
96
|
-
if thread is None:
|
|
97
|
-
raise ValueError(f"No conversation thread found with id {thread_id}")
|
|
98
|
-
self.thread_id = thread_id
|
|
99
|
-
self._extra = dict(thread.get("extra_data") or {})
|
|
100
|
-
self._messages = self._derived_view()
|
|
101
|
-
# The kind fallback (missing column on a database whose ALTER
|
|
102
|
-
# has not run) lives inside get_thread's copy now; resuming is
|
|
103
|
-
# not reclassifying, so the stored kind is simply reported.
|
|
104
|
-
self._kind = thread.get("kind") or THREAD_KIND_CHAT
|
|
105
|
-
|
|
106
|
-
@property
|
|
107
|
-
def kind(self) -> str:
|
|
108
|
-
"""What this thread IS (§27 T1): "chat", "research_pass" or
|
|
109
|
-
"subagent".
|
|
110
|
-
|
|
111
|
-
A deliberate boundary bend, recorded rather than slipped in
|
|
112
|
-
(#43, batch 16). §27 says this class "learns nothing from kind" --
|
|
113
|
-
it forwards the kwarg at creation and ignores it on resume --
|
|
114
|
-
because kind SEMANTICS are storage's to store and the loop's to
|
|
115
|
-
decide. That still holds: nothing here branches on the value.
|
|
116
|
-
What changed is that the loop can now ASK, because batch 16 gave
|
|
117
|
-
it a decision to make from the answer -- which compaction mode a
|
|
118
|
-
re-entered thread runs under derives from what the thread IS
|
|
119
|
-
(research_pass and subagent threads get M6's backstop wherever
|
|
120
|
-
they are resumed), and the memory is the object holding the
|
|
121
|
-
thread. Reporting a stored fact is not interpreting it.
|
|
122
|
-
"""
|
|
123
|
-
return self._kind
|
|
124
|
-
|
|
125
|
-
# -- the derived view (§21) --------------------------------------------
|
|
126
|
-
|
|
127
|
-
def _derived_view(self) -> list[dict]:
|
|
128
|
-
"""What the agent sees this turn: a view computed over the archive,
|
|
129
|
-
not a second copy of it.
|
|
130
|
-
|
|
131
|
-
Three parts, in order:
|
|
132
|
-
1. the latest checkpoint's summary, as a leading user message
|
|
133
|
-
2. pinned rows from inside the span that summary covers (M9),
|
|
134
|
-
verbatim -- the summary skipped them, and one watermark
|
|
135
|
-
cannot say "everything through K except these"
|
|
136
|
-
3. every archive row after the watermark, verbatim
|
|
137
|
-
|
|
138
|
-
A thread that has never been compacted has no checkpoint, so this
|
|
139
|
-
returns exactly what get_session_history() always returned. That
|
|
140
|
-
equivalence is what keeps every pre-§21 caller untouched until the
|
|
141
|
-
trigger first fires on a thread, and it is asserted directly.
|
|
142
|
-
"""
|
|
143
|
-
checkpoint = latest_checkpoint(self.thread_id)
|
|
144
|
-
if checkpoint is None:
|
|
145
|
-
return get_session_history(self.thread_id)
|
|
146
|
-
|
|
147
|
-
watermark = checkpoint["covers_up_to_message_id"]
|
|
148
|
-
summary = {
|
|
149
|
-
"role": "user",
|
|
150
|
-
"content": f"{SUMMARY_PREFIX}{checkpoint['summary_text']}",
|
|
151
|
-
}
|
|
152
|
-
return (
|
|
153
|
-
[summary]
|
|
154
|
-
+ pinned_through(self.thread_id, watermark)
|
|
155
|
-
+ get_session_history(self.thread_id, after_message_id=watermark)
|
|
156
|
-
)
|
|
157
|
-
|
|
158
|
-
def apply_checkpoint(self) -> None:
|
|
159
|
-
"""Rebuild the in-memory view after a compaction was recorded.
|
|
160
|
-
|
|
161
|
-
Deliberately re-reads rather than splicing the summary into the
|
|
162
|
-
list it already holds. The assembly rules (a leading summary,
|
|
163
|
-
pinned re-inclusion, the tail) then live in exactly one place, so
|
|
164
|
-
a mid-run compaction and a resumed thread cannot produce different
|
|
165
|
-
views of the same checkpoint -- which is the divergence a second
|
|
166
|
-
assembly path would eventually introduce.
|
|
167
|
-
"""
|
|
168
|
-
self._messages = self._derived_view()
|
|
169
|
-
|
|
170
|
-
# -- measured context size (§21) ----------------------------------------
|
|
171
|
-
|
|
172
|
-
@property
|
|
173
|
-
def last_input_tokens(self) -> int:
|
|
174
|
-
"""The provider's own count of everything it was last sent on this
|
|
175
|
-
thread, or 0 if it has never been measured.
|
|
176
|
-
|
|
177
|
-
This is what §21's compaction trigger reads. It is exact and it
|
|
178
|
-
comes from the provider rather than from a local tokenizer that
|
|
179
|
-
would have to be right per model -- but it is retrospective, which
|
|
180
|
-
is why the trigger is evaluated after a response and acts before
|
|
181
|
-
the next call.
|
|
182
|
-
|
|
183
|
-
PERSISTED, via the same extra_data write-through goal mode uses.
|
|
184
|
-
§21 says a resumed thread needs a rough character estimate before
|
|
185
|
-
its first call because nothing has been measured yet; carrying the
|
|
186
|
-
last real measurement across the process boundary means the
|
|
187
|
-
estimate is only ever needed for a thread written before this
|
|
188
|
-
section existed.
|
|
189
|
-
"""
|
|
190
|
-
return int(self._extra.get("last_input_tokens") or 0)
|
|
191
|
-
|
|
192
|
-
def record_input_tokens(self, tokens: int) -> None:
|
|
193
|
-
"""Store the measurement from the call that just returned. Ignores
|
|
194
|
-
a zero, which is what D21's raise exists to prevent reaching here
|
|
195
|
-
and what a provider reporting no usage would otherwise write over
|
|
196
|
-
a real earlier number."""
|
|
197
|
-
if tokens:
|
|
198
|
-
self.set_extra("last_input_tokens", int(tokens))
|
|
199
|
-
|
|
200
|
-
# -- session billing (#4) -------------------------------------------------
|
|
201
|
-
|
|
202
|
-
def record_billed(self, tokens: int) -> None:
|
|
203
|
-
"""Accumulate this thread's billed input+output for the SESSION.
|
|
204
|
-
|
|
205
|
-
Deliberately NOT persisted, unlike last_input_tokens beside it:
|
|
206
|
-
the scope the TUI's usage line shows is THREAD-SINCE-RESUME. A
|
|
207
|
-
lifetime total would need a schema column to mean anything (a
|
|
208
|
-
resumed thread would silently restart at zero anyway, reading as
|
|
209
|
-
a reset), and #4's figure exists for relative reasoning about
|
|
210
|
-
this session, not as a ledger.
|
|
211
|
-
"""
|
|
212
|
-
self.billed_tokens += int(tokens or 0)
|
|
213
|
-
|
|
214
|
-
def completed_turns(self) -> int:
|
|
215
|
-
"""How many turns of this thread are already finished (§21 M5/M11).
|
|
216
|
-
|
|
217
|
-
COUNTED FROM THE ARCHIVE, never from `self._messages`. M8 makes a
|
|
218
|
-
checkpoint summary a `role: "user"` message, so a compacted view
|
|
219
|
-
holds one user message that is not a turn -- and this number is
|
|
220
|
-
compared against archive-space turn indices in
|
|
221
|
-
compaction.compactable_span(). Counting the view was §21a's shipped
|
|
222
|
-
defect: the floor came out several turns too low, the computed
|
|
223
|
-
watermark went BACKWARDS, and the second automatic compaction of a
|
|
224
|
-
thread un-compacted it. See tests/test_storage_e2e.py.
|
|
225
|
-
|
|
226
|
-
Lives here rather than in core/loop.py because this is the file
|
|
227
|
-
that owns the thread's persistence -- the loop imports no storage
|
|
228
|
-
at all, and should not start.
|
|
229
|
-
|
|
230
|
-
Called before the first model call of a turn, and every wrapper
|
|
231
|
-
adds the user message first, so the turn about to run is the last
|
|
232
|
-
entry and is excluded. That off-by-one IS the structural floor:
|
|
233
|
-
everything from this index on is the current turn and can never be
|
|
234
|
-
folded.
|
|
235
|
-
|
|
236
|
-
Archive-space also makes the value STABLE for a whole turn. The
|
|
237
|
-
archive never changes under compaction, so a count taken at the top
|
|
238
|
-
of a turn stays correct after a mid-turn compaction rebuilds the
|
|
239
|
-
view; the view-based version silently went stale at exactly that
|
|
240
|
-
point.
|
|
241
|
-
"""
|
|
242
|
-
return len(turn_start_ids(self.thread_id)) - 1
|
|
243
|
-
|
|
244
|
-
# -- pinning (§21) ------------------------------------------------------
|
|
245
|
-
|
|
246
|
-
def pin_last(self, turns: int = 1) -> int:
|
|
247
|
-
"""Mark the last `turns` turns compaction-exempt. Returns how many
|
|
248
|
-
rows were newly pinned.
|
|
249
|
-
|
|
250
|
-
ORDINAL, not an id. §21 keeps MessageLog.id out of the neutral
|
|
251
|
-
shape -- the model never sees one and so cannot name one -- and
|
|
252
|
-
adding it would put a persistence concept into the provider-neutral
|
|
253
|
-
contract the whole memory design rests on, with three translation
|
|
254
|
-
branches then needing to strip it before the wire. "Pin the last N
|
|
255
|
-
turns" needs no id and is how the tool would actually be used.
|
|
256
|
-
|
|
257
|
-
A turn starts at a user message and runs to just before the next
|
|
258
|
-
one, so pinning a turn keeps the question together with its answer
|
|
259
|
-
and any tool results between them. Asking for more turns than the
|
|
260
|
-
thread has pins the whole thread rather than erroring: the intent
|
|
261
|
-
("keep this conversation") is unambiguous and there is nothing to
|
|
262
|
-
clarify.
|
|
263
|
-
"""
|
|
264
|
-
if turns < 1:
|
|
265
|
-
return 0
|
|
266
|
-
starts = turn_start_ids(self.thread_id)
|
|
267
|
-
if not starts:
|
|
268
|
-
return 0
|
|
269
|
-
first = starts[max(0, len(starts) - turns)]
|
|
270
|
-
return set_pinned(message_ids_from(self.thread_id, first))
|
|
271
|
-
|
|
272
|
-
def unpin_last(self, turns: int = 1) -> int:
|
|
273
|
-
"""Release the protection on the last `turns` turns (#89). The
|
|
274
|
-
mirror of pin_last, and what D26's "reversible" premise needed to
|
|
275
|
-
become true: set_pinned's pinned=False branch was written since
|
|
276
|
-
§21 and unreachable until this existed.
|
|
277
|
-
|
|
278
|
-
Same ordinal interface, same clamp (asking for more turns than
|
|
279
|
-
the thread has releases everything -- the intent is unambiguous),
|
|
280
|
-
same return contract (rows actually flipped, so "nothing was
|
|
281
|
-
pinned" reads as zero)."""
|
|
282
|
-
if turns < 1:
|
|
283
|
-
return 0
|
|
284
|
-
starts = turn_start_ids(self.thread_id)
|
|
285
|
-
if not starts:
|
|
286
|
-
return 0
|
|
287
|
-
first = starts[max(0, len(starts) - turns)]
|
|
288
|
-
return set_pinned(message_ids_from(self.thread_id, first),
|
|
289
|
-
pinned=False)
|
|
290
|
-
|
|
291
|
-
@property
|
|
292
|
-
def extra(self) -> dict:
|
|
293
|
-
"""Snapshot of the thread's extra_data (goal mode §18). A copy --
|
|
294
|
-
mutate via set_extra(), which persists write-through like the
|
|
295
|
-
message methods."""
|
|
296
|
-
return dict(self._extra)
|
|
297
|
-
|
|
298
|
-
def set_extra(self, key: str, value) -> None:
|
|
299
|
-
"""Write one extra_data key (value=None deletes), persisting
|
|
300
|
-
immediately so a goal set from the TUI is visible to the next
|
|
301
|
-
run in any shell."""
|
|
302
|
-
update_thread_extra(self.thread_id, key, value)
|
|
303
|
-
if value is None:
|
|
304
|
-
self._extra.pop(key, None)
|
|
305
|
-
else:
|
|
306
|
-
self._extra[key] = value
|
|
307
|
-
|
|
308
|
-
def add_user_message(self, text: str) -> None:
|
|
309
|
-
entry = {"role": "user", "content": text}
|
|
310
|
-
self._messages.append(entry)
|
|
311
|
-
save_message(self.thread_id, role="user", content=text)
|
|
312
|
-
|
|
313
|
-
def add_assistant_message(self, response) -> None:
|
|
314
|
-
"""
|
|
315
|
-
Takes the NORMALIZED ModelResponse from
|
|
316
|
-
core.client.call_model_stream() directly -- not a raw SDK object.
|
|
317
|
-
This is what eliminated the previous Anthropic-only
|
|
318
|
-
`response.raw.content` reach-through in loop.py; all three
|
|
319
|
-
provider branches produce the same ModelResponse shape (.text,
|
|
320
|
-
.tool_calls), so this method never needs to know which provider
|
|
321
|
-
generated it.
|
|
322
|
-
|
|
323
|
-
This used to name `call_model()`, which had no production caller
|
|
324
|
-
(#38) -- so the one sentence telling a reader where this argument
|
|
325
|
-
comes from named a function that never produced one. `raw` went
|
|
326
|
-
with it: it was set only there, so it was None on every live path
|
|
327
|
-
while its comment said it held the SDK response.
|
|
328
|
-
"""
|
|
329
|
-
tool_calls = [
|
|
330
|
-
{"id": tc.id, "name": tc.name, "input": tc.input}
|
|
331
|
-
for tc in response.tool_calls
|
|
332
|
-
]
|
|
333
|
-
entry = {"role": "assistant", "text": response.text, "tool_calls": tool_calls}
|
|
334
|
-
# §44: the turn's reasoning, in the provider's own blocks. Read
|
|
335
|
-
# off the response rather than accumulated from the display
|
|
336
|
-
# deltas, because an Anthropic block carries a signature the
|
|
337
|
-
# prose does not -- see ModelResponse.thinking. Attached to the
|
|
338
|
-
# in-memory entry as well as persisted, so a live turn and a
|
|
339
|
-
# resumed one hand _messages_for_provider the same shape; that is
|
|
340
|
-
# the whole point, and it is why this is one field and not two
|
|
341
|
-
# code paths.
|
|
342
|
-
thinking = getattr(response, "thinking", None)
|
|
343
|
-
if thinking:
|
|
344
|
-
entry["thinking"] = thinking
|
|
345
|
-
self._messages.append(entry)
|
|
346
|
-
# Persist only the assistant-specific payload, not the whole
|
|
347
|
-
# entry -- "role" is already carried by save_message's own
|
|
348
|
-
# `role=` argument, and duplicating it inside `content` is
|
|
349
|
-
# exactly the redundancy that caused the resume-shape bug. The
|
|
350
|
-
# reasoning has its own column for the same reason: it is not
|
|
351
|
-
# part of what the model said.
|
|
352
|
-
save_message(
|
|
353
|
-
self.thread_id,
|
|
354
|
-
role="assistant",
|
|
355
|
-
content={"text": response.text, "tool_calls": tool_calls},
|
|
356
|
-
thinking=thinking,
|
|
357
|
-
)
|
|
358
|
-
|
|
359
|
-
def add_tool_result(self, tool_call_id: str, result: dict) -> None:
|
|
360
|
-
result_text = str(result)
|
|
361
|
-
entry = {"role": "tool", "tool_call_id": tool_call_id, "content": result_text}
|
|
362
|
-
self._messages.append(entry)
|
|
363
|
-
# Persist only the result string. tool_call_id already has its
|
|
364
|
-
# own column (passed below) -- it doesn't need to also be
|
|
365
|
-
# duplicated inside content.
|
|
366
|
-
save_message(self.thread_id, role="tool", content=result_text, tool_call_id=tool_call_id)
|
|
367
|
-
|
|
368
|
-
@property
|
|
369
|
-
def messages(self) -> list[dict]:
|
|
370
|
-
return self._messages
|
|
1
|
+
"""
|
|
2
|
+
core/memory.py
|
|
3
|
+
|
|
4
|
+
Keeps the running message history for one agent conversation, backed by
|
|
5
|
+
real persistence. Stores history in a PROVIDER-NEUTRAL shape -- not
|
|
6
|
+
Anthropic's content-block format, not OpenAI's tool_calls format -- so
|
|
7
|
+
this file has no idea which provider is in use. core/client.py is the
|
|
8
|
+
only place that translates this neutral shape into whatever wire format
|
|
9
|
+
a specific provider's API actually wants, the same way it already
|
|
10
|
+
translates tool schemas per provider.
|
|
11
|
+
|
|
12
|
+
Neutral shapes stored in self._messages:
|
|
13
|
+
user: {"role": "user", "content": "text"}
|
|
14
|
+
assistant: {"role": "assistant", "text": "...", "tool_calls": [
|
|
15
|
+
{"id": "...", "name": "...", "input": {...}}, ...]}
|
|
16
|
+
tool: {"role": "tool", "tool_call_id": "...", "content": "..."}
|
|
17
|
+
(one entry per individual tool result)
|
|
18
|
+
|
|
19
|
+
PERSISTENCE, AND WHY THERE'S NO NORMALIZATION STEP HERE:
|
|
20
|
+
Each add_* method passes storage.save_message() only the PAYLOAD that
|
|
21
|
+
role actually needs -- plain text for user, {"text", "tool_calls"} for
|
|
22
|
+
assistant, a plain result string for tool -- never the whole neutral
|
|
23
|
+
entry dict, which would redundantly re-wrap "role" (and, for tool rows,
|
|
24
|
+
"tool_call_id") a second time inside the persisted content itself.
|
|
25
|
+
storage.get_session_history() reconstructs the exact neutral shape
|
|
26
|
+
above directly, per msg.role, so what comes back on resume is
|
|
27
|
+
identical to what a fresh add_* call would have produced -- no
|
|
28
|
+
post-hoc reshaping step is needed here, for this role or any future one.
|
|
29
|
+
|
|
30
|
+
An earlier version of this file had exactly the bug this design avoids:
|
|
31
|
+
add_assistant_message's persisted shape was nested and lossy on
|
|
32
|
+
resume, a read-side "_normalize_resumed_history()" function was added
|
|
33
|
+
to fix it -- but only for role == "assistant". add_tool_result had the
|
|
34
|
+
identical root cause (same "pass the whole entry dict" pattern) and was
|
|
35
|
+
never touched, because the fix lived one layer above where the actual
|
|
36
|
+
divergence was produced. Fixing what gets WRITTEN, once, here, closes
|
|
37
|
+
this for every role without a matching special case at every point
|
|
38
|
+
it's read back. See tests/test_memory_write_through.py for the
|
|
39
|
+
regression tests (now covering the tool row's `content`, not just its
|
|
40
|
+
`role`/`tool_call_id`, which is exactly the assertion that was missing
|
|
41
|
+
before).
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
from typing import Optional
|
|
45
|
+
from uuid import UUID
|
|
46
|
+
|
|
47
|
+
from storage import (
|
|
48
|
+
create_thread, get_thread, save_message, get_session_history,
|
|
49
|
+
update_thread_extra, latest_checkpoint, pinned_through,
|
|
50
|
+
message_ids_from, set_pinned, turn_start_ids, THREAD_KIND_CHAT,
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
# ROADMAP_v2 §21 (M8). How a compaction summary is introduced to the model.
|
|
54
|
+
#
|
|
55
|
+
# The neutral shape has three roles -- user, assistant, tool -- and no
|
|
56
|
+
# "system" among them, because the system prompt travels separately. A
|
|
57
|
+
# leading USER message is therefore the only form all three providers
|
|
58
|
+
# accept in the message list, and it is where a conversation naturally
|
|
59
|
+
# starts anyway.
|
|
60
|
+
#
|
|
61
|
+
# It is NEVER persisted as a MessageLog row. Doing so would put derived
|
|
62
|
+
# content in an append-only archive whose whole value is being original,
|
|
63
|
+
# and the next compaction would then summarize the previous summary as if
|
|
64
|
+
# it were something the user said -- chaining by accident, on a code path
|
|
65
|
+
# that means to re-derive.
|
|
66
|
+
SUMMARY_PREFIX = (
|
|
67
|
+
"[Summary of the earlier part of this conversation, compacted to save "
|
|
68
|
+
"context. The full history is preserved and unedited; this is what is "
|
|
69
|
+
"being shown to you now.]\n\n"
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class ConversationMemory:
|
|
74
|
+
def __init__(self, thread_id: Optional[UUID] = None,
|
|
75
|
+
kind: str = THREAD_KIND_CHAT) -> None:
|
|
76
|
+
"""`kind` (§27 T1) says what a NEW thread is, and is forwarded to
|
|
77
|
+
storage.create_thread and nowhere else.
|
|
78
|
+
|
|
79
|
+
This class does not learn what a kind means, store it, or read it
|
|
80
|
+
back. It owns active in-run state and must stay unaware of what
|
|
81
|
+
data exists -- that boundary is storage.py's. Ignored when
|
|
82
|
+
`thread_id` is given, because resuming does not reclassify: a
|
|
83
|
+
thread's kind was decided when it was created.
|
|
84
|
+
"""
|
|
85
|
+
# Session-scoped billing (#4): zero on EVERY construction, fresh or
|
|
86
|
+
# resumed -- see record_billed for why this one is deliberately not
|
|
87
|
+
# extra_data like its neighbour.
|
|
88
|
+
self.billed_tokens = 0
|
|
89
|
+
if thread_id is None:
|
|
90
|
+
self.thread_id = create_thread(kind=kind)
|
|
91
|
+
self._messages: list[dict] = []
|
|
92
|
+
self._extra: dict = {}
|
|
93
|
+
self._kind = kind
|
|
94
|
+
else:
|
|
95
|
+
thread = get_thread(thread_id)
|
|
96
|
+
if thread is None:
|
|
97
|
+
raise ValueError(f"No conversation thread found with id {thread_id}")
|
|
98
|
+
self.thread_id = thread_id
|
|
99
|
+
self._extra = dict(thread.get("extra_data") or {})
|
|
100
|
+
self._messages = self._derived_view()
|
|
101
|
+
# The kind fallback (missing column on a database whose ALTER
|
|
102
|
+
# has not run) lives inside get_thread's copy now; resuming is
|
|
103
|
+
# not reclassifying, so the stored kind is simply reported.
|
|
104
|
+
self._kind = thread.get("kind") or THREAD_KIND_CHAT
|
|
105
|
+
|
|
106
|
+
@property
|
|
107
|
+
def kind(self) -> str:
|
|
108
|
+
"""What this thread IS (§27 T1): "chat", "research_pass" or
|
|
109
|
+
"subagent".
|
|
110
|
+
|
|
111
|
+
A deliberate boundary bend, recorded rather than slipped in
|
|
112
|
+
(#43, batch 16). §27 says this class "learns nothing from kind" --
|
|
113
|
+
it forwards the kwarg at creation and ignores it on resume --
|
|
114
|
+
because kind SEMANTICS are storage's to store and the loop's to
|
|
115
|
+
decide. That still holds: nothing here branches on the value.
|
|
116
|
+
What changed is that the loop can now ASK, because batch 16 gave
|
|
117
|
+
it a decision to make from the answer -- which compaction mode a
|
|
118
|
+
re-entered thread runs under derives from what the thread IS
|
|
119
|
+
(research_pass and subagent threads get M6's backstop wherever
|
|
120
|
+
they are resumed), and the memory is the object holding the
|
|
121
|
+
thread. Reporting a stored fact is not interpreting it.
|
|
122
|
+
"""
|
|
123
|
+
return self._kind
|
|
124
|
+
|
|
125
|
+
# -- the derived view (§21) --------------------------------------------
|
|
126
|
+
|
|
127
|
+
def _derived_view(self) -> list[dict]:
|
|
128
|
+
"""What the agent sees this turn: a view computed over the archive,
|
|
129
|
+
not a second copy of it.
|
|
130
|
+
|
|
131
|
+
Three parts, in order:
|
|
132
|
+
1. the latest checkpoint's summary, as a leading user message
|
|
133
|
+
2. pinned rows from inside the span that summary covers (M9),
|
|
134
|
+
verbatim -- the summary skipped them, and one watermark
|
|
135
|
+
cannot say "everything through K except these"
|
|
136
|
+
3. every archive row after the watermark, verbatim
|
|
137
|
+
|
|
138
|
+
A thread that has never been compacted has no checkpoint, so this
|
|
139
|
+
returns exactly what get_session_history() always returned. That
|
|
140
|
+
equivalence is what keeps every pre-§21 caller untouched until the
|
|
141
|
+
trigger first fires on a thread, and it is asserted directly.
|
|
142
|
+
"""
|
|
143
|
+
checkpoint = latest_checkpoint(self.thread_id)
|
|
144
|
+
if checkpoint is None:
|
|
145
|
+
return get_session_history(self.thread_id)
|
|
146
|
+
|
|
147
|
+
watermark = checkpoint["covers_up_to_message_id"]
|
|
148
|
+
summary = {
|
|
149
|
+
"role": "user",
|
|
150
|
+
"content": f"{SUMMARY_PREFIX}{checkpoint['summary_text']}",
|
|
151
|
+
}
|
|
152
|
+
return (
|
|
153
|
+
[summary]
|
|
154
|
+
+ pinned_through(self.thread_id, watermark)
|
|
155
|
+
+ get_session_history(self.thread_id, after_message_id=watermark)
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
def apply_checkpoint(self) -> None:
|
|
159
|
+
"""Rebuild the in-memory view after a compaction was recorded.
|
|
160
|
+
|
|
161
|
+
Deliberately re-reads rather than splicing the summary into the
|
|
162
|
+
list it already holds. The assembly rules (a leading summary,
|
|
163
|
+
pinned re-inclusion, the tail) then live in exactly one place, so
|
|
164
|
+
a mid-run compaction and a resumed thread cannot produce different
|
|
165
|
+
views of the same checkpoint -- which is the divergence a second
|
|
166
|
+
assembly path would eventually introduce.
|
|
167
|
+
"""
|
|
168
|
+
self._messages = self._derived_view()
|
|
169
|
+
|
|
170
|
+
# -- measured context size (§21) ----------------------------------------
|
|
171
|
+
|
|
172
|
+
@property
|
|
173
|
+
def last_input_tokens(self) -> int:
|
|
174
|
+
"""The provider's own count of everything it was last sent on this
|
|
175
|
+
thread, or 0 if it has never been measured.
|
|
176
|
+
|
|
177
|
+
This is what §21's compaction trigger reads. It is exact and it
|
|
178
|
+
comes from the provider rather than from a local tokenizer that
|
|
179
|
+
would have to be right per model -- but it is retrospective, which
|
|
180
|
+
is why the trigger is evaluated after a response and acts before
|
|
181
|
+
the next call.
|
|
182
|
+
|
|
183
|
+
PERSISTED, via the same extra_data write-through goal mode uses.
|
|
184
|
+
§21 says a resumed thread needs a rough character estimate before
|
|
185
|
+
its first call because nothing has been measured yet; carrying the
|
|
186
|
+
last real measurement across the process boundary means the
|
|
187
|
+
estimate is only ever needed for a thread written before this
|
|
188
|
+
section existed.
|
|
189
|
+
"""
|
|
190
|
+
return int(self._extra.get("last_input_tokens") or 0)
|
|
191
|
+
|
|
192
|
+
def record_input_tokens(self, tokens: int) -> None:
|
|
193
|
+
"""Store the measurement from the call that just returned. Ignores
|
|
194
|
+
a zero, which is what D21's raise exists to prevent reaching here
|
|
195
|
+
and what a provider reporting no usage would otherwise write over
|
|
196
|
+
a real earlier number."""
|
|
197
|
+
if tokens:
|
|
198
|
+
self.set_extra("last_input_tokens", int(tokens))
|
|
199
|
+
|
|
200
|
+
# -- session billing (#4) -------------------------------------------------
|
|
201
|
+
|
|
202
|
+
def record_billed(self, tokens: int) -> None:
|
|
203
|
+
"""Accumulate this thread's billed input+output for the SESSION.
|
|
204
|
+
|
|
205
|
+
Deliberately NOT persisted, unlike last_input_tokens beside it:
|
|
206
|
+
the scope the TUI's usage line shows is THREAD-SINCE-RESUME. A
|
|
207
|
+
lifetime total would need a schema column to mean anything (a
|
|
208
|
+
resumed thread would silently restart at zero anyway, reading as
|
|
209
|
+
a reset), and #4's figure exists for relative reasoning about
|
|
210
|
+
this session, not as a ledger.
|
|
211
|
+
"""
|
|
212
|
+
self.billed_tokens += int(tokens or 0)
|
|
213
|
+
|
|
214
|
+
def completed_turns(self) -> int:
|
|
215
|
+
"""How many turns of this thread are already finished (§21 M5/M11).
|
|
216
|
+
|
|
217
|
+
COUNTED FROM THE ARCHIVE, never from `self._messages`. M8 makes a
|
|
218
|
+
checkpoint summary a `role: "user"` message, so a compacted view
|
|
219
|
+
holds one user message that is not a turn -- and this number is
|
|
220
|
+
compared against archive-space turn indices in
|
|
221
|
+
compaction.compactable_span(). Counting the view was §21a's shipped
|
|
222
|
+
defect: the floor came out several turns too low, the computed
|
|
223
|
+
watermark went BACKWARDS, and the second automatic compaction of a
|
|
224
|
+
thread un-compacted it. See tests/test_storage_e2e.py.
|
|
225
|
+
|
|
226
|
+
Lives here rather than in core/loop.py because this is the file
|
|
227
|
+
that owns the thread's persistence -- the loop imports no storage
|
|
228
|
+
at all, and should not start.
|
|
229
|
+
|
|
230
|
+
Called before the first model call of a turn, and every wrapper
|
|
231
|
+
adds the user message first, so the turn about to run is the last
|
|
232
|
+
entry and is excluded. That off-by-one IS the structural floor:
|
|
233
|
+
everything from this index on is the current turn and can never be
|
|
234
|
+
folded.
|
|
235
|
+
|
|
236
|
+
Archive-space also makes the value STABLE for a whole turn. The
|
|
237
|
+
archive never changes under compaction, so a count taken at the top
|
|
238
|
+
of a turn stays correct after a mid-turn compaction rebuilds the
|
|
239
|
+
view; the view-based version silently went stale at exactly that
|
|
240
|
+
point.
|
|
241
|
+
"""
|
|
242
|
+
return len(turn_start_ids(self.thread_id)) - 1
|
|
243
|
+
|
|
244
|
+
# -- pinning (§21) ------------------------------------------------------
|
|
245
|
+
|
|
246
|
+
def pin_last(self, turns: int = 1) -> int:
|
|
247
|
+
"""Mark the last `turns` turns compaction-exempt. Returns how many
|
|
248
|
+
rows were newly pinned.
|
|
249
|
+
|
|
250
|
+
ORDINAL, not an id. §21 keeps MessageLog.id out of the neutral
|
|
251
|
+
shape -- the model never sees one and so cannot name one -- and
|
|
252
|
+
adding it would put a persistence concept into the provider-neutral
|
|
253
|
+
contract the whole memory design rests on, with three translation
|
|
254
|
+
branches then needing to strip it before the wire. "Pin the last N
|
|
255
|
+
turns" needs no id and is how the tool would actually be used.
|
|
256
|
+
|
|
257
|
+
A turn starts at a user message and runs to just before the next
|
|
258
|
+
one, so pinning a turn keeps the question together with its answer
|
|
259
|
+
and any tool results between them. Asking for more turns than the
|
|
260
|
+
thread has pins the whole thread rather than erroring: the intent
|
|
261
|
+
("keep this conversation") is unambiguous and there is nothing to
|
|
262
|
+
clarify.
|
|
263
|
+
"""
|
|
264
|
+
if turns < 1:
|
|
265
|
+
return 0
|
|
266
|
+
starts = turn_start_ids(self.thread_id)
|
|
267
|
+
if not starts:
|
|
268
|
+
return 0
|
|
269
|
+
first = starts[max(0, len(starts) - turns)]
|
|
270
|
+
return set_pinned(message_ids_from(self.thread_id, first))
|
|
271
|
+
|
|
272
|
+
def unpin_last(self, turns: int = 1) -> int:
|
|
273
|
+
"""Release the protection on the last `turns` turns (#89). The
|
|
274
|
+
mirror of pin_last, and what D26's "reversible" premise needed to
|
|
275
|
+
become true: set_pinned's pinned=False branch was written since
|
|
276
|
+
§21 and unreachable until this existed.
|
|
277
|
+
|
|
278
|
+
Same ordinal interface, same clamp (asking for more turns than
|
|
279
|
+
the thread has releases everything -- the intent is unambiguous),
|
|
280
|
+
same return contract (rows actually flipped, so "nothing was
|
|
281
|
+
pinned" reads as zero)."""
|
|
282
|
+
if turns < 1:
|
|
283
|
+
return 0
|
|
284
|
+
starts = turn_start_ids(self.thread_id)
|
|
285
|
+
if not starts:
|
|
286
|
+
return 0
|
|
287
|
+
first = starts[max(0, len(starts) - turns)]
|
|
288
|
+
return set_pinned(message_ids_from(self.thread_id, first),
|
|
289
|
+
pinned=False)
|
|
290
|
+
|
|
291
|
+
@property
|
|
292
|
+
def extra(self) -> dict:
|
|
293
|
+
"""Snapshot of the thread's extra_data (goal mode §18). A copy --
|
|
294
|
+
mutate via set_extra(), which persists write-through like the
|
|
295
|
+
message methods."""
|
|
296
|
+
return dict(self._extra)
|
|
297
|
+
|
|
298
|
+
def set_extra(self, key: str, value) -> None:
|
|
299
|
+
"""Write one extra_data key (value=None deletes), persisting
|
|
300
|
+
immediately so a goal set from the TUI is visible to the next
|
|
301
|
+
run in any shell."""
|
|
302
|
+
update_thread_extra(self.thread_id, key, value)
|
|
303
|
+
if value is None:
|
|
304
|
+
self._extra.pop(key, None)
|
|
305
|
+
else:
|
|
306
|
+
self._extra[key] = value
|
|
307
|
+
|
|
308
|
+
def add_user_message(self, text: str) -> None:
|
|
309
|
+
entry = {"role": "user", "content": text}
|
|
310
|
+
self._messages.append(entry)
|
|
311
|
+
save_message(self.thread_id, role="user", content=text)
|
|
312
|
+
|
|
313
|
+
def add_assistant_message(self, response) -> None:
|
|
314
|
+
"""
|
|
315
|
+
Takes the NORMALIZED ModelResponse from
|
|
316
|
+
core.client.call_model_stream() directly -- not a raw SDK object.
|
|
317
|
+
This is what eliminated the previous Anthropic-only
|
|
318
|
+
`response.raw.content` reach-through in loop.py; all three
|
|
319
|
+
provider branches produce the same ModelResponse shape (.text,
|
|
320
|
+
.tool_calls), so this method never needs to know which provider
|
|
321
|
+
generated it.
|
|
322
|
+
|
|
323
|
+
This used to name `call_model()`, which had no production caller
|
|
324
|
+
(#38) -- so the one sentence telling a reader where this argument
|
|
325
|
+
comes from named a function that never produced one. `raw` went
|
|
326
|
+
with it: it was set only there, so it was None on every live path
|
|
327
|
+
while its comment said it held the SDK response.
|
|
328
|
+
"""
|
|
329
|
+
tool_calls = [
|
|
330
|
+
{"id": tc.id, "name": tc.name, "input": tc.input}
|
|
331
|
+
for tc in response.tool_calls
|
|
332
|
+
]
|
|
333
|
+
entry = {"role": "assistant", "text": response.text, "tool_calls": tool_calls}
|
|
334
|
+
# §44: the turn's reasoning, in the provider's own blocks. Read
|
|
335
|
+
# off the response rather than accumulated from the display
|
|
336
|
+
# deltas, because an Anthropic block carries a signature the
|
|
337
|
+
# prose does not -- see ModelResponse.thinking. Attached to the
|
|
338
|
+
# in-memory entry as well as persisted, so a live turn and a
|
|
339
|
+
# resumed one hand _messages_for_provider the same shape; that is
|
|
340
|
+
# the whole point, and it is why this is one field and not two
|
|
341
|
+
# code paths.
|
|
342
|
+
thinking = getattr(response, "thinking", None)
|
|
343
|
+
if thinking:
|
|
344
|
+
entry["thinking"] = thinking
|
|
345
|
+
self._messages.append(entry)
|
|
346
|
+
# Persist only the assistant-specific payload, not the whole
|
|
347
|
+
# entry -- "role" is already carried by save_message's own
|
|
348
|
+
# `role=` argument, and duplicating it inside `content` is
|
|
349
|
+
# exactly the redundancy that caused the resume-shape bug. The
|
|
350
|
+
# reasoning has its own column for the same reason: it is not
|
|
351
|
+
# part of what the model said.
|
|
352
|
+
save_message(
|
|
353
|
+
self.thread_id,
|
|
354
|
+
role="assistant",
|
|
355
|
+
content={"text": response.text, "tool_calls": tool_calls},
|
|
356
|
+
thinking=thinking,
|
|
357
|
+
)
|
|
358
|
+
|
|
359
|
+
def add_tool_result(self, tool_call_id: str, result: dict) -> None:
|
|
360
|
+
result_text = str(result)
|
|
361
|
+
entry = {"role": "tool", "tool_call_id": tool_call_id, "content": result_text}
|
|
362
|
+
self._messages.append(entry)
|
|
363
|
+
# Persist only the result string. tool_call_id already has its
|
|
364
|
+
# own column (passed below) -- it doesn't need to also be
|
|
365
|
+
# duplicated inside content.
|
|
366
|
+
save_message(self.thread_id, role="tool", content=result_text, tool_call_id=tool_call_id)
|
|
367
|
+
|
|
368
|
+
@property
|
|
369
|
+
def messages(self) -> list[dict]:
|
|
370
|
+
return self._messages
|