@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/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